Getting Started

Kick off your first scan in 5 minutes or less

Quickstart

HawkScan is a dynamic application vulnerability scanner that runs in a Docker container. See the System Requirements section for more information on first getting started with Docker. Below are the steps to get going with HawkScan:

  1. Config File: Create the stackhawk.yml file in your project directory. Start scanning right away with default configuration or customize to improve your scans.

  2. Run the Scan: Kick off HawkScan with a simple Docker command.

  3. Secure Your App: View the scan results and begin addressing vulnerabilities in your application with terminal and HTML output. StackHawk web app coming soon!

The docs currently support getting HawkScan up-and-running in a local development environment.

Configuration

HawkScan uses a YAML configuration file to supply operational settings to the scanner. To get started, copy the following into a file named stackhawk.yml in the root of your web app project directory. Replace URL_OF_YOUR_APP with the url of your locally running web app (ex: http://localhost:3000).

stackhawk.yml
app:
# The url of your application to scan
host: URL_OF_YOUR_APP # (required)
# Our scanner's capability is still in Alpha; If we notice a bug we'll use this email to reach out or provide a fix.
# We will never use this contact for marketing purposes.
contactEmail: your_email@company.com # (optional)
# The risk level of the app
riskLevel: MEDIUM # (optional)
# The type of data sensitivity the web app mantains
appDataType: PII # (optional)
# The names of your session tokens aka: cookie names
# sessionTokens: # (optional)
# - "_toy_app_session"
# # The name of your anti csrf parameter
# antiCsrfParam: authenticity_token # (optional)
#
# # Form POST based authentication configuration for scanning as a user.
# # Enabling will force the scanner to scan as an
# # authenticated user of your app.
# # Autenticated requests will pass cookies received from the form POST
# # to maintain authentication.
# formAuth: # (optional)
# # The route to a form POST to authenticate a user
# loginPath: /login # (required)
# # The route to logout a user
# logoutPath: /logout # (required)
# # The username field name in your authentication form
# usernameField: session[email] # (required)
# # The password field name in your authentication form.
# passwordField: session[password] # (required)
# # A regex to match against http responses to determine if the scan user is
# # still logged in to your app
# loggedInIndicator: "\\QLog out\\E" # (required)
# # A regex to match against http responses to determine if the scan user is
# # logged out of your app
# loggedOutIndicator: "\\QLog in\\E" # (required)
# # Other parameters that may be required by your log in form
# otherParams: # (optional)
# - name: utf8
# val: "✓"
# - name: "session[remember_me]"
# val: "0"
# # The username to authenticate as when scanning
# scanUsername: ${SCAN_USERNAME} # (required)
# # The password of the scanUsername
# scanPassword: ${SCAN_PASSWORD} # (required)
# # JSON POST based authentication configuration for scanning as a user.
# # Enabling will force the scanner to scan as an
# # authenticated user of your app.
# # Authenticated requests will use the token returned from the POST
# # request to loginPath, and identifed by payloadTokenPath,
# # as the Authorization header to requests.
# # The Authorization header is in the form of a Bearer token ie:
# # Authorization: Bearer <token>
# jsonAuth: # (optional)
# # The route to a form POST to authenticate a user
# loginPath: /login # (required)
# # The username field name in your authentication form
# usernameField: session[email] # (required)
# # The password field name in your authentication form.
# passwordField: session[password] # (required)
# # The username to authenticate as when scanning
# scanUsername: ${SCAN_USERNAME} # (required)
# # The password of the scanUsername
# scanPassword: ${SCAN_PASSWORD} # (required)
# # The path to the field in the returned JSON payload that
# # will contain the authentication token passed as an Authorization
# # header on requests.
# payloadTokenPath: "authentication.token" # (required)
# # The name of the token in the Authorization header.
# # ie: Authorization: Bearer <token>
# # Bearer is the default if not supplied.
# authTokenName: Bearer # (optional)
# # Other parameters that are required to be present in the JSON
# # payload when POSTing to the loginPath
# otherParams: # (optional)
# - name: utf8
# val: "&#x2713;"
# - name: "rememberMe"
# val: "true"
# # Path to openapi 2 spec file or inline openapi 2 spec yaml
# api: "openapi.json" # (optional)
#hawk:
# # Web crawler / spider configuration
# spider:
# # Enable the base spider for discovering your app's routes
# base: true # (default)
# # Enable the ajax spider for discovering your single page app
# ajax: false # (default)
# # Maximum time for spider to discover routes in your app
# maxDurationMinutes: 2 # (default)
# # Maximum time to wait for the scanner to start up
# startupTimeoutMinutes: 5 # (default)

Additional configuration settings and a detailed stackhawk.yml example can be found on the Configuration page.

Running the Scan

To scan your running web application, execute the following docker command:

docker run --rm -v $(pwd):/hawk:rw -it stackhawk/hawkscan:latest

As the scan runs you'll see the scan progress output on the terminal. This will use the latest stackhawk/hawkscan container image for the scan.

HawkScan will first crawl your web application, discovering and collecting routes as it runs. It will then attempt known and applicable web penetration techniques to the pages it finds, collecting metadata about each web request and recording the results along the way.

HawkScan is a no-joke application vulnerability scanner. It will attempt to find any flaws in your scanned application and will make many requests through discovered forms and inputs, including making POST, PUT, DELETE and UPDATE http requests to your application host. Make sure to only run HawkScan in environments you manage and are comfortable with being modified by HawkScan.

Additional runtime settings and example development scenarios can be found on the Running HawkScan page.

Viewing the Scan Results

Upon completion, the scanning application will write out terminal results and a hawkscan-results.html file containing the found vulnerabilities. You can open the html file in any browser to view its contents.

The results will present the total number of found vulnerabilities across all pages in the application, as well as the total number of unique vulnerabilities it finds throughout your app. Vulnerabilities are categorized and sorted by their risk severity as High, Medium, or Low.

A sample of the terminal scan results is included below:

1) Cross Site Scripting (Reflected)
Risk: High
Confidence: Medium
Cheatsheet: https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.md
Paths (1):
POST /searchresults
2) Path Traversal
Risk: High
Confidence: Medium
Cheatsheet: https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Input_Validation_Cheat_Sheet.md
Paths (1):
POST /microposts
3) Cross-Domain JavaScript Source File Inclusion
Risk: Low
Confidence: Medium
Paths (43):
GET /users
GET /users/2
GET /users/2/edit
GET /users/2/followers
GET /users/2/following
... 38 more in details

In the future, scan results will be available via the StackHawk web app. StackHawk currently collects anonymized scan results to help improve HawkScan.

For more information on how to understand and follow-up on HawkScan results, see the Viewing Scan Results page.

System Requirements

HawkScan runs in a Docker container. The scanning application can be run on any environment with a running Docker Engine. This makes Docker the only runtime dependency needed for running HawkScan.

Docker Engine - Community is available on most common platforms, including:

Because HawkScan is running in a docker container, it will only use as much compute resources as you allocate to the Docker Engine. To run with reasonable performance, your Docker engine should be configured to use a minimum of:

  • 2 CPUs

  • 2 Gigabytes Memory

Larger web applications and differently configured scan settings may require additional compute resources allocated to the Docker Engine.

If you encounter issues with your scan, see the complete config details, or reach out to us at support@stackhawk.com.