CI/CD Integrations | StackHawk Documentation

Automate (CI/CD)

It’s great to know you can scan your services at any time and get a read on potential vulnerabilities. But why not scan every time you check in code? We made it simple to add HawkScan to your CI/CD pipeline. This means you can catch new issues before your code goes live.

This page describes a general approach to integrating HawkScan into your pipeline. But if you’d rather dive right in to configuring your CI/CD system, check below for our getting started guides. If we don’t have your system listed, let us know so we can add it!

AWS Code Services

Atlassian Bamboo

Azure Pipelines

Bitbucket Pipelines

Buildkite

CircleCI

Concourse CI

GitHub Actions

GitLab CI/CD

Harness

Jenkins

Spinnaker

Travis CI

Start Simple

We recommend putting a fast, simple scan into your pipeline initially. You want to iterate quickly until you have your scans consistently working, and then you can add detail. For example, we typically start with a HawkScan configuration such as this:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://example.com
  env: Development

hawk:
  startupTimeoutMinutes: 1
  spider:
    base: false

With this configuration, HawkScan hits the application running at http://example.com in the Development environment, and it makes no attempt to discover routes other than /.

In particular, you will want to remove the hawk.spider.base: false configuration, which prevents HawkScan from crawling your app to find routes.

Once your scan is working well, you can expand your configuration to discover routes, authenticate, and so forth.

Hide your Secrets

You should take care to hide any secrets, such as your StackHawk API key, as well as usernames and passwords you may use for authenticated scans against your application. These should be kept out of source control, in a secure secrets store.

Many build systems have some method for storing secrets and retrieving them as environment variables during a job. For example, Jenkins has a Credentials Plugin, CircleCI has secure Environment Variables, and TravisCI supports secret Environment Variables.

Alternatively you can use general purpose secrets stores such as Hashicorp Vault or AWS Parameter Store.

In your build pipeline, you will extract secrets as environment variables, and configure HawkScan to inject them into the scan at runtime.

Suppose you have three secrets in three variables, HAWK_API_KEY, SCAN_USERNAME, and SCAN_PASSWORD. Here is a simple configuration that imports the username and password, with a default username of “jdoe.”

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://example.com
  env: Development
  authentication:
    loggedInIndicator: "\\Qsigned in as\\E"
    loggedOutIndicator: "\\Qlog in\\E"
    loginPath: /login
    usernameField: User
    scanUsername: ${SCAN_USERNAME:jdoe}
    scanPassword: ${SCAN_PASSWORD}

At runtime, you pass these variables and HAWK_API_KEY to HawkScan via Docker, like so:

docker run -v $(pwd):/hawk -t \
  -e API_KEY=”${HAWK_API_KEY}” \
  -e SCAN_USERNAME=”${SCAN_USERNAME}” \
  -e SCAN_PASSWORD=”${SCAN_PASSWORD}” \
  stackhawk/hawkscan

Requirements

There are really just two requirements for running HawkScan in your pipeline – the hawk CLI (or Docker) and access to your running application.

The `hawk` CLI

As of HawkScan 6.0.0, hawk ships as a self-contained native binary with no Docker or Java dependency, which makes it the simplest way to add HawkScan to most pipelines. Pin a version so your pipeline stays reproducible:

VERSION=6.4.0
ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && PLATFORM="linux-x64" || PLATFORM="linux-aarch64"
curl -L "https://download.stackhawk.com/hawk/${VERSION}/${PLATFORM}/hawk" -o hawk
chmod +x hawk
sudo mv hawk /usr/local/bin/hawk
hawk --api-key="${HAWK_API_KEY}" scan stackhawk.yml

Or skip the OS/arch detection above and let our install script do it for you:

curl -sSf https://download.stackhawk.com/hawk/install.sh | sh

Set HAWK_INSTALL_VERSION to pin a version; leave it unset and the script installs the latest release. HAWK_INSTALL_DIR overrides the install location (default ~/.hawk/bin).

To track the latest release instead of pinning, resolve the version from https://api.stackhawk.com/hawkscan/version:

VERSION=$(curl -fsSL https://api.stackhawk.com/hawkscan/version)

See the StackHawk CLI page for install options on every platform.

Docker (Alternative)

HawkScan is also distributed as a Docker image, so if you’d rather not install the CLI directly, Docker works too:

docker run -v $(pwd):/hawk -t \
  -e API_KEY="${HAWK_API_KEY}" \
  stackhawk/hawkscan

Access to your Running Application

Your build system needs to be able to reach your running application in order to test it. This should be straightforward if your test environment is public, or collocated with your build system. Otherwise you may need to open up access via security groups or firewall rules to allow your build system to reach it.

Summary

That’s all there is to it! Start with a simple scan that will run quickly so you can iterate. Take care to hide your secrets, such as your StackHawk API key. Make sure the hawk CLI (or Docker) is available on your build system. And finally, provide access to your running application.