HawkScan and GitLab

You can run HawkScan in your GitLab pipeline to automate scanning on code check-in. This can be a great addition to an existing pipeline, typically as a step that occurs after deploying your app to an integration environment where HawkScan can reach it.

To follow our example, you will need to enable Docker commands in your pipeline, as described in GitLab’s documentation here.

Secure Your API Key

HawkScan will need your StackHawk API key to submit scan results to the platform. Save your key as a set of masked and protected environment variables in your GitLab project. You will use them to pass your API key to HawkScan. From GitLab Project View, click on Settings, then CI/CD in the left pane to create them.

Our API keys contain an ID component, and a secret component. They take the form:

hawk.<HAWK_API_ID>.<HAWK_API_SECRET>

GitLab can only mask variable values with Base64 characters, which does not include the . character. So you will need to break down your StackHawk API key into its component parts, ID and secret.

For example, if your API key is:

hawk.AAaaAAaaAAaaAAaaAAaa.BBbbBBbbBBbbBBbbBBbb

You should create two variables,

HAWK_API_ID=AAaaAAaaAAaaAAaaAAaa
HAWK_API_SECRET=BBbbBBbbBBbbBBbbBBbb

Mark these variables Protected and Masked in the web console, like so:

Configure Your GitLab Job

At the base directory of your code repository, add a .gitlab-ci.yml pipeline configuration file. Configure it to pull and run HawkScan as a Docker container:

.gitlab-ci.yml

image: docker:19.03.1
services:
  - docker:19.03.1-dind
before_script:
  - docker pull stackhawk/hawkscan
hawkscan:
  script:
    - |
      docker run -v $(pwd):/hawk:rw -t \
        -e API_KEY="hawk.${HAWK_API_ID}.${HAWK_API_SECRET}" \
        -e NO_COLOR=true \
        stackhawk/hawkscan

In this configuration, HawkScan is run as a Docker container in the hawkscan job. Text output color is disabled, and the StackHawk API key is injected from the secure environment variables, HAWK_API_ID and HAWK_API_SECRET. Your pipeline may have other jobs, for instance to build and deploy your application before scanning it.

Docker Configuration Prerequisites

In order to load the scanner’s configuration files, the [runners.docker] section in config.toml needs to be configured to:

1. Run in privileged mode (privileged = true)
2. Contain docker.sock and /builds mappings in the volumes list in config.toml

For example:

[[runners]]
  name = "stackhawk-test"
  url = "https://git.example.org/"
  token = "xxxxxxxxxxxxxxxxxxxx"
  executor = "docker"
    [runners.docker]
      tls_verify = false
      image = "docker:stable"
      privileged = true
      disable_cache = false
      volumes = ["/var/run/docker.sock:/var/run/docker.sock","/cache","/builds:/builds"]
      shm_size = 0

Configure HawkScan

Now create a stackhawk.yml file at the base of your code repository. For our example, we target our Development environment API endpoint, http://example.com.

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 update applicationId with your App ID from StackHawk.

The hawk.spider.base: false element tells HawkScan to limit its scope to a single endpoint, /. That helps keep the scan time short while you work on integrating it into your pipeline. You can expand the scope later.

Run It

Check those two files, .gitlab-ci.yml and stackhawk.yml, into source control, and head over to the GitLab app console to watch your job run. And once the job is complete, check your account at StackHawk to check your scan details!

Troubleshooting

See the CI/CD section of the Help Center for troubleshooting information around running HawkScan with GitLab and other CI/CD solutions.