CI — Scan in your pipeline

Scan every push and pull request with CodesGuard — your code and its dependencies, in one scan — and let your organisation's policy decide whether the build may pass.

What a CI scan does

1. Create a CI token

An owner or admin creates one under Security → CI tokens (see Security & 2FA): give it a name, optionally limit it to one project, and choose when it expires. The token (cgci_…) is shown once — store it as a secret in your CI system.

2. The CI client

One Python file (Python 3.9 or later, standard library only) uploads the code, waits for the scan and turns the verdict into the job's result:

Keep a copy in your repository, or download it in the job and check it against the checksum above, as the examples below do.

3. GitHub Actions

Add the token as the repository secret CODEGUARD_TOKEN, and your organisation and project ids as the variables CODEGUARD_ORG_ID and CODEGUARD_PROJECT_ID (the project id is optional for a token made for one project). Then add .github/workflows/codeguard.yml:

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

permissions:
  contents: read
  security-events: write   # for the code scanning upload

jobs:
  codeguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: CodesGuard scan
        env:
          CODEGUARD_TOKEN: ${{ secrets.CODEGUARD_TOKEN }}
          CODEGUARD_ORG_ID: ${{ vars.CODEGUARD_ORG_ID }}
          CODEGUARD_PROJECT_ID: ${{ vars.CODEGUARD_PROJECT_ID }}
          CODEGUARD_APP_URL: https://codesguard.io
        run: |
          curl -fsSL -o codeguard_ci.py https://docs.codesguard.io/assets/ci/codeguard_ci.py
          echo "2b10dc80dc68f614f1fe608f7d1176f189931617e10dccc695a261fe1878278c  codeguard_ci.py" | sha256sum -c -
          python3 codeguard_ci.py --path . --sarif codeguard.sarif
      - name: Upload to code scanning
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: codeguard.sarif

In a pull request the client compares with the target branch's latest scan by itself; set --base-branch to compare with another branch, or --no-diff to judge the whole scan.

4. GitLab CI

Set CODEGUARD_TOKEN (masked), CODEGUARD_ORG_ID and CODEGUARD_PROJECT_ID under Settings → CI/CD → Variables, and add the job to .gitlab-ci.yml:

codeguard:
  stage: test
  image: python:3.12-slim
  variables:
    CODEGUARD_APP_URL: https://codesguard.io
  script:
    - python3 -c "import urllib.request; urllib.request.urlretrieve('https://docs.codesguard.io/assets/ci/codeguard_ci.py', 'codeguard_ci.py')"
    - echo "2b10dc80dc68f614f1fe608f7d1176f189931617e10dccc695a261fe1878278c  codeguard_ci.py" | sha256sum -c -
    - python3 codeguard_ci.py --path . --sarif codeguard.sarif --codequality gl-code-quality-report.json
  artifacts:
    when: always
    paths:
      - codeguard.sarif
    reports:
      codequality: gl-code-quality-report.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

The failing findings of a merge request appear on it, in its code quality report.

5. Any other pipeline

export CODEGUARD_TOKEN=cgci_… CODEGUARD_ORG_ID=… CODEGUARD_PROJECT_ID=…
python3 codeguard_ci.py --path . --sarif codeguard.sarif --base-branch main

The scan has no time limit of its own: the job waits until it is done. Use your CI system's job timeout if you want one.

Programmatic access — API & webhooks

The release gate is one use of the platform API. The same authenticated access lets you drive CodesGuard from your own tools:

IAST in your pipeline

The CI scan above analyses your source and dependencies before the app runs. IAST adds the runtime half: attach its in-process agent to your JVM service in the same CI or staging job with a single -javaagent flag and a project token, then run your test suite or a DAST scan. Confirmed vulnerabilities — each with the request, code path and stack trace — stream into the same Findings queue. IAST is in early access (JVM first).

The policy

What fails a scan is your organisation's scan policy (Organization → Scan policy), or a project's own (the project's Settings tab → Scan policy → Customize): a severity threshold for code and dependency findings, fixable-only, malicious packages, possible typosquats, licenses your license policy denies, known-exploited vulnerabilities, an exploit-likelihood threshold, the age of an advisory, and whether a pull request is judged only on what it introduces. Until you change it, a scan fails on any open critical or high finding, a malicious package, a possible typosquat, or a package whose license your license policy denies. Marking a finding remediated or not processed, or a package not affected, counts at once — no rescan.