Welcome
The StackHawk CLI, hawk
, is a tool for performing dynamic application security tests and managing StackHawk configuration files.
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.
Compared to the Docker image, the StackHawk CLI is a lighter-weight tool for running scans and validating stackhawk.yml files.
The hawk validate config command validates your configuration file(s) using the new
configuration validation specification. This specification
is in the JSONSchema format and is publicly available from SchemaStore.org,
allowing for stackhawk.yml
file validation in your favorite IDE.
See the commands section to learn more about running CLI commands.
QuickStart
Visit our quickstart guide to learn how to complete your first scan with the StackHawk CLI.
Docker vs. CLI
Starting with version 2.0.0
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 will be released on the same versioning cycle and will be 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.
The hawk validate config
command and hawk scan
commands 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
as well as 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
- Java version 11 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 11.0.11 2021-04-20
If you get an error when trying to validate your version of Java, ensure that:
- A JDK is installed
- If not, visit adoptium.net or install Java using your package manager of choice
- The Java program’s location is set in your environment’s PATH variable
Java installation examples:
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
Ajax Spider Requirements:
To use the hawk.spider.ajax option with the CLI, you must (in addition to Java and the CLI itself):
- have Firefox or Chrome installed
- set hawk.spider.ajaxBrowser appropriately.
Install with zip file
To install the CLI with the zip file, download the file and extract it.
To download the CLI zip file, click the following link or use cURL to download it from a terminal command:
File | SHA256 Sum |
---|---|
hawk-3.1.0.zip | 6a74bb05dc91c2008316130f3ee23ec5eb93254fc4cc2dbe34346ab972f07dda |
cURL Example:
curl -v https://download.stackhawk.com/hawk/cli/hawk-3.1.0.zip -o hawk-3.1.0.zip
Then, unzip the file:
unzip hawk-3.1.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
echo "export PATH=$HOME/hawk-3.1.0:$PATH" >> ~/.zshrc
source ~/.zshrc
echo "export PATH=$HOME/hawk-3.1.0:$PATH" >> ~/.bash_profile
source ~/.bash_profile
$env:PATH="C:\Users\hawky\hawk-3.1.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
.
Install with Homebrew (MacOS)
MacOS users may install the CLI using the CLI zip file or the Homebrew package manager.
To install the latest version of the StackHawk CLI with Homebrew,
you’ll need to install the StackHawk Tap and the CLI tool hawk
.
Option 1: Tap, then install, the CLI:
tap
brew tap stackhawk/cli
install
brew install hawk
Option 2: Single command to install tap and CLI:
tap/install
brew install stackhawk/cli/hawk
Now you’re ready to use the hawk
command. See below for usage instructions.
Alternate Versions
You can view and install alternate versions and beta releases of HawkScan with brew
.
These correspond to the same alternate versions available in a Docker context as stackhawk/hawkscan:beta
images.
Once you’ve added the brew tap stackhawk/cli
, you can run brew search
to see all available versions.
Sample output:
$ brew search /hawk.*/
==> Formulae
stackhawk/cli/hawk stackhawk/cli/hawk-beta ✔ stackhawk/cli/hawk-beta@2.0.0
Install with MSI (Windows) (BETA)
Windows Users may install the CLI using the MSI Installer
To install hawk from MSI, click the following link or use msiexec.exe
to install it from a terminal command:
File | SHA256 Sum |
---|---|
hawk-3.1.0.msi | e1cad06b3cbc6aa969f26bd2a76fd71db91ef5cbf19b2168645a475d12e4f809 |
msiexec Install:
msiexec.exe /i https://download.stackhawk.com/hawk/msi/hawk-3.1.0.msi /passive
The HawkScan install additionally bundles openjdk 17.0.5 2022-10-18
, and will add hawk
to the path automatically.
Update the CLI
To get the latest version of the HawkScan CLI:
- Download and unzip the latest CLI zip file
- Update the PATH variable to point to the updated hawk directory (e.g., from
/hawk-2.7.0
to/hawk-2.8.0
)
MacOS Users:
If the CLI was installed using Homebrew, upgrade it with:
bash
brew upgrade hawk
Usage
Once your PATH has been updated, you can use the hawk
command.
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
Windows Users
Windows users should install HawkScan from the msi installer
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 enableBeta: Use Unicode UTF-8 for worldwide language support
.
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.
Additionally, the command line option can be specified as environment variables. See the table below for command line options and their environment variable equivalents:
Examples
Command Line Option | hawk.properties |
Environment Variable |
---|---|---|
--api-key=xxxxx |
api-key=xxxxx |
API_KEY=xxxxx |
--debug |
debug=true |
DEBUG=true |
--hawk-mem=1g |
hawk-mem=1g |
HAWK_MEM=1g |
--no-color |
no-color=true |
NO_COLOR=true |
--proxy-port |
proxy-port=20000 |
PROXY_SERVER_PORT=20000 |
The three forms of options can be used together and will be loaded in the preference order
Command Line Option -> Environment Variable -> hawk.properties
.
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, 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 theapi-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 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.
Options
--repo-dir
- Directory containing yourstackhawk.yml
files. Config file arguments will be searched for in this directory.-e, --env
- Set variables in thestackhawk.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 thestackhawk.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
--session-home
- The working directory for the scan. The default is$HOME/.hawk/sessions
--git-url
- The url of the git repository containingstackhawk.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. ie1g
or1500m
--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--proxy-port
- Starts the underlying scanner on a specific port. Defaults to port 20000.
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.
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 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 vulnerabilites
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 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
v3.1.0