Integrate CI-driven scans

This document outlines a generic process to integrate Invicti Platform with your CI/CD pipelines (for example, Jenkins, GitLab CI/CD, Azure Pipelines, GitHub Actions) to automate web application vulnerability scans. With this integration, you can automatically trigger security scans during your CI/CD workflows to identify and address issues before deployment.

The integration uses the Invicti scan-cli container - a lightweight Docker container configured entirely through environment variables with no code changes required. It connects to Invicti Platform to trigger and monitor scans, works with any CI/CD platform that supports Docker, and stores all scan results and reports centrally in Invicti Platform.

note

The scan-cli container triggers scans and monitors them. The actual scan duration is the same as running the same scan in the UI — you're using the pipeline to trigger it.

Prerequisites

Ensure the following requirements are met before proceeding:

• Permission to create and configure pipeline jobs in your CI/CD tool (Jenkins, GitLab CI/CD, Azure Pipelines, CircleCI, etc.). Admin access is not required.
• Docker command-line tool installed and running on the agent or node that executes your pipeline
• Invicti Platform account with API Security enabled
• Access to the Invicti Scan CLI Docker image. Refer to access Invicti registries for more information.
• A target ID for the application you want to scan (see Step 2)
• A scan profile configured in Invicti Platform

Step 1: Generate an API token

You need an API token to authenticate the scan requests.

1. In Invicti Platform, choose your Username  > Profile from the left-side menu.
2. In the Token field, copy the existing token. If you generate a new token, the previous one becomes invalidated.
3. Store this token securely using your CI/CD platform's secret management. It is used in your CI/CD script.

Step 2: Get your target ID

You need the target ID of the application you want to scan. You can find it in the UI URL, or retrieve it using the Inventory API:

curl -X 'GET' \
'https://platform.invicti.com/api/inventory/v1/assets?assetType=target&pageSize=50&pageNumber=1' \
-H 'accept: application/json' \
-H 'X-Auth: {your-api-token}'

The target ID is located at $.items[0].id in the JSON response. For more options, refer to Retrieve the target ID.

tip

Target IDs don't change, so you can save them alongside the website name and reuse them across different pipelines and configurations.

Step 3: Get a scan script

There are two ways to get a scan script:

Option 1: Generate from Invicti Platform

Invicti Platform provides a tool-specific scan script generator that produces pre-configured scripts with the correct environment variables and platform-specific syntax.

1. Choose Integrations from the left-side menu.
2. Open the Browse Integrations tab.
3. Choose any supported integration (for example, Jenkins) and click Configure.
4. Choose the Asset and Scan Profile you want to use.
5. Set build failure conditions if needed.

6. Click Generate script.

Use the generated script as a starting point and customize it for your specific requirements.

Option 2: Write a custom script

Write your own script to pull the image, define environment variables, and run the container. The general flow is the same across all CI/CD platforms: pull the container, define environment variables, and run the container. This approach offers more flexibility. See the examples in Step 5.

Step 4: Copy and customize the script

1. Copy the generated script.
2. Replace the INVICTI_API_TOKEN placeholder with your actual API token.
3. Adjust environment variables to fit your CI/CD environment.

Environment variables

The scan-cli container is configured through environment variables:

Variable	Required	Description
INVICTI_API_BASE_URL	Yes	API base URL for your Invicti Platform instance
INVICTI_API_TOKEN	Yes	Your API token for authentication
INVICTI_TARGET_ID	Yes	The target (asset) ID of the application to scan
INVICTI_SCAN_PROFILE	Yes	Scan configuration (for example, "Full Scan", "Crawl Only")
INVICTI_SCAN_AGENT	No	Which agent to use (defaults to CloudAgent)
INVICTI_SCAN_TIMEOUT	No	Maximum scan duration
INVICTI_REPORT_TEMPLATE	No	Report template name (for example, "Comprehensive")

For a complete list of available variables, refer to CI environment variables.

note

If your target requires authentication credentials, these are automatically pulled by the scan-cli from the Target configuration in Invicti Platform. Configure authentication by selecting Targets > Edit > Authentication in the UI.

If you have Enable AI aided auto-login set to yes, you may not even need an LSR (Login Sequence Recorder) or web page configuration — just provide the username and password and Invicti automatically figures out the login process.

Generic Docker run command

Use the following command to trigger a scan directly via Docker. This method works across all CI/CD platforms that support Docker.

Basic usage

docker pull platform-registry.invicti.com/invicti-platform/invicti-scan-cli
docker run \
  -e INVICTI_API_BASE_URL="https://platform.invicti.com" \
  -e INVICTI_API_TOKEN="<your-api-token>" \
  -e INVICTI_TARGET_ID="<your-target-id>" \
  -e INVICTI_SCAN_AGENT="CloudAgent" \
  -e INVICTI_REPORT_TEMPLATE="Comprehensive" \
  platform-registry.invicti.com/invicti-platform/invicti-scan-cli

Docker Hub alternative

The Invicti Scan CLI image is also available on Docker Hub. You can use invicti/scan-cli as an alternative to the Invicti registry image.

With report volume mount

To retrieve reports locally after the scan completes, use a volume mount:

docker run \
  -e INVICTI_API_BASE_URL="https://platform.invicti.com" \
  -e INVICTI_API_TOKEN="<your-api-token>" \
  -e INVICTI_TARGET_ID="<your-target-id>" \
  -e INVICTI_SCAN_AGENT="CloudAgent" \
  -e INVICTI_REPORT_TEMPLATE="Comprehensive" \
  -v ./publicdata:/home/invicti/publicdata/ \
  platform-registry.invicti.com/invicti-platform/invicti-scan-cli

This mounts the local ./publicdata directory into the container, allowing you to retrieve reports post-scan.

Using an on-premises CI/CD tool with cloud Invicti Platform

You can use a self-hosted CI/CD tool (such as Azure Pipelines with self-hosted agents) together with cloud-hosted Invicti Platform. The integration works outbound: the scan-cli runs as a step inside your pipeline and communicates to Invicti Platform. Your pipeline agents only need outbound network access to the INVICTI_API_BASE_URL and to the scan target.

Network accessibility requirement

When using on-premises Invicti installations, ensure your CI/CD environment can access the INVICTI_API_BASE_URL. If the CI/CD system cannot reach your on-premises Invicti instance, the integration will fail. Verify network connectivity before running scans.

Scanning internal targets

If your target isn't publicly accessible — for example, an internal staging environment or an app behind a firewall — use INVICTI_SCAN_AGENT="EphemeralAgent" instead of CloudAgent. The ephemeral agent launches temporarily from within the CI/CD environment, performs the scan, and is automatically cleaned up afterward.

Step 5: Embed the script in your CI/CD pipeline

Once you have your script (generated or custom), integrate it into your pipeline:

1. Share the script with your developer team.
2. Add it as a build step towards the end of your pipeline, after your application has been built.
3. Deploy the application to a test environment before running the scan.
4. Configure the scan to run against that deployed environment.

This ensures you're scanning the actual built and deployed version of your application, not source code.

Each CI/CD tool has its own method for embedding the script. Make sure the script runs at the appropriate phase (for example, post-build, pre-deploy).

GitHub Actions

name: Invicti Scan

on:
  workflow_dispatch: {}
  push:
    branches: [ main ]
  pull_request: {}

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: invicti/scan-cli:latest
    env:
      INVICTI_API_BASE_URL: "https://platform.invicti.com"
      INVICTI_API_TOKEN: ${{ secrets.INVICTI_API_TOKEN }}
      INVICTI_TARGET_ID: "<your-target-id>"
      INVICTI_SCAN_AGENT: "CloudAgent"
      INVICTI_SCAN_PROFILE: "Full Scan"

    steps:
      - name: Run Invicti Scan CLI
        run: /home/invicti/scancli/ScanCLI

      - name: Upload scan artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: invicti-scan-results
          path: |
            ./scan-results/**
            ./reports/**
            ./*.json
            ./*.html
          if-no-files-found: ignore
          retention-days: 7

Jenkins

Add the script to the pipeline configuration. Jenkins also requires the Docker Pipeline plugin (via Manage Jenkins > Manage Plugins).

GitLab CI/CD

Place the script in a job step within your .gitlab-ci.yml file.

Azure Pipelines

Add the script in a script step within your azure-pipelines.yml file.

CircleCI

Create a file named config.yml inside the .circleci directory and paste the prepared script. Read more at the official CircleCI website.

Step 6: Run and monitor the pipeline

1. Trigger a pipeline run.
2. The CI/CD tool performs the following actions:
   • Pulls the Invicti Scan CLI Docker image
   • Runs the scan
   • Generates a security report
3. Monitor the console/log output.
4. Download and review the report if required.

Scan results and reports are stored centrally in Invicti Platform:

• Select Scans from the left-side menu to view all scan activities
• Select Reports to access generated reports
• Check Vulnerabilities for detailed findings

Best practices

• Use the script generation feature in Invicti Platform as a starting point — every CI/CD environment has different requirements.
• Store API tokens securely using your CI/CD platform's secret management.
• Run scans after your application is built and deployed to a test environment, not against source code.
• Multiple shorter scans are better than one large scan. Use INVICTI_SCAN_TIMEOUT to set the maximum scan duration.
• Schedule regular scans using scheduled pipelines or cron jobs.
• Use environment-specific scan profiles (for example, staging vs. production).
• Enforce policies to block builds if critical vulnerabilities are found.

---

Need help?

Invicti Support team is ready to provide you with technical help. Go to Help Center