Code Scanning

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:

• Adding the StackHawk workflow to your repo
• 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, you will need to have a GitHub Advanced Security license.

Adding the StackHawk Workflow

Add the following workflow file to your repo. It runs HawkScan with --sarif-ghas (HawkScan 6.6.0 and later), which writes stackhawk-ghas.sarif, and then uploads that file to GitHub code scanning with GitHub’s upload-sarif action.

Note: If you start from the StackHawk entry in your repo’s Security tab (Code Scanning Alerts > Set up this workflow), the generated file uses the deprecated codeScanningAlerts input. Replace it with the workflow below. See Migrating from codeScanningAlerts.

Upload Individual Findings as SARIF

name: "StackHawk"

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

jobs:
  stackhawk:
    name: StackHawk
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write                      # Required to upload SARIF
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - 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 }}
          args: |
            --sarif-ghas

      - name: Upload SARIF to GitHub code scanning
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: stackhawk-ghas.sarif
          category: stackhawk

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

• The process for starting your service.
• Whether the HawkScan step should succeed even if the scanner reports an error. The upload step runs either way because of if: always().

Each finding becomes its own code scanning alert. In stackhawk-ghas.sarif:

--sarif-artifact still writes stackhawk.sarif in its original format, which GitHub code scanning doesn’t accept. You can set both flags to get both files.

Read the details on our GitHub Marketplace page for the StackHawk HawkScan Action.

Once you have updated these fields, commit the workflow 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:

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  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. To fail your build when the threshold is met, set continue-on-error: false on the HawkScan step. The SARIF upload step still runs when the build fails, because it uses if: always().

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

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  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 workflow 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

Navigate to the Security tab and select Code scanning. Filter by the stackhawk category to see one alert per HawkScan finding. Each alert’s rule help links to the rule’s page in the Vulnerability Index.

Not seeing any alerts? Make sure that:

• HawkScan is version 6.6.0 or later, and --sarif-ghas is in the args input.
• The job has the security-events: write permission.
• The Upload SARIF to GitHub code scanning step ran and found stackhawk-ghas.sarif.

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.

Migrating from codeScanningAlerts

Deprecated: The HawkScan Action’s codeScanningAlerts input is deprecated as of stackhawk/hawkscan-action 3.2.0 and will be removed in a future release.

codeScanningAlerts raises a single code scanning alert, linking to the scan in StackHawk, only when a scan meets your failureThreshold. --sarif-ghas raises one alert per finding, with its own rule, location, and help link.

To migrate an existing workflow:

1. Remove codeScanningAlerts: true from the HawkScan step. You can also remove githubToken if nothing else uses it.
2. Add --sarif-ghas to the HawkScan step’s args.
3. Add security-events: write to the job’s permissions.
4. Add the Upload SARIF to GitHub code scanning step after the HawkScan step.

The diff below shows only the changed parts of the workflow; ... stands for your existing steps.

     permissions:
       contents: read
+      security-events: write
     steps:
       ...
       - name: Run HawkScan
         uses: stackhawk/hawkscan-action@v2
         continue-on-error: true
         with:
           apiKey: ${{ secrets.HAWK_API_KEY }}
-          codeScanningAlerts: true
-          githubToken: ${{ github.token }}
+          args: |
+            --sarif-ghas
+
+      - name: Upload SARIF to GitHub code scanning
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: stackhawk-ghas.sarif
+          category: stackhawk

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.