HawkScan

Getting Started

Welcome!

In order to run HawkScan and view results, you’ll need to create a StackHawk account and generate an API key and Application ID for your YAML.

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:

  • Create an Api Key and Application: Signup for the web app to obtain an Api Key and create your first app.
  • Config File: Create the stackhawk.yml file in your project directory. Start scanning right away with default configuration or customize to improve your scans.
  • Run the Scan: Kick off HawkScan with a simple Docker command.
  • Secure Your App: View the scan results and begin addressing vulnerabilities in your application with terminal and the StackHawk WebApp. Sign up for access

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 (example: http://localhost:3000) and the applicationId and env with the values from the StackHawk platform.

stackhawk.yml

app:
  # An applicationId obtained from the StackHawk platform.
  applicationId: kkAAAKAW-kAWW-kkAA-WWwW-kAAkkAAAAwWW # (required)
  # The environment for the applicationId defined in the StackHawk platform.
  env: Development # (required)
  # The url of your application to scan
  host: ${authority}://${host}:${port} # https://localhost:3000 (required)
  # The risk level of the app
  riskLevel: MEDIUM # (default)
  # The type of data sensitivity the web app maintains
  appDataType: PII # (default)
# Regex paths you want excluded entirely from the scan
#  excludePaths: # (optional)
#    # - "/assets/.*"
#    # - "/dont-scan-this-page"
# Regex paths you want specifically included for the scan
#  includePaths: # (optional)
#    # - "/api/v1/.*"
#    # - "/also-scan-this-page"
#  # The names of your session tokens aka: cookie names
#  sessionTokens: # (optional)
#    # - "_toy_app_session" (required)
#  # 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: # (optional)
#    # 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: # (optional)
#      # POST authentication credentials as application/x-www-form-urlencoded
#      # Set type to JSON to POST as application/json.
#      type: # FORM (required)
#      # The route to POST credentials to authenticate as a user
#      loginPath: # /login (required)
#      # The route that serves the login form. The anti-csrf parameter
#      # 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)
#      # returned from a GET request will be extracted from the response.
#      loginPagePath: # /login (optional)
#      # Other request parameters that may be required by your log in payload
#      otherParams: # (optional)
#        # - name: utf8 (required)
#        #   val: "✓" (required)
#        # - name: "session[remember_me]"
#        #   val: "0"
#    # Maintain authorized session via cookie.
#    cookieAuthorization: # (optional)
#      # Names of cookies used to track a users session
#      cookieNames: # (required)
#        # - "_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: # (optional)
#      # Set to BODY to match against response body instead of HEADER.
#      type: # HEADER (default)
#      # Protected path to send GET/POST request validation.
#      path: # /profile (required)
#      # 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.*" (required)
#      # The request method for authentication validation.
#      # GET/POST/PUT
#      requestMethod: # GET (default)
#      # The request body for POST/PUT authentication validation.
#      requestBody: # foo=bar&hawk=foo  (optional)
#    # Externally supplied authorization token.
#    # Use as an alternative to usernamePassword authentication
#    external: # (optional)
#       # A token type external credential.
#       # Set to COOKIE to supply an externally sourced cookie
#       type: # TOKEN (required)
#       # 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} (required)
#    # 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 authentication.
#       # Set to HEADER_NAME if your authorization token is returned as a response header.
#       type: # TOKEN_PATH (required)
#       # The path to the token or name of the header.
#       value: # "auth.token" (required)
#    # Use token based authorization instead of cookie based.
#    # Tokens are passed on all requests to maintain authorized access
#    # to your application
#    tokenAuthorization: # (optional)
#      # The way to pass the token on requests. Set to QUERY_PARAM
#      # to pass your token as part of the query string instead of a header.
#      type: # HEADER (required)
#      # The name of the header or query param.
#      value: # Authorization (required)
#      # The token type which will be prepended to your authorization header.
#      # ie: Authorization: Bearer <token>
#      # Leave undefined if not applicable.
#      tokenType: # Bearer <token> (optional)
#  # Path to openapi 2 spec file or inline openapi 2 spec yaml
#  # Note: default '/' == '{app.host}/openapi.json'
#  api: # "/myopenapi.json" (optional)
#  graphqlConf:
#    # GraphQL introspection path
#    schemaPath: /
#    # Request method to use for queries [POST|GET]
#    requestMethod: POST
#    # Request method to use for queries [ALL|QUERY|MUTATION]
#    operation: ALL
#    # Set the max length of URIs when generating GET queries
#    uriMaxLength: 4000
#    # Provide the relative path to a JSON formatted schema file
#    # Note: also requires schemaPath to be set if not at the standard /graphql endpoint  
#    filePath: schema.json
#    # Set the request parameters for introspection and enumeration
#    introspection:
#      # Number of requests to make at each interval
#      requestsPerCycle: 20
#      # Delay interval for request cycles
#      requestDelay: 1000
## Parameters affecting scanner runtime.
#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)
#  # Minimum alert level for a scan fail result:
#  # LOW|MED|HIGH
#  failureThreshold: # HIGH (optional)
#
## Parameters for addOns and custom scripts
#hawkAddOn: # (optional)
#  # Replacer addOn configuration
#  replacer: # (optional)
#    # List of rules for the Replacer addOn
#    rules: # (optional)
#      # Rules begin with _matchString_ key.
#      # - matchString: 'User-Agent.*' # (required)
#      #  replacement: 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36' # (required)
#      # - matchString: 'Content-Type.*'
#      #   replacement: 'Content-Type: application/json'
#  # Custom scripts configurtation
#  scripts: # (optional)
#    # Scripts begin with the _name_ key.
#    # - name: # 'json-auth.js' (required)
#    #   type: # 'authentication' (required)
#    #   path: # ${PWD}/../zap_scripts (required)

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

Running the Scan

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx -it stackhawk/hawkscan:latest
docker run --rm -v %cd%:/hawk -e API_KEY=hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx -it stackhawk/hawkscan:latest
docker run --rm -v ${PWD}:/hawk -e API_KEY=hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx -it stackhawk/hawkscan:latest
docker run --rm -v $(pwd):/hawk:rw -network host -e API_KEY=hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx -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 send detailed results to the StackHawk Platform containing the found vulnerabilities.

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

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.