Automate (CI/CD)

Continuous Integration with HawkScan

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!

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 – Docker and access to your running application.

Docker

HawkScan is distributed as a Docker image, so you will need Docker available on your build system.

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 Docker is available to your build system. And finally, provide access to your running application.