---
title: "Code Scanning"
description: "Run Dynamic API and Application Security Testing (DAST) whenever you check in code, and view results in GitHub."
url: https://docs.stackhawk.com/integrations/ci-cd/github-actions/github-code-scanning/
---

# Code Scanning

![GitHub](https://docs.stackhawk.com/images/integrations/logos/github.svg)

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](https://docs.github.com/en/get-started/learning-about-github/about-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`](#migrating-from-codescanningalerts).

### Upload Individual Findings as SARIF

```yaml title=".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-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@v3
        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`:

| Field | Value |
| - | - |
| Rule ID | The HawkScan plugin ID, for example `10038` |
| Rule help link | The rule’s page in the [Vulnerability Index](https://docs.stackhawk.com/vulnerability-index/) |
| Location | The request path relative to your application host, for example `api/users` |
| Fingerprint | Derived from the rule, HTTP method, path and parameter, so the same finding keeps its alert across HawkScan upgrades |

`--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](https://github.com/marketplace/actions/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](https://docs.stackhawk.com/hawkscan/#quickstart), 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:

```yaml title="stackhawk.yml"
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:

```yaml title="stackhawk.yml"
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](https://docs.stackhawk.com/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](https://docs.stackhawk.com/platform/scans/#actions).

## 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.

```diff
     permissions:
       contents: read
+      security-events: write
     steps:
       ...
       - name: Run HawkScan
         uses: stackhawk/hawkscan-action@v3
         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](https://docs.stackhawk.com/support/) and we’ll help you get your scans running.