CI/CD

Run inkdex in GitHub Actions, GitLab CI or any pipeline: license with a CI token, SARIF upload, and failing the build on what matters.

In a pipeline, inkdex needs:

the binaries, installed from mlab's package repository in the job (see Install);
a CI token in the INKDEX_TOKEN variable (see License).

Nothing else: the index is built in the job.

The command

inkdex-vuln scan . --update --format sarif -o inkdex.sarif --fail-on high

--update builds the index in the job.
--format sarif -o inkdex.sarif writes a report code-scanning tools read.
--fail-on high makes the job fail (exit code 1) when a finding is high or critical. Exit code 2 means inkdex itself could not run (no license, bad path).

In CI the progress display is off and the output is plain text.

GitHub Actions

name: inkdex
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write        # to upload SARIF
    env:
      INKDEX_TOKEN: ${{ secrets.INKDEX_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - name: Install inkdex
        run: |
          sudo install -m 0755 -d /etc/apt/keyrings
          sudo curl -fsSL https://apt.mlab.sh/mlab.asc -o /etc/apt/keyrings/mlab.asc
          printf 'Types: deb\nURIs: https://apt.mlab.sh\nSuites: stable\nComponents: main\nSigned-By: /etc/apt/keyrings/mlab.asc\n' \
            | sudo tee /etc/apt/sources.list.d/mlab.sources >/dev/null
          sudo apt-get update && sudo apt-get install -y inkdex inkdex-vuln
      - name: Scan
        run: inkdex-vuln scan . --update --format sarif -o inkdex.sarif --fail-on high
      - name: Upload to code scanning
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: inkdex.sarif

Findings then show in the repository's Security › Code scanning, and on pull requests. Their fingerprints let GitHub follow an alert when code moves.

GitLab CI

inkdex:
  image: ubuntu:24.04
  variables:
    INKDEX_TOKEN: $INKDEX_TOKEN        # a masked CI/CD variable
  script:
    - apt-get update && apt-get install -y curl ca-certificates
    - install -m 0755 -d /etc/apt/keyrings
    - curl -fsSL https://apt.mlab.sh/mlab.asc -o /etc/apt/keyrings/mlab.asc
    - |
      printf 'Types: deb\nURIs: https://apt.mlab.sh\nSuites: stable\nComponents: main\nSigned-By: /etc/apt/keyrings/mlab.asc\n' > /etc/apt/sources.list.d/mlab.sources
    - apt-get update && apt-get install -y inkdex inkdex-vuln
    - inkdex-vuln scan . --update --format json -o inkdex.json --fail-on high
  artifacts:
    when: always
    paths: [inkdex.json]

Only what a change introduces

On a pull request you may want to fail only on what the change adds. --since scans the base revision too and reports only the findings it does not have:

inkdex-vuln scan . --update --since origin/main --fail-on high

Or keep the report of the main branch as an artifact and compare against it:

inkdex-vuln scan . --update --format json -o main.json                # on main
inkdex-vuln scan . --update --baseline main.json --fail-on high       # on the pull request

For a summary in the job's page, or a pull request comment, write Markdown:

      - name: Summary
        if: always()
        run: inkdex-vuln scan . --format markdown >> "$GITHUB_STEP_SUMMARY"

To compare the code itself (symbols, flows, dependencies), index both revisions and diff them:

inkdex init
inkdex index --commit origin/main
inkdex index
inkdex diff origin/main HEAD --markdown        # what changed: symbols, flows, dependencies
inkdex diff origin/main --gate                 # exit 1 on a new unsanitized flow
inkdex diff origin/main HEAD --sarif > new.sarif

Keeping the index between jobs

Indexing is incremental. Caching .inkdex/ between runs (keyed on the branch) makes later jobs re-read only what changed:

      - uses: actions/cache@v4
        with:
          path: .inkdex
          key: inkdex-${{ github.ref_name }}-${{ github.sha }}
          restore-keys: inkdex-${{ github.ref_name }}-

Good practice

One CI token per pipeline, so usage and revocation are per pipeline.
Keep the token in your CI's secret store, never in the repository.
Start with --fail-on critical, then tighten once the existing findings are reviewed.
Put the threshold and the reviewed findings in .inkdex-vuln.toml (fail_on, [[ignore]]): developers and the pipeline then see the same report. See Ignoring findings.