Login Start Free Trial Login Start Free Trial
 

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

# 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 section.

Docker Run Command

To set up the environment:

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

To run the scan:

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

Run from your favorite TTY shell.

Command Line Interface 

# 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 section.

Docker Run Command 

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 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.

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 HAWK_GIT_URL environment variable and remove the local mounting flag as such:

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 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 HAWK_GIT_URL=$HAWK_GIT_URL -e HAWK_GIT_REV=my-new-feature-branch --rm -t stackhawk/hawkscan:latest

or

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

The current HawkScan version is: 4.3.0

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

docker pull stackhawk/hawkscan

For the Command Line Interface (CLI): To get the latest version of HawkScan, run this command:

brew upgrade hawk

You can also upgrade your CLI by following the instructions to install with a ZIP file.