Search

HawkScan and CircleCI

With the StackHawk Orb, it’s easy to integrate HawkScan into your CircleCI pipeline. 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 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, 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

orbs:
  stackhawk: stackhawk/stackhawk@x.y.z

version: 2.1

workflows:
  scan-remote:
    jobs:
      - stackhawk/hawkscan-remote:
          configuration-files: stackhawk.yml
          host: 'http://example.com'

In this configuration, we define a single workflow, scan-remote, which runs the stackhawk orb job, hawkscan-remote. The job starts its own container and checks out your code, including the HawkScan configuration described below. Then HawkScan runs from within the container and sends your scan results back to the StackHawk platform. The StackHawk API key is automatically pulled 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://example.com
  env: Development

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. The text output from the job results in CircleCI will contain a link to your scan results in the StackHawk app.

BONUS: Local Scanning

The StackHawk orb has a second job option called hawkscan-local, which runs on a machine instance rather than a container. This job accepts a list of steps as a parameter, which allows you to optionally stand up local services on the CircleCI build machine before running the scan.

As an example, the following CircleCI and StackHawk configurations will stand up an nginx Docker container, and scan it.

.circleci/config.yml

orbs:
  stackhawk: stackhawk/stackhawk@x.y.z

version: 2.1

workflows:
  scan-local:
    jobs:
      - stackhawk/hawkscan-local:
          docker-network: scan_net
          steps:
            - run:
                name: Create scan_net Network
                command: docker network create scan_net
            - run:
                name: 'Run Local Test Instance, nginx_test, on the scan_net Network'
                command: docker run --rm --detach --network scan_net --name nginx_test nginx

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://nginx_test
  env: Development

hawk:
  startupTimeoutMinutes: 1
  spider:
    base: false