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.

Since HawkScan 6.0.0, the hawk CLI is a self-contained native binary, so our example below installs it with the hawk CLI install script, with no Docker required. If you’d rather run HawkScan as a Docker container, see the Docker Alternative.

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 install and run the hawk CLI:

hawkscan:
  image: ubuntu:22.04
  # Optional: pin a version (6.0.0 or later). Leave it unset to install the latest release.
  # variables:
  #   HAWK_INSTALL_VERSION: "6.6.0"
  before_script:
    - apt-get update -qq && apt-get install -qq -y curl
    - curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
    - export PATH="$HOME/.hawk/bin:$PATH"
  script:
    - hawk --api-key="hawk.${HAWK_API_ID}.${HAWK_API_SECRET}" scan

In this configuration, before_script installs curl, runs the install script, and adds the install directory, ~/.hawk/bin, to the PATH. The script installs the latest HawkScan release and checks its checksum; to run the same version every time, set HAWK_INSTALL_VERSION in the job’s variables. The script doesn’t change the PATH itself, so keep the export PATH line. GitLab runs before_script and script in the same shell, so the hawkscan job’s script can then run the scan. 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 Alternative

If you’d rather run HawkScan as a Docker container, you will need to enable Docker commands in your pipeline, as described in GitLab’s documentation here:

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

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.

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 Help Center for troubleshooting information around running HawkScan with GitLab and other CI/CD solutions.