HawkScan and GitHub Actions

With our HawkScan GitHub Action, it is a snap to add application scanning to your GitHub Actions workflow.

To integrate StackHawk into GitHub Actions workflows, simply:

1. Secure your API key as a Secret in your GitHub repository
2. Configure your workflow with a .github/workflows/hawkscan.yml file
3. Configure HawkScan with a stackhawk.yml file

In this how-to, we will first describe the simple scenario of scanning a publicly available example app, example.com. Then we will walk through how to scan a service on the localhost address and in a Docker Compose configuration.

Looking for the new Microsoft Defender for Cloud integration? Check out the documentation here.

Secure Your API Key

When you signed up on StackHawk, you created an API key. To keep it a secret, and out of your repository, copy it to a GitHub secret for your repository. On GitHub, find your repository, and click into the ⚙️Settings tab near the top right side of the screen. Then click Secrets near the bottom left . Add your StackHawk API key as a secret called HAWK_API_KEY.

Configure Your Workflow

At the base directory of your code repository, add a .github/workflows/hawkscan.yml file to configure GitHub Actions to run HawkScan. Your file should look like this.

.github/workflows/hawkscan.yml

name: HawkScan
on:
  push:
  pull_request:
jobs:
  hawkscan:
    name: HawkScan
    runs-on: ubuntu-latest
    steps:
      - name: Clone repo
        uses: actions/checkout@v2
      - name: Run HawkScan
        uses: stackhawk/hawkscan-action@v2
        with:
          apiKey: ${{ secrets.HAWK_API_KEY }}

This configuration tells GitHub Actions to run a single job which checks out your code, and then runs HawkScan as a Docker container. We pass the StackHawk API key to HawkScan from the GitHub secret, HAWK_API_KEY.

Configure HawkScan

At the base directory of your code repository, create a stackhawk.yml appropriate for scanning your application. For our example, we will create a minimal configuration pointing to our Development environment API endpoint, http://example.com.

stackhawk.yml

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

Replace the value for applicationId with your Application ID from StackHawk.

Run It

Check those two files into source control, and push them to GitHub. Head over to the GitHub Actions console to watch your workflow run. When it is complete, check your account at StackHawk to review your scan details!

Local Scanning

The previous example is simple, but it assumes that you have an integration environment that is publicly accessible. Alternatively, you can run your app and scan it directly on the ephemeral GitHub build host. Here are three common ways of doing that.

Scanning a Service on Localhost

One way to test an app after building it is to launch it on the VM where the workflow is running, and scan it on the localhost address. You can launch the HawkScan container with the flag --network host to give it access to localhost, and set app.host in stackhawk.yml to http://localhost:8080.

For our example app, we will launch an Nginx container listening on port 8080. Then we will scan it at the localhost address with HawkScan. This method works with any app you wish to scan, containerized or not, as long as it is listening on the localhost address.

Here’s our modified GitHub workflow.

.github/workflows/hawkscan.yml

name: HawkScan
on:
  push:
  pull_request:
jobs:
  hawkscan:
    name: HawkScan
    runs-on: ubuntu-latest
    steps:
      - name: Clone repo
        uses: actions/checkout@v2
      - name: Run Nginx
        run: docker run --rm --detach --publish 8080:80 --name nginx_test nginx
      - name: Run HawkScan
        uses: stackhawk/hawkscan-action@v2
        with:
          apiKey: ${{ secrets.HAWK_API_KEY }}

☝️ Notice the new Run Nginx step which launches our app.

Finally, here’s our modified HawkScan configuration pointing to the localhost address.

stackhawk.yml

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

When you run this workflow, it will launch Nginx, scan it with HawkScan, and post the results to your StackHawk scan list.

Scanning a Service in Docker Compose

Docker Compose can be a useful tool for modeling complex test environments in your CI/CD pipeline. It provides a concise way to combine your app server with any other services it might require to create a useful environment for integration testing and of course DAST scanning.

In Docker Compose, you can publish the ports of the service you want to scan using the services.<service-name>.ports configuration. That service would then be accessible on the localhost address of your build VM, so your HawkScan Action configuration would look just like the one above, under Scanning a Service on Localhost.

For example, say you have an test environment for your application defined as the Docker Compose configuration below. It contains your app server, myapp, and a Postgres database, db.

# docker-compose.yml

version: "3.9"

services:
  myapp:
    image: myapp
    ports:
      - "8080:80"


  db:
    image: postgres
    restart: always
    ports:
      - "5432:5432"

To scan the above, say you have a HawkScan configuration file like the following.

# stackhawk.yml

app:
  applicationId: xxxxxxxx-XXXX-xxxx-XXXX-xxxxxxxxxxxx
  env: Development
  host: http://localhost:8080

Finally here’s how you would configure your GitHub Actions workflow.

# .github/workflows/hawkscan.yml

name: HawkScan
on:
  push:

jobs:
  hawkscan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: docker-compose up -d
      - uses: stackhawk/hawkscan-action@v2
        with:
          apiKey: ${{ secrets.HAWK_API_KEY }}

For more details on configuring the HawkScan Action, visit HawkScan Action in the GitHub Actions marketplace!

And, if you are looking to integrate StackHawk notifications with GitHub Advanced Security, checkout our GitHub Code Scanning Integration )