StackHawk CLI

The StackHawk CLI, hawk, also known has HawkScan, is a command-line tool for performing dynamic application security tests.

The StackHawk CLI has many sub commands, most notably hawk scan, which can be used to perform a DAST vulnerability scan of your running web application, just like using the stackhawk/hawkscan Docker image.

The StackHawk CLI will use valid stackhawk.yml files to configure the scan behavior.

See the usage section to learn more about running CLI commands, and how to optionally configure the scanner with environment variables. Details of specific commands and their controls can be found in the commands section.

QuickStart

Visit our quickstart guide to learn how to complete your first scan with the StackHawk CLI.

Visit the Downloads page to get HawkScan on the Command Line or HawkScan in your Pipeline.

Docker vs. CLI

The HawkScan Docker image contains the StackHawk CLI and the ENTRYPOINT for the container is the hawk scan command.

The StackHawk CLI and HawkScan Docker image are released on the same versioning cycle and are feature compatible.

For many CI/CD use cases, the HawkScan Docker image is the best choice for running scans against your web application. Sometimes, however, the dependency on Docker can be prohibitive–for instance, when running from your local machine or in CI/CD environments without Docker-in-Docker support. Depending on your OS, an entire virtual machine may be required to run Docker.

Docker can also present some networking issues when trying to scan applications listening on localhost, which is common for local web development.

The CLI is ideal for those learning to use HawkScan and are trying to configure their stackhawk.yml configuration files. Most commands including hawk scan will run faster with the CLI than Docker due to lower runtime overhead in most operating systems. This lower overhead makes the CLI well-suited for testing stackhawk.yml configuration files locally, as well as for iterating on complex scan configurations like scripted authentication.

Installation Overview

The StackHawk CLI can be installed by downloading and unzipping a self-contained zip file.

Included are instructions to update the PATH on your preferred shell to include the unzipped directory. Supported shells include:

• Bash
• Linux
• Powershell

Once installed, the CLI tool, hawk, will be available in your terminal. Enter hawk --help in your terminal for sub commands and options.

NOTE: MacOS users can install the CLI using Homebrew as an alternative.

Prerequisites

Java Requirements

HawkScan requires Java to run. If using the zip installer, java must be defined and on the PATH. Other HawkScan installations may supply their own copy of Java for convenience.

• Java version 17 or higher
• a JDK must be installed
  • for example, Temurin
  • a lightweight JRE environment is insufficient

To validate your version of Java, run the following command in your terminal:

shell

java --version

Sample output:

$ java --version
openjdk 17.0.11 2024-04-16

If you get an error when trying to validate your version of Java, ensure that:

1. A JDK is installed
   • If not, visit adoptium.net or install Java using your package manager of choice
2. The Java program’s location is set in your environment’s PATH variable

Java installation examples:

• MacOS (homebrew)
• Linux (bash)
• Windows (chocolatey)
• Windows (winget)

  brew install openjdk
  ## Make sure you follow any post-install instructions in the "Caveats" section of the brew install output.

  sudo apt update && sudo apt upgrade -y
  apt-cache search openjdk
  sudo apt-get install openjdk-17-jdk -y
  

  choco install openjdk
    

  winget install Microsoft.OpenJDK.17
    

Install with zip file

To install the CLI with the zip file, download the file and extract it.

You can download and extract it from the downloads page, or use cURL from the command line:

cURL Example:

curl -v https://download.stackhawk.com/hawk/cli/hawk-4.8.0.zip -o hawk-4.8.0.zip

Then, unzip the file:

unzip hawk-4.8.0.zip

Add the CLI to your PATH

Once the unzipped CLI directory is in place, you’ll need to add it to your path variable:

• $PATH on MacOS / Linux / WSL
• $env:PATH on Windows

• MacOS (zsh)
• Linux (bash)
• Windows (PowerShell)

echo "export PATH=$HOME/hawk-4.8.0:$PATH" >> ~/.zshrc
source ~/.zshrc

echo "export PATH=$HOME/hawk-4.8.0:$PATH" >> ~/.bash_profile
source ~/.bash_profile

$env:PATH="C:\Users\hawky\hawk-4.8.0;$Env:PATH"
##GUI Alternative: Settings-->Edit Environment Variables-->Select System or User-->Path

Note: after updating the PATH, restart your terminal before attempting to run hawk.

MacOS Install

MacOS users may install the StackHawk CLI using our pkg installer, with the CLI zip file or they can install from homebrew.

Install with Pkg (MacOS)

The pkg installer is the most convenient way for MacOS users to install HawkScan. It comes with Java bundled.

You can install it from the downloads page, or from the command line:

# download the .pkg installer
curl -v https://download.stackhawk.com/hawk/pkg/hawk-4.8.0.pkg -o hawk.pkg
# install HawkScan from the .pkg
sudo installer -pkg hawk.pkg -target /Applications

The HawkScan PKG install additionally bundles openjdk 17.0.5 2022-10-18, and will add hawk to the path automatically.

Install with HomeBrew (MacOS)

To install the latest version of the StackHawk CLI with Homebrew, you’ll need to install the StackHawk Tap and the CLI tool hawk.

Tap, then install:

brew tap install

brew tap stackhawk/cli
brew install hawk

Windows Install

Windows users may install the StackHawk CLI using our msi installer or with the CLI zip file and their own copy of Java. From the zip install, the hawk commands will run from the hawk.ps1 file.

NOTE: PowerShell and other Windows terminals may not support UTF-8 encoding by default. HawkScan can still be used, but the terminal output may appear garbled. There are a few workarounds:

• HawkScan Users can toggle the no-color=true command option to disable color and control sequences in HawkScan output.
• Windows users can use the Windows terminal with unicode support.
• Windows users should change their regional language locale to use UTF-8 for worldwide language support. Run intl.cpl, and under the Administrative tab, select Change system locale and enable Beta: Use Unicode UTF-8 for worldwide language support.

Install with MSI (Windows)

The msi installer is the most convenient way for Windows users to install HawkScan.

You can install it from the downloads page, or from powershell with msiexec.exe:

# download and install the .msi installer
msiexec.exe /i https://download.stackhawk.com/hawk/msi/hawk-4.8.0.msi /passive

The HawkScan MSI install additionally bundles openjdk 17.0.5 2022-10-18, and will add hawk to the path automatically.

Usage

Once your PATH has been updated, you can use the hawk command.

With the hawk command available on the path, you can run hawk --help/-h to get help on the available options and commands. The --help/-h flag is supported by all sub commands, for example hawk scan -h will show help for the scan command.

Before going any further run hawk init to set your StackHawk API Key, which is required for many commands.

When running a hawk scan command the API key you supplied to hawk init will be used by reading it from the $HOME/.hawk/hawk.properties file, or it can be supplied as an option on the command line.

hawk --api-key=xxxxx scan

Command Options

Command options in the StackHawk CLI can be supplied from a file or environment variable in addition to the command line option, ie: --option. The property values in $HOME/.hawk/hawk.properties will be used if a command line option is not specified. For example if the hawk --api-key option is not specified the value from the api-key=xxxx property in the $HOME/.hawk/hawk.properties file will be used.

The three forms of options can be used together and will be loaded in the preference order: Command Line Option -> Environment Variable -> hawk.properties

See the table below for command line options:

Base Options

Advanced Scan Options

The StackHawk CLI is designed for flexibility to scan a variety of APIs.

Outbound Proxy Config Options

The StackHawk CLI supports first class support for Enterprise network proxies.

Java Options

The HawkScan CLI is a java application. The JAVA_OPTS environment variable can be specified to include any java application options you want applied to HawkScan command execution.

Commands

The CLI is the top level command hawk which has several sub commands.

hawk

The hawk root command doesn’t take any action on its own but does have options that can be set across multiple sub commands.

Options

• --api-key=xxxxx - StackHawk API Key can be supplied at runtime for any sub command’s usage.
• --num-stored-sessions=4 - The number of sessions to persist in the .hawk/sessions directory. (default: 4)
• --log-roll-size=100mb - The roll size of the log file. (default: 100MB)
• --no-color - Do not use colors in the terminal output.

Example

hawk --no-color scan

hawk init

hawk init will prompt you for a StackHawk API key which will be validated then stored in the file $HOME/.hawk/hawk.properties, which will be created if it does not exist. The property api-key from $HOME/.hawk/hawk.properties will be used whenever a hawk command is run instead of requiring the usage of the --api-key=xxxx option.

Examples Basic usage to create the hawk.properties file

hawk init --api-key=xxxx

Create the hawk.properties file going through an outbound proxy.

hawk init --api-key=xxxx --outbound-proxy-host https://localhost:8080 --outbound-proxy-username $PROXY_USERNAME --outbound-proxy-password $PROXY_PASSWORD --outbound-proxy-auth-scheme BASIC

Options

• --api-key=xxxx - Will skip the terminal prompt and set the api-key property in the $HOME/.hawk/hawk.properties file.

hawk validate config

Validate stackhawk.yml configuration files before running hawk scan. The validate config command can validate a single or multiple files merged together as supported by the scan command.

Examples

Validate stackhawk.yml or stackhawk.yaml file in the current working directory.

hawk validate config

Validate the ./stackhawk-dev.yml yaml file.

hawk validate config ./stackhawk-dev.yml

Validate the configurations of stackhawk.yml and prod/stackhawk.yml files merged together.

hawk validate config stackhawk.yml prod/stackhawk.yml

hawk validate api

Validate the OpenAPI spec included in the stackhawk.yml configuration file.

Examples

Validate an OpenAPI spec included in a stackhawk.yml file.

hawk validate api

Validate an OpenAPI spec included in a specific configuration yml file.

hawk validate api ./stackhawk-dev.yml

hawk validate auth

Validates authentication on your app based upon your stackhawk.yml configuration. Requires HawkScan to be running in daemon mode. Run hawk perch start hawk perch start to start the HawkScan daemon

Options

• --watch - Enters an interactive mode where HawkScan will monitor any changes to you stackhawk.yml config and any authentication scripts configured in the stackhawk.yml.

Examples

Validates authentication configured in a stackhawk.yml file.

hawk validate auth

Validates authentication configured in a specific configuration yml file.

hawk validate auth ./stackhawk-dev.yml

Watches for changes in a specific configuration yml and associated authentication scripts and retries authentication on saving of those files. Press ctrl+c to exit watch mode

hawk validate auth --watch ./stackhawk-dev.yml

hawk register plugin

Registers a Custom Test Script by generating a Plugin Id based on the Application Id in the stackhawk.yml configuration file.

Examples

Registers a Custom Test Script by generating a Plugin Id based on the Application Id in the stackhawk.yml file.

hawk register plugin <plugin-name>

Registers a Custom Test Script by generating a Plugin Id based on an Application Id included in the referenced configuration YAML file that is not using the default stackhawk.yml name.

hawk register plugin <plugin-name> ./stackhawk-dev.yml

hawk list plugin

Lists all the names and IDs of your Custom Test Scripts. By default, the Custom Test Scripts or plugins will be listed based on the Application ID in the stackhawk.yml configuration file.

Examples

Lists names and IDs of plugins based on the Application ID in the stackhawk.yml file.

hawk list plugin

Lists names and IDs of plugins based on the Application ID included in the referenced configuration YAML file that is not using the default stackhawk.yml name.

hawk list plugin ./stackhawk-dev.yml

Lists names and IDs of plugins based on the given Organization ID.

hawk list plugin --organization-id <organization-id>

hawk scan

Scan your running web application or API.

The scan command takes stackhawk.yml configuration files as arguments, each file being merged onto the last in the order they are supplied. By default, the stackhawk.yml file in the current working directory will be used if no arguments are supplied.

When the scanner starts up, it will choose or apply a Scan Policy, which encompass a collection of Vulnerability Check Plugins.

Scan results are coordinated by the specified application ID and environment name.

Options

• --repo-dir - Directory containing your stackhawk.yml files. Config file arguments will be searched for in this directory.
• -e, --env - Set variables in the stackhawk.yml configuration as described here. This argument allows multiples and is of type key/value pair, ie: --env MY_VAR1=value1 --env MY_VAR2=value2 or -e MY_VAR1=value1 -e MY_VAR2=value2.

• --env-file - Set variables in the stackhawk.yml configuration as described here. This argument --env-file=my-env.txt takes a path to a file of key/value pairs with each line containing a pair.

  --env-file example:

    $ cat my-env.txt
    MY_VAR1=value1
    MY_VAR2=value2
  

Advanced Options

See Advanced Scan Options.

stackhawk.yml environment variables

The --env/-e and --env-file arguments can be used to supply variable values to the stackhawk.yml files. For example if your stackhawk.yml file had host: ${APP_HOST:http://localhost:3000} in it using -e APP_HOST=http://dev.example.com that would set the host to http://dev.example.com. In this way the scan command’s -e works similarly to the docker command’s -e. However the hawk command can also use the current environment for the variables as well.

For example, given the following stackhawk.yml configuration, all of the commands listed will resolve the configuration file the same way.

stackhawk.yml

app:
  host: ${APP_HOST:http://dev.example.com}
  env: ${APP_ENV:Test}

Commands:

hawk scan -e APP_HOST=http://localhost:3000 -e APP_ENV=Dev

APP_HOST=http://localhost:3000 APP_ENV=Dev hawk scan

export APP_HOST=http://localhost:3000
export APP_ENV=Dev  
hawk scan

This allows a great degree of flexibility from environment variables to environment files for managing the flexible and secret parts of the stackhawk.yml configuration file.

hawk perch start

Perch manages running HawkScan in a background daemon process rather than running a scan. hawk validate auth and hawk perch browser are available to run in daemon mode.

Options

• --with-chrome - Launches a Chrome browser which will record any traffic of you browsing.
• --with-proxy-info - Outputs the proxy host and port to allow testing tools to proxy through HawkScan
• --app-host - When using --with-chrome, the Chrome browser will start on this web address.

Examples

Starts HawkScan in a background daemon process.

hawk perch start

Launches a Chrome broser at https://localhost:9000 and records user browsiing

hawk perch start --with-chrome --app-host=https://localhost:9000

hawk perch stop

Stops the background HawkScan daemon process.

Options

• --har-file - When specified it will save all browsing history to a specified har file, that can be used for custom scan discovery.

Examples

Stops the HawkScan daemon process.

hawk perch stop

Stops the HawkScan daemon process and saves all browsing recording from launching --with-chrome or from hawk perch browser to a file titled recording.har

hawk perch stop --har-file=recording.har

hawk perch status

Checks if hawk perch is currently running.

Returns status information about the running HawkScan daemon process

hawk perch status

hawk perch browser

Starts a Chrome browser to record traffic through HawkScan to be saved to a file on stop. Requires hawk perch start to be called first.

Options

• --app-host - The Chrome browser will start on the supplied web address.

Launches a Chrome broser that starts at an empty web page.

hawk perch browser

Launches a Chrome broser at https://localhost:9000 and records user browsing.

hawk perch browser --app-host=https://localhost:9000

hawk rescan

Runs a scan based upon the last scan for the Application Id in your stackhawk.yml. A rescan will only scan for the plugins that alerted on vulnerabilities

The scan command takes stackhawk.yml configuration files as arguments, each file being merged onto the last in the order they are supplied. By default, the stackhawk.yml file in the current working directory will be used if no arguments are supplied.

Examples

Runs the most recent scan for an Application based on your stackhawk.yml with only tests that threw alerts

hawk rescan

Runs a scan based on the specific scan id provided and configuration in your stackhawk.yml. Only tests that threw an alert will be rerun.

hawk rescan --scan-id XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX

hawk create app

Create StackHawk applications from the CLI.

hawk create app

hawk create application is also accepted as a valid form of the command.

Running the command without an application name as an argument will run the command in an interactive mode and will prompt the user for an application name and an environment name. If the user belongs to multiple organizations, they will be prompted for an organization ID.

Options

• -n, --name - Application name. Omitting this argument will cause the command to run in interactive mode.
• -e, --env - Environment name. Development by default.
• -o, --org-id - Organization ID. Needed if user is a member of multiple organizations.
• -t, --team-id - Team ID. Needed if user wants to assign an application to a team.

To run the command as part of an automation script, provide the application name and other arguments. Examples:

hawk create app --name "Example App 1" --env Dev

hawk create application --name "Example App 2" --org-id XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxX

hawk create app -n "Example App 3" -e Pre-Production -t XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxX

The ID of the application will be returned as an output of the command:

$ hawk create app --name Example App 1 --env Dev
KaaKaww! Here is your new application ID:
XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxX

NOTE: Team IDs can be retrieved from the URL bar of a browser by navigating to the Team Details page in Settings > User Management > Teams and clicking on the name of the team. Example: https://app.stackhawk.com/teams/team/XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxX

hawk download log

Download and print HawkScan log files to the console. Pass the scan ID as an argument to get the log for any previously run scan. You can review the scan log in order to troubleshoot any issues encountered while scanning.

Example:

hawk download log XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX

The ID of a scan can be found in the URL after clicking an individual scan found on the Scans page. The last portion of the URL is the scan ID. So for the URL https://app.stackhawk.com/scans/XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX, the scan ID would be XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX.

Running the command will output the scan log to the console/STDOUT. The scan log can be saved to a file by using the right angle bracket (>) with the command along with a destination file.

hawk download log XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX > hawkscan.log

hawk version

Print the version of the CLI.

Sample output:

$ hawk version
v4.8.0