CI/CD and automation

scansuite-ci starts a ScanSuite scan from a CI job, a script or a terminal, waits for it, and fails the job when the scan finds confirmed vulnerabilities or secrets. It runs static analysis of the code (the default), dynamic scans of a running web application, and infrastructure scans of hosts, networks and container images. The scan runs on the ScanSuite server, so the CI runner needs only Python 3.8 or newer, or the client's container image appsec4u/scansuite-ci:1. This page covers client version 1.4.5.

The steps below set up one pipeline. GitLab CI step by step walks through the same setup in GitLab with screenshots and tested recipes.

Before you start

Setup

The pipeline signs in with the token of a service account, not a person's password. A service account belongs to the team and keeps working when people leave.

1. 01
   Create a service account

   Teams in the sidebar, then the People tab, Automation and API tokens card. Under New service account type a name such as ci, set Role to Operator (the default, Reader, cannot start scans) and select Create. Check: the account appears in the card with the role Operator and the badge Active.

2. 02
   Note the team name

   The line at the top of the same card reads: This team's name in pipelines and API addresses (SCANSUITE_TEAM), followed by the name in bold. Use that name, not the team's display name. The first team of an installation is default, whatever it was renamed to.

3. 03
   Issue a token

   Select New token on the service account. Keep the CI pipeline preset, set Valid for (days) and select Create token. Check: the Your new token dialog opens with the token, the team name and two test commands.

The Your new token dialog shows, in order: the token with a Copy button; the row This team's name in pipelines and API addresses (SCANSUITE_TEAM) with its own Copy button; and Test the connection with two ready-to-run commands, With the pipeline client (Docker) and With curl, that already contain this server's address, the team and the token. Both commands contain the token, so running them as they are leaves it in your shell history. Prefer the test below, which reads the token without echoing it.

A token can never do more than its service account's role allows. A service account is Reader or Operator.

Test the connection

This test proves that the server answers, takes the token for this team, and that the token can run pipeline scans. It starts nothing.

1. 01
   Set the server and team

   ShellCopy

   export SCANSUITE_URL=<YOUR_SCANSUITE_URL> SCANSUITE_TEAM=<YOUR_TEAM>

2. 02
   Read the token without echoing it (paste it, then press Enter)

   ShellCopy

   read -rs SCANSUITE_TOKEN && export SCANSUITE_TOKEN

3. 03
   Run the check

   ShellCopy

   docker run --rm -e SCANSUITE_URL -e SCANSUITE_TEAM -e SCANSUITE_TOKEN appsec4u/scansuite-ci:1 --check

[scansuite] Connected to https://scansuite.example.com: the server accepts the API token for team default (role operator)
[scansuite] The token may: credential.read, finding.read, product.read, product.write, report.read, scan.cancel, scan.execute, scan.read
[scansuite] The token expires in 30 day(s) (2026-11-18T09:12:44Z)
[scansuite] The token can run pipeline scans

Without Docker, run python3 scansuite-ci.py --check with the client from Getting the client. A token without the permissions a pipeline needs prints WARNING: The token cannot run pipeline scans: it lacks … instead of the last line; issue a new token with the CI pipeline preset. A refused token ends with exit code 3 and the reason:

Add the variables to your CI system

Add a ScanSuite scan to this repository's CI pipeline by following https://scansuite.eu/documentation/reference/cicd. Work out which CI system the repository uses, use the image appsec4u/scansuite-ci:1, and use the merge-request and default-branch bundles the page recommends. Do not put a token anywhere in the repository and do not ask me for it: tell me which secret and variables to add, and stop at every step marked "A person does this step".

Token permissions

Before anything starts, the client checks that the token has every permission the run needs and names any that is missing (exit code 3).

Getting the client

Download it from your ScanSuite server, which serves the version that matches it, and check its checksum:

curl -fsSO <YOUR_SCANSUITE_URL>/ci/scansuite-ci.py
curl -fsS <YOUR_SCANSUITE_URL>/ci/scansuite-ci.py.sha256 | sha256sum -c -
python3 scansuite-ci.py --version

On a server that still has its first, self-signed certificate, curl stops with SSL certificate problem: add -k to these two lines until a real certificate is in place (SSL/TLS Setup).

Expected: scansuite-ci.py: OK, then scansuite-ci 1.4.5 (or the version your server publishes). Or use the container image appsec4u/scansuite-ci:1 (the latest 1.x), where the client runs as scansuite-ci and Git is installed; clear its entrypoint when the CI system runs its own shell in the container. At start-up the client says when the server offers a newer version.

Pipelines by CI system

Each platform runs the same client with the same options. The client reads the repository, branch, commit and merge or pull request target from GitLab CI, GitHub Actions, Jenkins, Azure DevOps and Bitbucket Pipelines.

GitLab CI

Include the template your ScanSuite server publishes. It adds scansuite-merge-request (quick-classic on the changed files of every merge request) and scansuite-default-branch (standard-ai on the default branch), and a hidden .scansuite job to extend for your own jobs.

include:
  - remote: '<YOUR_SCANSUITE_URL>/ci/scansuite.gitlab-ci.yml'

Variables, recipes (DAST, images, nightly, release, monorepo) and GitLab-specific troubleshooting are in GitLab CI step by step.

GitHub Actions

Copy the github/ folder of the scansuite-ci repository into your repository as .github/actions/scansuite, and add the token as the repository secret SCANSUITE_TOKEN. Findings then appear under Security → Code scanning.

name: ScanSuite
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  security-events: write          # SARIF upload

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }  # --changed-only needs the history
      - uses: ./.github/actions/scansuite
        with:
          url: <YOUR_SCANSUITE_URL>
          team: <YOUR_TEAM>
          product: <YOUR_PRODUCT>
          token: ${{ secrets.SCANSUITE_TOKEN }}
          profile: ${{ github.event_name == 'pull_request' && 'quick-classic' || 'standard-ai' }}
          changed-only: ${{ github.event_name == 'pull_request' }}
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with: { sarif_file: scansuite.sarif }

The action has no input for --fail-on-secrets, --scan-type, targets, --create-product or other client options. For those, and for DAST and infrastructure scans, run the image as a container job and pass any option:

jobs:
  scan:
    runs-on: ubuntu-latest
    container: appsec4u/scansuite-ci:1
    env:
      SCANSUITE_URL: <YOUR_SCANSUITE_URL>
      SCANSUITE_TEAM: <YOUR_TEAM>
      SCANSUITE_PRODUCT: <YOUR_PRODUCT>
      SCANSUITE_TOKEN: ${{ secrets.SCANSUITE_TOKEN }}
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: scansuite-ci --profile quick-classic --changed-only --sarif scansuite.sarif

Jenkins

Add the jenkins folder of the scansuite-ci repository as a Global Pipeline Library (Manage Jenkins → System → Global Pipeline Libraries, for example named scansuite), and store the token as a Secret text credential. The step needs the Docker Pipeline plugin. It publishes the JUnit report and archives the JSON summary.

@Library('scansuite') _
pipeline {
  agent any
  stages {
    stage('ScanSuite') {
      steps {
        scansuiteScan(
          url: '<YOUR_SCANSUITE_URL>', team: '<YOUR_TEAM>', product: '<YOUR_PRODUCT>',
          credentialsId: 'scansuite-ci-token',
          profile: env.CHANGE_ID ? 'quick-classic' : 'standard-ai',
          changedOnly: env.CHANGE_ID != null,
          unstableOnGate: true)
      }
    }
  }
}

Without the library, use a Docker agent with the image, clear its entrypoint (args '--entrypoint='), map the credential with SCANSUITE_TOKEN = credentials('scansuite-ci-token'), and run scansuite-ci in an sh step.

Azure DevOps

Add SCANSUITE_TOKEN as a secret pipeline variable. Azure DevOps does not pass secrets to scripts on its own, so map it under env. The Microsoft-hosted Ubuntu agents have Python 3 and Git.

trigger: [main]
pr: [main]
pool: { vmImage: ubuntu-latest }

variables:
  SCANSUITE_URL: <YOUR_SCANSUITE_URL>
  SCANSUITE_TEAM: <YOUR_TEAM>
  SCANSUITE_PRODUCT: <YOUR_PRODUCT>

steps:
  - checkout: self
    fetchDepth: 0
  - script: |
      set -e
      curl -fsSO "$SCANSUITE_URL/ci/scansuite-ci.py"
      curl -fsS "$SCANSUITE_URL/ci/scansuite-ci.py.sha256" | sha256sum -c -
      if [ "$BUILD_REASON" = "PullRequest" ]; then ARGS="--profile quick-classic --changed-only"; else ARGS="--profile standard-ai"; fi
      python3 scansuite-ci.py $ARGS --junit scansuite-junit.xml --sarif scansuite.sarif
    displayName: ScanSuite
    env:
      SCANSUITE_TOKEN: $(SCANSUITE_TOKEN)
  - task: PublishTestResults@2
    condition: always()
    inputs: { testResultsFormat: JUnit, testResultsFiles: scansuite-junit.xml, testRunTitle: ScanSuite }

Pull request builds (branch policy → build validation) report the target branch, and --changed-only compares with it. A server with a self-signed certificate also needs curl -k for the download.

Bitbucket Pipelines

Add SCANSUITE_TOKEN as a secured repository variable and the others as plain ones. Test results under test-results/ are picked up on their own.

image: python:3.12
clone:
  depth: full

pipelines:
  pull-requests:
    '**':
      - step:
          name: ScanSuite (changed files)
          script:
            - curl -fsSO "$SCANSUITE_URL/ci/scansuite-ci.py"
            - curl -fsS "$SCANSUITE_URL/ci/scansuite-ci.py.sha256" | sha256sum -c -
            - python3 scansuite-ci.py --profile quick-classic --changed-only --junit test-results/scansuite.xml
  branches:
    main:
      - step:
          name: ScanSuite
          script:
            - curl -fsSO "$SCANSUITE_URL/ci/scansuite-ci.py"
            - curl -fsS "$SCANSUITE_URL/ci/scansuite-ci.py.sha256" | sha256sum -c -
            - python3 scansuite-ci.py --profile standard-ai --junit test-results/scansuite.xml

Any other CI system, a script or a laptop

Elsewhere (CircleCI, TeamCity, Drone, a cron job) give the client what it cannot detect: the base for --changed-only, and a unique --idempotency-key per run so a retried step does not pick up the previous run's scan.

docker run --rm -v "$PWD:/src" -w /src \
    -e SCANSUITE_URL -e SCANSUITE_TEAM -e SCANSUITE_TOKEN -e SCANSUITE_PRODUCT \
    appsec4u/scansuite-ci:1 \
    --profile quick-classic --changed-only --base origin/main --idempotency-key "build-$BUILD_NUMBER" \
    --junit scansuite-junit.xml

On a laptop, keep the token in a file readable only by you and pass --token-file ~/.scansuite-token instead of the variable. Without Git on the machine, the client archives the directory tree with default exclusions, and --changed-only falls back to a full scan.

Check the first run

The job log starts with the team and product it reports to and the scan's reference, and ends with the verdict:

[scansuite] Quality gate passed

or [scansuite] Quality gate FAILED: N blocking finding(s), M blocking secret(s), after one BLOCKING line per finding or secret that failed it, followed by [scansuite] Exit code 1: the quality gate failed …. The scan also appears in ScanSuite under Scan History. If the job ends with another exit code, see Exit codes.

Products

Every scan reports into one product of your team: give its exact name with --product-name (SCANSUITE_PRODUCT) or its number with --product-id (SCANSUITE_PRODUCT_ID), not both. A name that matches no product stops the run with exit code 3.

With --create-product (SCANSUITE_CREATE_PRODUCT=1) the first run creates the product and logs Created product …; later runs find it. The CI pipeline preset allows it. When the team works with DefectDojo, the product is created there as well; if DefectDojo cannot be reached, it is still created in ScanSuite and the run warns. For one product per service of a monorepo, give each job its folder and product: --source-dir services/payments --product-name payments --create-product.

What to run, and when

Static analysis

Six bundles, three without AI and three with it. --profile or SCANSUITE_PROFILE picks one; standard-ai is the default.

The AI bundles report only the secrets AI verification confirmed; when verification could not run for some, the client warns with their number. full-ai analyses Git history, so fetch the full history in the pipeline (GitLab GIT_DEPTH: 0, GitHub fetch-depth: 0). The 1.x names still work: quick is quick-classic, standard is standard-ai, deep is full-ai.

Scanners and options

--scanners replaces a bundle's scanners, --add-scanners adds to them, and --options replaces its options; --no-ai-verification drops the AI options. An option is sent only with its scanner. --list-scanners prints what your server offers, marks what can scan selected files, what runs alone and what is NOT AVAILABLE for your team, with the reason; choosing an unavailable scanner stops the run with exit code 3 before a scan starts.

--lang names the main language instead of the bundle's (multilanguage for all detected languages), and --git-history adds mlsast_git_history (the archive then includes .git).

Only what a merge request changed

--changed-only (SCANSUITE_CHANGED_ONLY=1) scans the files changed since the merge base with the target branch. Merge and pull request pipelines report the target branch themselves; elsewhere give it with --base. When a shallow clone lacks the target branch, the client fetches it. Only scanners that can scan selected files run (mlsast, sast_quick, sast_full, sast_custom, iacs_kics): secrets and dependency checks need the whole repository and are skipped, with a warning when a dependency manifest changed. When nothing changed the job passes; when no base can be found a full scan runs, with a warning. It cannot be combined with --mode or --scope.

Upload or clone

By default (--source auto) the runner uploads its checkout as an archive: only the files Git tracks, from the CI workspace or --source-dir, minus --exclude patterns. The server scans exactly the commit the pipeline runs on, private repositories need no extra access, and findings link to the files in your repository at that commit.

With --source git (chosen automatically when --git-url or --mode incremental is given) the server clones the repository instead, at the branch head when the scan starts. Private repositories are cloned over SSH with the team's key: Teams page, Scanning tab, Team SSH key. Pipeline scans always use the team key, never a person's own key (see Git repository authentication). The URL must not contain credentials. --mode incremental scans only what changed since the previous scan of the branch and passes when nothing did.

--mode custom-scope --scope PATTERN (repeatable, or --scope-file FILE) scans only the files the patterns match; scanners that cannot be limited to files are left out, with a note.

Web application and infrastructure scans

Give the targets with --target (repeatable, or separated by commas, spaces or ;) or SCANSUITE_TARGETS. The team's target policy must allow each one, unless Allow is set to Any target; a refused target stops the run with exit code 3 before anything starts, and the message names it. The rules for targets are on Web App Scanning. The secrets gate does not apply to these scans.

scansuite-ci --scan-type dast --target https://staging.example.com \
  --profile standard --header "Authorization: Bearer $STAGING_TOKEN" --junit scansuite-dast.xml

To scan behind a login, pass --header "Name: value" (several separated by |) or --cookie "key=value" (several separated by ;). Keep such values in CI secrets, not in the job file.

Infrastructure scans have no profiles: name the scanners with --scanners.

# Two hosts, the top 1000 TCP and UDP ports, including hosts that do not answer ping
scansuite-ci --scan-type infra --scanners openvas,nuclei \
  --target 10.0.4.10,10.0.4.11 --ports "Top 1000 TCP/UDP" --no-ping --fail-on-severity critical

# A container image
scansuite-ci --scan-type infra --scanners docker_image_scan \
  --target registry.example.com/shop/api:1.4.2

In GitLab, set SCANSUITE_PORTS rather than passing --ports in SCANSUITE_EXTRA_ARGS: that variable is split on spaces, so Top 1000 TCP/UDP would break apart.

When the build fails

Findings from this scan that are Open or In Progress count. Findings AI verification marked unreachable do not, unless you add --include-unreachable. What the classic scanner tools report counts only when the team stores it: Teams page, Scanning tab, Scanner findings in Vulnerabilities (on by default).

• A target that does not answer is a warning in the scan log, not a failure: the scan ends Finished and the gate decides on what the other targets returned.
• What two scanners of one scan report for the same issue on the same service is one finding: it blocks once, at the higher severity.
• If one of the scanners did not complete, the build fails with exit code 2 even when nothing else blocks it; findings from the scanners that did complete still fail it with exit code 1.
• The first scan of a product sees every secret as new, so it fails on secrets already committed. Triage them in ScanSuite, or start with --fail-on-secrets none.

Exit codes

A failed run ends with a line naming its exit code and what it means, for example [scansuite] Exit code 3: configuration error: option, token, permission, target or certificate. Some CI systems, GitLab among them, show every failed job as exit code 1; that line tells you which failure it was. --soft-fail turns codes 2, 4 and 5 into 0 with a warning, so a ScanSuite outage does not block a release; codes 1 and 3 still fail the job.

Reports

The job log lists every blocking finding and secret with the rule that blocked it; --max-print N limits how many (50 by default).

Waiting and cancelling

The client follows the scan until it ends, checking every 20 seconds for up to two hours. When the CI job is cancelled, the client cancels its scan (the token needs Stop scans, which the CI pipeline preset includes). A request repeated after a network error picks up the scan already started instead of starting another, a busy server is retried, and separate CI runs never share a scan.

TLS certificates

With a self-signed certificate, or one from a CA the runner does not know, the client warns and goes on without verifying it. Give the CA certificate with --ca-bundle to verify it, or add --strict-tls to stop with exit code 3 instead. A CA-signed certificate for another host, or an expired one, always stops the run.

All options

Every option the client takes. Boolean variables accept 1, true or yes. A variable is read only when the option is not given.

Server and product

What to scan

Static analysis: source and selection

--changed-only, --mode, --scope and --git-url are for --scan-type sast only, and --changed-only cannot be combined with --mode or --scope (exit 3).

Waiting

Quality gate

Output