GitLab + Checkmarx
Complete Setup Guide

A fully automated security scanning pipeline. Once set up, no developer needs to do anything — pushing code is enough to trigger a scan.

GitLab CI drives everything. The runner invokes CxFlow which talks to Checkmarx. Checkmarx never reaches back into GitLab — clean, firewall-friendly.

This is done by whoever administers your Checkmarx instance. Do not use a personal account or the built-in cxadmin — create a dedicated service account.

1 — Log into Checkmarx Web UI as admin

https://checkmarx.company.local

Use the cxadmin account or any account with User Management permissions.

2 — Navigate to User Management

Top menu → Administration → User Management

3 — Create new user — fill in these exact values

4 — Assign roles — Scanner only

On the same screen under Roles:

5 — Click Save

The account is now created. Move to Step 02 to verify it works before touching GitLab.

Run this from the GitLab Runner host or any machine that can reach Checkmarx on port 443. Do this before setting any GitLab variables.

curl -X POST https://checkmarx.company.local/cxrestapi/auth/identity/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=svc-gitlab-ci" \
  -d "password=<the-password-you-set>" \
  -d "grant_type=password" \
  -d "scope=sast_rest_api" \
  -d "client_id=resource_owner_client" \
  -d "client_secret=014DF517-39D1-4453-B7B3-9930C563627C"

If it fails

You generate this yourself in GitLab. CxFlow uses it to post scan results back to MRs and the Security Dashboard.

1 — Navigate to Access Tokens

GitLab → Top-right avatar → Edit Profile → Access Tokens → Add new token

2 — Fill in these values

3 — Click Create token

Store the token in a password manager or Vault right now. You'll paste it into GitLab CI/CD Variables in the next step.

Set these at the group level — not per-project. Every repo under that group inherits them automatically. You only do this once.

1 — Navigate to Variables

GitLab → Your Group → Settings → CI/CD → Variables → Expand → Add variable

2 — Add these four variables exactly

Create this file in the root of every repo you want scanned. If you want it on all repos without touching each one, use GitLab's Compliance Pipelines or include: from a central project.

# Fire on every push to any branch AND on every MR
workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH'

stages:
  - sast

checkmarx-sast:
  stage: sast

  # Pin by SHA256 digest — never use :latest (see Step 06)
  image: checkmarx/cx-flow@sha256:<your-pinned-digest>

  variables:
    # Full scan on default branch, incremental (changed files only) on everything else
    IS_INCREMENTAL: >-
      $([[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]] && echo false || echo true)

  script:
    - |
      java -jar /app/cx-flow.jar \
        --scan \
        --cx-server="${CX_SERVER}" \
        --cx-user="${CX_USERNAME}" \
        --cx-password="${CX_PASSWORD}" \
        --cx-project="${CI_PROJECT_NAME}" \
        --app="${CI_PROJECT_NAME}" \
        --branch="${CI_COMMIT_REF_NAME}" \
        --repo-name="${CI_PROJECT_NAME}" \
        --namespace="${CI_PROJECT_NAMESPACE}" \
        --merge-id="${CI_MERGE_REQUEST_IID:-}" \
        --bug-tracker=GitLabDashboard \
        --f="${CI_PROJECT_DIR}" \
        --cx-flow.filter-severity=HIGH,CRITICAL \
        --incremental="${IS_INCREMENTAL}"

  # This is what makes results appear in GitLab UI
  artifacts:
    when: always          # upload report even if job fails
    reports:
      sast: gl-sast-report.json   # → Pipeline Security tab + MR widget
    paths:
      - gl-sast-report.json
    expire_in: 30 days

  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH && $CI_PIPELINE_SOURCE != "schedule"'

  allow_failure: false    # pipeline goes red on HIGH/CRITICAL findings

Image tags like :latest are mutable — upstream can overwrite them silently. A SHA256 digest is immutable. Run this once on any machine with Docker access.

docker pull checkmarx/cx-flow:latest
docker inspect --format='{{index .RepoDigests 0}}' checkmarx/cx-flow:latest

Output looks like:

checkmarx/cx-flow@sha256:a1b2c3d4e5f6789abc...

Copy the sha256:... part and paste it into your .gitlab-ci.yml:

# Before — unsafe
image: checkmarx/cx-flow:latest

# After — pinned, reproducible, auditable
image: checkmarx/cx-flow@sha256:a1b2c3d4e5f6789abc...

Commit the .gitlab-ci.yml to the repo and push. Then verify everything ran correctly.

1 — Trigger the first scan

# If the file is already in the repo, a push triggers it
git add .gitlab-ci.yml
git commit -m "chore: add Checkmarx SAST pipeline"
git push origin main

2 — Watch the pipeline

GitLab → CI/CD → Pipelines → click the running pipeline → checkmarx-sast job

3 — Confirm the report was uploaded

In the pipeline job detail page, look for the artifacts section — gl-sast-report.json should be listed. If it's there, GitLab picked it up.

4 — Confirm scan ran in Checkmarx

Checkmarx Web UI → Projects → look for a project named after your GitLab repo

Checkmarx auto-creates the project on first scan using $CI_PROJECT_NAME.

Pipeline Security tab — all tiers

CI/CD → Pipelines → <your pipeline> → Security tab

Lists every finding from that scan with severity, CWE, file, and line number.

MR security widget — all tiers

Merge Requests → <your MR> → scroll to Security widget at bottom of page

Shows only new findings introduced by that MR — not pre-existing ones. This is what blocks the merge when allow_failure: false.

Project Security Dashboard — GitLab Ultimate only

Security → Dashboard

Trend view of all findings over time across all scans in the project.

• Checkmarx Manager reachable from GitLab Runner host on port 443
• Checkmarx Scan Engine reachable on port 8088
• svc-gitlab-ci account created with Scanner role and password-never-expires
• Auth test (Step 02 curl) returns an access_token
• GitLab token created with api scope only, 90-day expiry
• All four group-level CI/CD variables set with correct Protected/Masked flags
• CxFlow image pinned by SHA256 digest — no :latest
• .gitlab-ci.yml committed to repo root
• Test push made and pipeline visible under CI/CD → Pipelines
• gl-sast-report.json visible in pipeline artifacts
• Security tab shows findings in GitLab pipeline
• Calendar reminder set to rotate GitLab token in 90 days