GitHub Code Scanning Integration

With StackHawk’s code scanning integration in GitHub Actions, teams can now run Dynamic API and Application Security Testing (DAST) whenever they check-in code and view results directly in GitHub.

This integration can be broken down into four major steps:

• Installing and configuring the integration in GitHub
• Configuring StackHawk to run in GitHub
• Running a scan
• Viewing and triaging results

In this how-to we will go through the scenario of adding the StackHawk integration to a public GitHub repository.

Note: If you are looking to install this integration on a private repository using the codeScanningAlerts feature, you will need to have a GitHub Advanced Security license.

Installing and Configuring the StackHawk Code Scanning Integration

In your repo, navigate to the security tab. Once there, select Code Scanning Alerts in the left hand menu. Scroll down through the list of integration partners and select StackHawk. Click Set Up this Workflow. Upon doing so you will be redirected to the code analysis builder file.

The builder file will look like this by default:

.github/workflows/stackhawk-analysis.yml

name: "StackHawk"

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  schedule:
    - cron: '35 11 * * 5'

jobs:
  stackhawk:
    name: StackHawk
    runs-on: ubuntu-20.04
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Start your service
        run: ./your-service.sh &                  # ✏️ Update this to run your own service to be scanned

      - name: Run HawkScan
        uses: stackhawk/hawkscan-action@v2
        continue-on-error: true                   # ✏️ Set to false to break your build on scan errors
        with:
          apiKey: ${{ secrets.HAWK_API_KEY }}
          codeScanningAlerts: true
          githubToken: ${{ github.token }}

As indicated in the comments in the file, you will need to update two fields:

• The process for starting your service.
• If you would like the HawkScan job step to succeed, even if the scanner reports an error. To have HawkScan push alerts in GitHub code scanning this will need to be set to true.

Read the details on our GitHub Marketplace page for the StackHawk HawkScan Action, and in particular for the codeScanningAlerts feature.

Once you have updated these fields, commit the builder file to your repo.

Configuring StackHawk to Run in GitHub

This section assumes that you have configured your target app in StackHawk. If you have not done so, check out the Getting Started Docs, and then meet us back here.

Store Your StackHawk API Key

To execute a scan in GitHub, you will need to store your StackHawk API key in the GitHub secrets manager.

To do so:

• Copy your API key out of the StackHawk platform.
• Navigate to the Settings tab in your GitHub repo.
• Select Secrets from the left-hand menu and create a new repository secret.
• Name your secret HAWK_API_KEY
• Paste your API key into the value field.
• Add the secret.

Configure the StackHawk YAML

Basic Configuration

The next step is adding the StackHawk YAML file to the base of your repo.

The StackHawk YAML has a wide range of configuration options. For this project, your file needs to have the following configuration at minimum:

stackhawk.yml

app:
  applicationId: kkAAAKAW-kAWW-kkAA-WWwW-kAAkkAAAAwWW
  env: Development
  host: http://localhost:3000

Make sure your .applicationId is correct for your app in the StackHawk platform. Also make sure your .env and .host settings match your application.

Failure Threshold

An important configuration option to also consider including in the YAML is the failureThreshold.

This variable sets the finding level that returns a failed scan status. Accepted values are related to finding severity so this field can be set to high, medium, or low. If a scan fails due to this threshold being met, it will trigger a Code Scanning Alert in GitHub.

To enable this variable, update your configuration file to the following:

stackhawk.yml

app:
  applicationId: kkAAAKAW-kAWW-kkAA-WWwW-kAAkkAAAAwWW
  env: Development
  host: http://localhost:3000
hawk: 
  failureThreshold: high

Commit the file to your repo.

Running a Scan

By default, StackHawk will run every time you check in code. To modify this setting, change the builder file.

After you have pushed code, visit the Actions tab and you will see StackHawk is now a step in the pipeline.

Viewing and Triaging Scan Results

View Results in GitHub Actions

To view results you can click into the Run Hawkscan portion of the latest build in GitHub Actions.

Scroll to the bottom and you can see the findings from the scan and find a link that will bring you to the findings report in StackHawk.

View Results in GitHub Security

If you have configured StackHawk to break builds, you will see a badge in the security tab should StackHawk find new vulnerabilities that meet your failure threshold.

Click into that tab and navigate to Code Scanning Alerts where you will see a notification that StackHawk found results that met or exceeded your failure threshold.

Click into the notification to be taken to the findings report in the StackHawk platform.

Not seeing any notifications? Make sure that both the failureThreshold variable in the StackHawk YAML is set, and the codeScanningAlerts variable is set to “true” in the builder file.

Triaging Scan Results

If new findings broke your build, you will need to triage those findings to complete future builds. To learn more about how to triage and available triage actions, check out the docs.

Support

If you are trying to run a StackHawk scan with GitHub Code Scanning and something isn’t working, contact StackHawk Support and we’ll help you get your scans running.