Add InsightAppSec Scans into your GitHub Workflow

Scan for vulnerabilities and prevent potential exploits before publishing changes to your production environment by using the InsightAppSec integration with GitHub Actions. You can include InsightAppSec scans in your CI/CD build pipeline workflow by adding the scan action and subsequent steps to your GitHub workflow.

Integration between GitHub and InsightAppSec

How does this integration work?

Let's walk through the interactions between GitHub, GitHub Actions, and InsightAppSec to better understand this integration.

  1. An event in GitHub triggers the workflow in GitHub Actions.
  2. GitHub Actions sends a scan request to InsightAppSec.
  3. The scan runs in InsightAppSec. You can view progress in both InsightAppSec and GitHub.
  4. After the scan completes, InsightAppSec sends the scan results back to GitHub, where you can view a summary of the results.
  5. The workflow advances.

You can add scan gating to prevent vulnerable code from being deployed to production. If there are results from the vuln-query, the job is marked as failed.

Scan gating

You can set gating criteria with this integration to prevent risky code from entering your production environment. One way to use scan gating is to set build pass/fail criteria for vulnerabilities. When the scan finds vulnerabilities that meet or exceed your gating criteria, you can set a step to follow, such as failing the workflow so that code is not deployed to production.

The scan gating query can be anything the search vulnerability endpoint can accept, not just limited to severity. For more information, see the InsightAppSec API documentation.

Example: Use scan gating to prevent vulnerable code from being deployed to production.

In this example, we will create a workflow with scan gating so that the build will fail if high severity vulnerabilities are discovered in the scan.

Add a workflow

  1. In your GitHub repository, click the Actions tab.
  2. Customize and add the following to a new yaml workflow file, using the vuln-query field to set gating criteria: 
    yaml
    1
     name: IAS Scan
    2
     on:
    3
       push:
    4
         branches: [ master ]
    5
     jobs:
    6
       scan:
    7
         runs-on: ubuntu-latest
    8
         steps:
    9
           - id: my-scan
    10
             uses: rapid7/insightappsec-scan-github-actions@v1.1.0
    11
             with:
    12
               region: "us"
    13
               api-key: ${{ secrets.IAS_API_KEY }}
    14
               scan-config-id: "999703e4-a4p0-4ea6-a3sc-53cg789e4fc1"
    15
               vuln-query: "vulnerability.severity = 'HIGH'"
    16
           - name: Upload findings
    17
             if: always()
    18
             run: echo "${{ steps.my-scan.outputs.scan-findings }}"

Run a build

  1. Commit to GitHub.
  2. The commit starts the build workflow in GitHub Actions.
  3. In GitHub Actions, the actions are built and deployed.
  4. GitHub Actions sends a scan request to InsightAppSec.
  5. The scan runs in InsightAppSec. You can view progress in both InsightAppSec and GitHub.
  6. After the scan completes, InsightAppSec sends the scan results back to GitHub.
  7. Depending on your scan and actions configurations, one of the following happens:
    • If there are no vulnerabilities that meet your gating criteria, the workflow completes and is published to production.
    • If there are one or more vulnerabilities that match your gating criteria, the workflow fails which, in this case, is severity = High.

What you'll need

To make your configuration easier, have the following pieces of information available:

  • InsightAppSec API key
  • Scan Config ID of the InsightAppSec scan that you want to run

Integrate InsightAppSec in GitHub

  1. Add the InsightAppSec API Key as a secret in GitHub, otherwise the action won't work. See the GitHub documentation for information about adding API keys as secrets: https://docs.github.com/en/actions/security-guides/encrypted-secrets
  2. Access the Rapid7 InsightAppSec action in one of the following ways:

Add the InsightAppSec scan as an action to your GitHub workflow

In your GitHub workflow YML file, add the following to the jobs: section, using your own details:

yaml
1
  scan:
2
    runs-on: ubuntu-latest
3
    steps:
4
      - id: my-scan
5
        uses: rapid7/insightappsec-scan-github-actions@v1.1.0
6
        with:
7
          region: "us"
8
          api-key: ${{ secrets.IAS_API_KEY }}
9
          scan-config-id: "999703e4-a4p0-4ea6-a3sc-53cg789e4fc1"
10
          vuln-query: "vulnerability.severity = 'MEDIUM'"
11
      - name: Upload findings
12
        if: always()
13
        run: echo "${{ steps.my-scan.outputs.scan-findings }}"

Update to a new version

When a new version of the extension is available, manually update the uses: value in the yaml file with the new version number.

How will I know if there's a new version available?

The InsightAppSec release notes will include any updates to the extension. You can also check GitHub Marketplace for updates.

When an update is applied, manually update the version in the yaml file for the action.

View results

During the scan, you can view scan progress in both GitHub and InsightAppSec on the Scanning Activity page.

When the scan completes and the results are automatically sent back to GitHub, you can view your results in the build results and in InsightAppSec.