---
title: "Running HawkScan"
description: "Invoke the HawkScan vulnerability scanner in any environment"
url: https://docs.stackhawk.com/hawkscan/running-hawkscan/
---

# Running HawkScan

## Running HawkScan in a Docker Container

The most straightforward way to kick off a HawkScan is through the command line. Start a scan by running the Docker command for your operating system.

Make sure you have first saved your [StackHawk API key](https://app.stackhawk.com/settings/apikeys) to the `HAWK_API_KEY` environment variable, or have run `hawk init` to first save your credentials.

### Windows

Run the following from a PowerShell prompt.

#### Command Line Interface

```powershell
# authenticate with your API key
hawk init
# start HawkScan
hawk scan
```

For additional information on the CLI and how to get it, check out the [StackHawk CLI](https://docs.stackhawk.com/stackhawk-cli/) section.

#### Docker Run Command

To set up the environment:

```powershell
# adds the HAWK_API_KEY environment variable to the PowerShell profile
echo '$env:HAWK_API_KEY="hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx"' >> $profile
# source the profile
. $profile
```

To run the scan:

```powershell
docker run -e API_KEY=$env:HAWK_API_KEY --rm -v ${PWD}:/hawk:rw -t stackhawk/hawkscan:latest
```

> **Note:** **NOTE:** If you see errors such as `file not found` or `cannot start service`, you may need to [enable file sharing](https://docs.docker.com/desktop/settings-and-maintenance/settings/#file-sharing) in Docker.

### Linux/macOS

Run from your terminal.

#### Command Line Interface

```bash
# authenticate with your API key
hawk init
# start HawkScan
hawk scan
```

For additional information on the CLI and how to get it, check out the [StackHawk CLI](https://docs.stackhawk.com/stackhawk-cli/) section.

#### Docker Run Command

```bash
docker run -e API_KEY=$HAWK_API_KEY --rm -v $(pwd):/hawk:rw -t stackhawk/hawkscan:latest
```

To better understand what this command does, let’s break it down:

- `docker run` is how you run a new command in a Docker container
- `--rm` tells Docker to automatically remove the HawkScan container once the scan has completed
- `-v $(pwd):/hawk:rw` will mount the current working directory into the container, giving HawkScan access to local files in the repository, including the `stackhawk.yml` configuration file
- `-t stackhawk/hawkscan:latest` will run the [`stackhawk/hawkscan`](https://hub.docker.com/r/stackhawk/hawkscan) image as a container with a pseudo-TTY for stdout reporting. The `:latest` at the end of the command specifies the HawkScan docker image tagged with the latest update should be pulled down and used.
- `stackhawk.yml` is an optional input into the `source` parameter. It is input into the Docker container to specify the name of the applicable configuration file(s) to use. If it is not provided, Docker will instead find and use the `stackhawk.yml` configuration in the current working directory. You can specify multiple configuration files to merge them, with later files taking precedence.

#### Bash Alias Command

```bash
# supply api keys in an env file; ~/.hawk/hawk.rc for example  
mkdir ~/.hawk
echo "API_KEY=hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx" > ~/.hawk/hawk.rc

# Create a new alias to docker run HawkScan and point to ~/.hawk/hawk.rc
echo "alias hawkscan='docker run --env-file ~/.hawk/hawk.rc \
    -ti -v \`pwd\`:/hawk:rw stackhawk/hawkscan:latest'" >> ~/.bashrc

# Source the alias and run HawkScan, now available as `hawkscan`
source ~/.bashrc
hawkscan stackhawk.yml
```

### Mounting a Git Repository

By default HawkScan will attempt to mount itself from the current working directory. HawkScan can also be mounted from an application’s git repository instead. Any git repository can be used as long as the `stackhawk.yml` file has been checked into the repository project root. To mount HawkScan from a private remote git repository, either a username/password or a Personal Access Token must be provided. You can either supply these via the command line prompt, or directly in the url. For example:

```text
https://username:password@github.com/organization/project.git
```

or

```text
https://username:access_token@gitlab.com/organization/project.git
```

**NOTE:** If 2-Factor Authentication is active on the account you are attempting to clone with, an access token MUST be used in place of the password.

Instructions on how to acquire a Personal Access Token for the major git providers are listed here:

- [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
- [BitBucket](https://confluence.atlassian.com/bitbucketserver0717/personal-access-tokens-1087535496.html)
- [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens)

To supply the git url, simply add a `HAWK_GIT_URL` environment variable and remove the local mounting flag as such:

```bash
docker run -e API_KEY=$API_KEY -e HAWK_GIT_URL=$HAWK_GIT_URL --rm -t stackhawk/hawkscan:latest
```

The above command will check out whichever branch your repository’s HEAD is set to, typically the master or develop branch. To specify a branch or revision, the `HAWK_GIT_REV` environment variable can also be supplied. This variable can take either a branch name or a commit hash and use that version of the code to run HawkScan against. For example:

```bash
docker run -e API_KEY=$API_KEY -e HAWK_GIT_URL=$HAWK_GIT_URL -e HAWK_GIT_REV=my-new-feature-branch --rm -t stackhawk/hawkscan:latest
```

or

```bash
docker run -e API_KEY=$API_KEY -e HAWK_GIT_URL=$HAWK_GIT_URL -e HAWK_GIT_REV=e95571bad0f3b7cd99d62e610460d2518ec2c69f0f85bb35de0036eb6f649ea5 --rm -t stackhawk/hawkscan:latest
```

## Updating HawkScan Version

To ensure you’re running the latest version of HawkScan, update regularly using the commands below.

**Docker:**

```bash
docker pull stackhawk/hawkscan
```

**Homebrew (macOS):**

```bash
brew upgrade hawk
```

**Binary (direct download):** Download the latest binary for your platform from the [downloads page](https://download.stackhawk.com) and replace your existing `hawk` binary.