Login Start Free Trial Login Start Free Trial
 

HawkScan

HawkScan

HawkScan

StackHawk is a dynamic application security testing (DAST) tool built for developers. It has two parts – the HawkScan Scanner and the StackHawk Platform. The scanner can run anywhere - your laptop, a server, Kubernetes, or in your software delivery pipeline. Results are collected on the StackHawk Platform, where you can analyze, communicate, and track findings to resolution.

Prerequisites

HawkScan now supports arm64 architectures, including Apple computers using the M1 CPU from version v2.2.0 forward.

HawkScan can be run either from a Docker Container or from the Command Line Tool.

HawkScan also requires network access to your running application. It works by connecting to your application and testing it with HTTP(S) requests. Web application firewalls, load balancers, intermediate proxies or unstable network conditions may impact scan performance.

The current HawkScan version is: 4.3.0

Docker Container

HawkScan can run as a Docker container. All you need is Docker. Make sure Docker has at least 2 GB memory available if you are running on Mac (Preferences) or Windows (Settings). To scan larger applications, you may need more memory.

HawkScan Docker Images can be found on DockerHub. The HawkScan docker image is built to run on the amd64 and arm64 architectures.

Command Line

HawkScan can run from the command line with the Hawk CLI. The CLI can be downloaded from a ZIP file or installed from Homebrew. Once installed, HawkScan can be run with hawk scan. See the StackHawk CLI section for further details.

Quickstart

Getting started with HawkScan is easy. Just sign up for a free account, and the platform will guide you through setting up and running your first scan.

The getting-started flow on the StackHawk platform will walk you through these steps:

  • Create an API Key to enable the scanner can push results back to the platform.
  • Create an Application so the platform can track scans associated with the same app scanned against different hosts.
  • Create the Configuration File so the scanner can target your specific application, and give the most accurate scan possible.
  • Run a Scan against your running application, attempting known attacks against it.
  • Review Security Findings on the StackHawk platform with expert advice on how to fix them.

Configuration

HawkScan uses a YAML file, stackhawk.yml, to configure the scanner. The StackHawk platform can guide you through creating an initial configuration for each app. Typically, you place this file in the root of your application project directory, where HawkScan looks for it by default.

A basic configuration file looks like this.

stackhawk.yml

app:
  applicationId: XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: https://localhost:3000

There are many configuration settings available to tune HawkScan for your application. You can configure it to authenticate to your app, introspect and scan GraphQL, read your app’s OpenAPI specification, and more.

For more detail, see HawkScan Configuration.

Running the Scan

Running HawkScan takes the form of a Docker command,

docker run <OPTIONS> stackhawk/hawkscan:latest

where <OPTIONS> may include:

  • -v $(pwd):/hawk to mount your working directory so HawkScan can find its configuration file.
  • --rm to remove the container once the scan is complete.
  • -e API_KEY to provide your StackHawk API key to HawkScan as the environment variable API_KEY, so it can send results back to the platform.
  • -t to allocate a psuedo-TTY to HawkScan so it can print status messages to the console in real time.
  • --network host to give HawkScan full access to your host’s network stack. This is useful for scanning apps on the localhost address.

Here are some examples for various platforms:

export HAWK_API_KEY=hawk.XxXXxxxXXxXXXxxxXxXx.XxxxXXXxXxXXXxXxXxxx
docker run --rm -v $(pwd):/hawk:rw -e API_KEY=${HAWK_API_KEY} -t stackhawk/hawkscan:latest
export HAWK_API_KEY=hawk.XxXXxxxXXxXXXxxxXxXx.XxxxXXXxXxXXXxXxXxxx
docker run --rm -v $(pwd):/hawk:rw --network host -e API_KEY=${HAWK_API_KEY} -t stackhawk/hawkscan:latest
set HAWK_API_KEY="hawk.XxXXxxxXXxXXXxxxXxXx.XxxxXXXxXxXXXxXxXxxx"
docker run --rm -v %cd%:/hawk:rw -e API_KEY=%HAWK_API_KEY% -it stackhawk/hawkscan:latest
$env:HAWK_API_KEY="hawk.XxXXxxxXXxXXXxxxXxXx.XxxxXXXxXxXXXxXxXxxx"
docker run --rm -v ${PWD}:/hawk:rw -e API_KEY=$env:HAWK_API_KEY -it stackhawk/hawkscan:latest

Once launched, HawkScan will crawl your application for routes, then probe each route for vulnerabilities.

WARNING: HawkScan is an aggressive scanner. Only run it against apps in environments where data modifications are acceptable. It will try to create, update, and delete information!

HawkScan prints details to the console as it runs to let you know what it is working on, and what it finds. It also streams data to the platform, so you can watch your scan status online in real time.

For more detail on how to run HawkScan, see HawkScan: Running HawkScan.

For more detail on HawkScan console output, see HawkScan: Viewing Scan Results.

Viewing the Scan Results

Once a scan is complete, its findings can be viewed in detail from the scans section of the platform.

Findings are categorized and sorted by their risk severity as High, Medium, or Low. These risk categories are loosely based on the OWASP Risk Rating Methodology.

You can click in to each individual finding to learn what the vulnerability is, what routes it affects, the evidence for it, how to reproduce it, and how to fix it. You can triage findings and optionally create detailed tickets for them in Jira to help track them to resolution.

For more detail on working with HawkScan results in the platform, see StackHawk Platform: Scans.

If you have trouble getting your scan working, please contact StackHawk Support .