Welcome

The StackHawk CLI hawk is a tool for performing dynamic application security tests, managing StackHawk configuration files, and future functionality from StackHawk.

The StackHawk CLI is made up of various sub commands, for example hawk scan, which can be used to perform a scan of your running web application just like using the stackhawk/hawkscan docker image, learn more about the CLI vs. docker container.

The StackHawk CLI is a lighter weight tool to run scans, as well as provides commands to validate stackhawk.yml files. The hawk validate config command will validate your configuration file, or files, using the new configuration validation specification. The specification is in the JSONSchema format and is publicly available via SchemaStore.org which makes stackhawk.yml file validation already enabled in your favorite IDE.

Learn more about the CLI’s commands.

Quickstart

View our quickstart guide on how to complete your first scan with the StackHawk CLI.

Install

The StackHawk CLI can be installed by downloading a self-contained zip file or via homebrew. Once installed the CLI tool hawk will be available in your terminal, checkout hawk --help for sub commands and options.

Prerequisites

The main requirement for the StackHawk CLI is Java version 11 or higher.

Run the following command in your terminal to check your version of java.

$ java --version
openjdk 11.0.11 2021-04-20
OpenJDK Runtime Environment AdoptOpenJDK-11.0.11+9 (build 11.0.11+9)
OpenJDK 64-Bit Server VM AdoptOpenJDK-11.0.11+9 (build 11.0.11+9, mixed mode)

If your output look similar to the above you’re all set!

If you don’t have Java installed visit https://adoptium.net/ or install via brew…

$ brew install openjdk

Make sure you follow any post-install instructions in the “Caveats” section of the brew install output.

NOTE: To use the hawk.spider.ajax option with the CLI you must have firefox or chrome installed and set hawk.spider.ajaxBrowser appropriately.

Install with Homebrew

To install the latest version of the StackHawk CLI via homebrew you’ll need to install the StackHawk Tap and the CLI tool hawk.

NOTE: To install on systems without brew, such as Linux or Windows, follow the Install with Zip file guide.

$ brew tap stackhawk/cli
$ brew install hawk    

Single command to install tap and CLI

$ brew install stackhawk/cli/hawk

Now you’re ready to use the hawk command. See below for usage instructions.

You can also view and install alternate versions and beta releases via brew as you can with the stackhawk/hawkscan:beta docker images. Once you’ve added the brew tap stackhawk/cli you can run to see all available versions.

$ brew search /hawk.*/
==> Formulae
stackhawk/cli/hawk   stackhawk/cli/hawk-beta ✔   stackhawk/cli/hawk-beta@2.0.0

Install with Zip file

To install via the zip file open a terminal in your home directory, download the CLI zip file and extract it.

Example

$ curl -v https://download.stackhawk.com/hawk/cli/hawk-2.8.0.zip -o hawk-2.8.0.zip
$ unzip hawk-2.8.0.zip

Add the CLI to your $PATH

Zsh

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

Bash

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

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

Download

Download the CLI zip file.

Usage

With the hawk command now available 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 via 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. Additionally, the command line option can be specified via an environment variable. Due to the naming constraints on environment variables the equivalent environment variable for the --api-key option would be API_KEY.

Examples

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

Docker vs. CLI

Starting with version 2.0.0 the HawkScan Docker container contains the StackHawk CLI and the ENTRYPOINT for the container is the hawk scan command. The StackHawk CLI and HawkScan Docker container will be released on the same versioning cycle and will be feature compatible.

For many CI/CD use cases the HawkScan Docker container is the best choice for running scans against your web application. Sometimes however, the dependency on Docker can be prohibitive 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. The hawk validate config command and hawk scan commands will run faster via the CLI than Docker due to lower runtime overhead in most operating systems. This makes the CLI well suited for testing stackhawk.yml configuration files as well as iterating on complex scan configurations like scripted authentication.

Commands

The CLI is the top level command hawk which has several sub commands, future versions of the CLI may introduce new 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.
• --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.

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

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, ie:

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

Advanced Options

• --session-home - The working directory for the scan. The default is $HOME/.hawk/sessions
• --git-url - The url of the git repository containing stackhawk.yml config files and other scan and application files. ie: https://username:token@github.com/username/repository.git
• --git-dev - The git branch to use from the --git-url specified.
• --hawk-mem - The maximum memory the scanner can use, the default is 1/3 of available memory. ie 1g or 1500m
• --debug - Enable debug level logging to the StackHawk platform and the logs in the directory $HOME/.hawk/logs.
• --verbose - Enables logs to be printed in the foreground

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 all of the commands listed will resolve the configuration file the same way.

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

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

Example

$ hawk version
v2.0.0

Update CLI Version

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

brew upgrade hawk 

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