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)
#
# Authentication configuration for scanning as a user.
# Enabling will force the scanner to scan as an
# authenticated user of your app.
# authentication:
# # 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)
# # Username password based authentication method.
# usernamePassword:
# # POST authentication credentials as application/x-www-form-urlencoded
# # Set type to JSON to POST as application/json.
# type: FORM
# # The route to POST credentials to authenticate as a user
# loginPath: /login # (required)
# # The route that serves the login form. The anti-csrf parameter
# # returned from a GET request will be extracted from the response.
# loginPagePath: /login # (optional)
# # The username field name in your authentication payload.
# usernameField: session[email] # (required)
# # The password field name in your authentication payload.
# passwordField: session[password] # (required)
# # The username to authenticate as when scanning
# scanUsername: ${SCAN_USERNAME} # (required)
# # The password of the scanUsername
# scanPassword: ${SCAN_PASSWORD} # (required)
# # Other request parameters that may be required by your log in payload
# otherParams: # (optional)
# - name: utf8
# val: "✓"
# - name: "session[remember_me]"
# val: "0"
# # Maintain authorized session via cookie.
# cookieAuthorization:
# # Names of cookies used to track a users session
# cookieNames:
# - "_toy_app_session"
# # A path and criteria for asserting authentication is working correctly.
# # The path should be a protected route that can only be accesed
# # by an authenticated user. Before running a scan this path will be
# # requested to verify authenticated access is working correctly.
# testPath:
# # Match criteria against the HEADERs. Set to BODY to match against
# # reponse body instead.
# type: HEADER
# # The protected path to issue a GET request to.
# path: /profile
# # A regex to match against that will indicate a successful authorized
# # request. Configure fail criteria to match against a failed
# # authorized request. Example: fail:".*302.*Location.*/login.*"
# success: ".*200.*"
# # Externally supplied authorization token.
# # Use as an anternative to usernamePassword authentication
# external:
# # A token type external credential.
# # Set to COOKIE to supply an externally sourced cookie
# type: TOKEN
# # The value of the token passed as an environment variable at runtime.
# # When type=COOKIE the value format should be <cookie-name>=<cookie-value>
# value: ${AUTH_TOKEN}
# # Describe how to extract your apps authorization token.
# # This should only be used with tokenAuthorization
# tokenExtraction:
# # The type of extraction to use. TOKEN_PATH is the path to the token in
# # the JSON payload returned from usernamePassword authenticsation.
# # Set to HEADER if youtr authorizarion token is retuned as a response header.
# type: TOKEN_PATH
# # The path to the token or name of the header.
# value: "auth.token"
# # Use token based authorization instead of cookie based.
# # Tokens are passed on all requests to maintain authorized access
# # to your application
# tokenAuthorization:
# # The way to pass the token on requests. Set to QUERY_PARAM
# # to pass your token as psrt of the query string instead of a header.
# type: HEADER
# # The name of the header or query param.
# value: Authorization
# # The token type which will be prepended to your authorization header.
# # ie: Authorization: Bearer <token>
# # Leave undefined if not applicable.
# tokenType: Bearer
# # 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.