---
title: "HawkScan"
description: "Install and run HawkScan to find security vulnerabilities in your web applications and APIs. Docker and CLI setup, configuration, and results."
url: https://docs.stackhawk.com/hawkscan/
---

# HawkScan

StackHawk is a dynamic application security testing (DAST) tool built for developers. It has two parts – the [HawkScan Scanner](https://docs.stackhawk.com/hawkscan/running-hawkscan/) and the [StackHawk Platform](https://docs.stackhawk.com/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.

The current HawkScan version is: **6.6.0**

## Prerequisites

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.

### Docker Container

HawkScan can run as a Docker container. All you need is [Docker](https://docs.docker.com/get-docker/). Make sure Docker has at least 2 GB memory available if you are running on Mac ([Preferences](https://docs.docker.com/desktop/install/mac-install/#system-requirements)) or Windows ([Settings](https://docs.docker.com/desktop/install/windows-install/#system-requirements)). To scan larger applications, you may need more memory.

HawkScan Docker Images can be found on [DockerHub](https://hub.docker.com/r/stackhawk/hawkscan). 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 as a native binary](https://docs.stackhawk.com/stackhawk-cli/) or [installed from Homebrew](https://docs.stackhawk.com/stackhawk-cli/#install-with-homebrew-macos). Once installed, HawkScan can be run with `hawk scan`. See the [StackHawk CLI](https://docs.stackhawk.com/stackhawk-cli/) section for further details.

## Quickstart

Getting started with HawkScan is easy. Just [sign up](https://auth.stackhawk.com/signup) 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.

```yaml title="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](https://docs.stackhawk.com/hawkscan/configuration/).

### Running the Scan

Running HawkScan takes the form of a Docker command,

```bash
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:

**Tab: Bash**

```bash
export HAWK_API_KEY=hawk.XxXXxxxXXxXXXxxxXxXx.XxxxXXXxXxXXXxXxXxxx
docker run --rm -v $(pwd):/hawk:rw -e API_KEY=${HAWK_API_KEY} -t stackhawk/hawkscan:latest
```

**Tab: Linux**

```bash
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
```

**Tab: Windows CMD**

```powershell
set HAWK_API_KEY="hawk.XxXXxxxXXxXXXxxxXxXx.XxxxXXXxXxXXXxXxXxxx"
docker run --rm -v %cd%:/hawk:rw -e API_KEY=%HAWK_API_KEY% -it stackhawk/hawkscan:latest
```

**Tab: PowerShell**

```powershell
$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.

> **Error:** 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](https://app.stackhawk.com), so you can watch your scan status online in real time.

For more detail on how to run HawkScan, see [HawkScan: Running HawkScan](https://docs.stackhawk.com/hawkscan/running-hawkscan/).

For more detail on HawkScan console output, see [HawkScan: Viewing Scan Results](https://docs.stackhawk.com/hawkscan/viewing-scan-results/).

### Viewing the Scan Results

Once a scan is complete, its findings can be viewed in detail from the [scans](https://app.stackhawk.com/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](https://docs.stackhawk.com/platform/scans/).

> **Note:** If you have trouble getting your scan working, please [contact StackHawk Support](https://docs.stackhawk.com/support/).