Running HawkScan

Running HawkScan through the Docker CLI

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.

Windows

Run the following from a PowerShell prompt.

To set up the environment:

mkdir "~\.hawk"
echo '$env:HAWK_API_KEY="hawk.kkAAAKAWkAWWkkAAWWwW.kkAAAKAWkAWWkkAAWWwW"' > $home\.hawk\hawk.ps1

To run the scan:

& "~\.hawk\hawk.ps1"
docker run -e API_KEY=$env:HAWK_API_KEY --rm -v ${PWD}:/hawk:rw -t stackhawk/hawkscan:latest

NOTE: If you see errors such as file not found or cannot start service, you may need to enable shared folders in Docker.

Linux/OSX

PLEASE NOTE: HawkScan currently does not work on Apple computers using the M1 CPU. If you have a Mac with the M1 chip, we recommend running HawkScan on another computer, such as an Intel based Mac, or an Intel-based Linux machine.

Docker Run Command

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

Bash Alias Command

# supply api keys in an env file; ~/.hawk/hawk.rc for example  
mkdir ~/.hawk
echo "API_KEY=hawk.kkAAAKAWkAWWkkAAWWwW.kkAAAKAWkAWWkkAAWWwW" > ~/.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:

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

or

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:

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

docker run -e API_KEY=$API_KEY -e GIT_URL=$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 specifiy a branch or revision, the 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:

docker run -e API_KEY=$API_KEY -e GIT_URL=$GIT_URL -e GIT_REV=my-new-feature-branch --rm -t stackhawk/hawkscan:latest

or

docker run -e API_KEY=$API_KEY -e GIT_URL=$GIT_URL -e GIT_REV=e95571bad0f3b7cd99d62e610460d2518ec2c69f0f85bb35de0036eb6f649ea5 --rm -t stackhawk/hawkscan:latest

Updating HawkScan Version

The current HawkScan version is: 0.11.14

To get the latest version of HawkScan, run this docker command:

docker pull stackhawk/hawkscan 

Docker Command Deep Dive

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 image as a container with a psuedo-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.