HawkScan and Azure Pipelines Using Docker containers

Integrating HawkScan tests into your Azure pipelines using the Docker containers, requires the following tasks:

1. Add the azure-pipelines.yml configuration file in your repository to run HawkScan.
2. Add a stackhawk.yml configuration file to your repository to configure HawkScan.

Before you Begin

Before you can use HawkScan to test your applications in Azure pipelines, you must first have the following:

To run HawkScan, you must have a StackHawk account, a StackHawk API Key, and a Stackhawk application ID for your application.

NOTE: For instructions on generating a StackHawk API Key, see Get an API Key, and for instructions on getting an application ID, see Get an Appplication ID.

Configure Azure Pipeline

Using the HawkScan Docker image you can test remote or locally running web applications. You can also scan your applications running from Docker containers using a Docker bridge network with either docker run commands or using Docker Compose.

The following configurations tell Azure Pipelines to run a single job which runs HawkScan as a Docker container. The job will pass the StackHawk API key to HawkScan as an environment variable, HAWK_API_KEY, taken from a secret Pipeline Variable.

See Set variables in pipeline in the Azure DevOps documentation for more information on adding a secret Pipeline Variable.

Remote running application configuration:

azure-pipelines.yml

pool:
  vmImage: 'ubuntu-latest'

jobs:
  - job: Remote_Scan
    steps:
      - script: >
          docker run -v $(pwd):/hawk:rw -t
          -e API_KEY="${HAWK_API_KEY}"
          stackhawk/hawkscan
        displayName: Run HawkScan
        env:
          HAWK_API_KEY: $(hawk_api_key)

Locally running NGINX application configuration:

azure-pipelines.yml

pool:
  vmImage: 'ubuntu-latest'

jobs:
  - job: Local_Scan
    steps:
      - script: docker run --detach --publish 8080:80 nginx
        displayName: Start Nginx
      - script: >
          docker run -v $(pwd):/hawk:rw -t
          -e API_KEY="${HAWK_API_KEY}"
          stackhawk/hawkscan
        displayName: Run HawkScan
        env:
          HAWK_API_KEY: $(hawk_api_key)

Scan Your Application on a Docker Bridge Network

Another way to test your application is to run it in a container and scan it on a Docker bridge network. The following example uses Docker Compose to define a set of containers that can address one another by name using a declarative YAML configuration.

Add a Docker Compose configuration file, docker-compose.yml, to the root of your repository, similar to the following example:

docker-compose.yml

version: "3.7"
services:
  # Fire up the app to test, nginx_test
  nginx_test:
    image: nginx

  # Fire up hawkscan to scan the test app (nginx_test)
  hawkscan:
    image: stackhawk/hawkscan
    environment:
      API_KEY: "${HAWK_API_KEY}"
    volumes:
      - type: bind
        source: .
        target: /hawk
    tty: true
    depends_on:
      - nginx_test

This configuration creates two containers (services) named nginx_test and hawkscan running on a bridge network, and they can reach one another by service name.

In the Pipelines configuration, we replace the docker script with docker-compose, which reads docker-compose.yml by default for its configuration. And since NGINX is defined in the Docker Compose configuration, we can remove it from the before_install section.

azure-pipelines.yml

pool:
  vmImage: 'ubuntu-latest'

jobs:
  - job: Docker_Compose_Scan
    steps:
      - script: docker-compose up --abort-on-container-exit
        displayName: Docker Compose Scan
        env:
          HAWK_API_KEY: $(hawk_api_key)

The flag, --abort-on-container-exit, tells Docker Compose to tear down all the containers as soon as any one of them exits. This flag will cause Docker Compose to stop all containers once the HawkScan container finishes. Without this flag, the nginx_test container would continue running, and the job would hang until it times out.

Configure HawkScan

At the base directory of your code repository, create a stackhawk.yml configuration file. Then, add the following bare-minimum configuration in the Development environment.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://example.com
  env: Development

Before running HawkScan, replace the following in the configuration:

• app.applicationId with your application ID
• app.host with your application’s host
  • if running locally - http://localhost:{port-number}
  • if running on a Docker Bridge Network - http://{service-name}
• app.env with your application’s environment

Add, commit, and push this file to your Git repository.

For more information on the stackhawk.yml configuration file options, see configuration.