Integrate InsightAppSec with GitLab

Scan for vulnerabilities and prevent potential exploits before publishing changes to your production environment by using the InsightAppSec integration with GitLab. Integrate your InsightAppSec scans into your GitLab CI/CD pipeline by including the scanning steps, which will then automate a DAST scan as part of that build.

Integration between GitLab and InsightAppSec

How does this integration work?

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

  1. An event triggers the CI/CD pipeline in GitLab.
  2. GitLab sends a scan request to InsightAppSec.
  3. The scan runs in InsightAppSec. You can view scan progress in InsightAppSec and build progress in GitLab.
  4. After the scan completes, InsightAppSec sends the scan results back to GitLab, where you can view a summary of the results.

You can add scan gating to prevent vulnerable code from being deployed to production.

What you'll need

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

Configure your CI/CD pipeline for InsightAppSec scans

Configuration options and descriptions
FieldDescriptionRequired?
imagerapid7/insightappsec-gitlab-scan:latest

This is a path to the Rapid7 dockerhub image, from which the pipeline will run.

:latest ensures that you always have the latest version of the image.		Required
scriptpython3 /insightappsec_scan/actions.py

This runs the integration.		Required
TOKEN (API Key)InsightAppSec API key.

Added as a Gitlab variable.		Required
SCAN_CONFIG_IDScan config ID from IAS.Required
REGIONDeployment regionRequired
FAIL_ON_VULN_FINDINGSTrue or False

Determines what happens to the pipeline if vulnerabilities are found.

The default value is True		Optional
WAIT_FOR_SCAN_COMPLETETrue or False

Determiners if the build will wait on the scan completing or just start a scan that can be reviewed later.

The default value is True		Optional
VULN_QUERYScan gating query, which uses parameters from the InsightAppSec Search endpoint.Optional
LOG_LEVELDefines the log level.

Options are debug, info, warn, error, fatal, and panic.

The default is info.		Optional
TIMEOUTScan timeout in minutes, if limit is reached the scan will be canceled and pipeline fail.Optional

  1. Access the Rapid7 InsightAppSec step from Dockerhub. The docker image is included in the pipeline through the image field in the pipeline YAML.

  2. In the GitLab CI/CD Editor, add the following stage, using your own details:

    yaml
    1
    stages:
    2
      - scan
    3
    scan:
    4
      image: rapid7/insightappsec-gitlab-scan:latest
    5
      stage: scan
    6
      script:
    7
        - python3 /insightappsec_scan/actions.py 
    8
            --TOKEN="${IAS_API_KEY}"
    9
            --SCAN_CONFIG_ID="${SCAN_CONFIG_ID}"
    10
            --REGION="${REGION}"
    11
            --FAIL_ON_VULN_FINDINGS="${FAIL_ON_VULN_FINDINGS}"
    12
            --WAIT_FOR_SCAN_COMPLETE="${WAIT_FOR_SCAN_COMPLETE}"
    13
            --VULN_QUERY="${VULN_QUERY}"
    14
            --LOG_LEVEL="${LOG_LEVEL}"
    15
            --TIMEOUT="${TIMEOUT}"
    16
      variables:
    17
        REGION: us
    18
        SCAN_CONFIG_ID: 187a1863-8f1a-4a85-92a6-14d41613deb3
    19
        vuln-query: "vulnerability.severity = 'HIGH'"
    20
        FAIL_ON_VULN_FINDINGS: "false"
    How will I know if there's a new version available?

    The image reference ends with :latest to ensure that you always have the latest version.

You can add scan gating to prevent vulnerable code from being deployed to production.

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. If you set the FAIL_ON_VULN_FINDINGS option to true and results in (VULN_QUERY) match this criteria, then the integration will optionally fail the build.

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.

View results

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

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