HawkScan and CircleCI

It’s easy to integrate StackHawk scanning into your pipeline with CircleCI. The basic steps are:

1. Add your code repository as a CircleCI Project
2. Secure your API key as an environment variable in your CircleCI Project
3. Configure your CircleCI job by adding a .circleci/config.yml file to your project repository
4. Configure HawkScan with a stackhawk.yml file

Create your CircleCI Project

If you haven’t already, set up your code repository as a CircleCI Project. From the CircleCI web app, click ADD PROJECTS from the left pane, and select your code repository.

Secure Your API Key

When you signed up on StackHawk, you created an API key. To keep it a secret, copy it to the Environment Variables for your project. From within your CircleCI Project View in Jobs or Workflows, click on Project Settings icon (⚙️) at the top right of your browser, and then select Environment Variables from the left pane. Add your StackHawk API key as a variable called HAWK_API_KEY.

Configure Your CircleCI Job

At the base directory of your code repository, add a .circleci/config.yml file to configure your CircleCI project to run HawkScan. An example is provided below.

.circleci/config.yml

version: 2.1
jobs:
  build:
    machine: true
    steps:
      - checkout
      - run:
          name: Run HawkScan
          command: |
            docker run --volume $(pwd):/hawk --tty \
              --env API_KEY="${HAWK_API_KEY}" \
              --env NO_COLOR=true \
              stackhawk/hawkscan

In this configuration, we define a single job, build, which uses a standard machine executor. In the checkout step, our code is checked out, including the HawkScan configuration described below. Then, HawkScan runs as a Docker container, with text output color disabled. The StackHawk API key is injected from the environment variable, HAWK_API_KEY.

Configure HawkScan

At the base directory of your code repository, create a stackhawk.yml appropriate for scanning your application. Create a minimal config pointing to your development environment API endpoint.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://dev.example.com
  env: development
  contactEmail: integration-test@example.com
hawk:
  startupTimeoutMinutes: 1
  spider:
    base: false

Replace the host entry with your test endpoint, and replace applicationId with your App ID from StackHawk.

Run It

Check those two files into source control, and head over to the CircleCI app console to watch your job run. And once CircleCI is done, check your account at StackHawk to review your scan details!