CircleCI Integration

Integrate Code Pathfinder into your CircleCI pipelines for automated security scanning using the official Docker image.

Quick Start

Add this to your .circleci/config.yml:

yaml

version: 2.1

jobs:
  code-pathfinder-sast:
    docker:
      - image: shivasurya/code-pathfinder:stable-latest
    steps:
      - checkout
      - run:
          name: Run Code Pathfinder SAST
          command: |
            pathfinder ci --project . \
              --ruleset python/all \
              --ruleset docker/all \
              --ruleset docker-compose/all \
              --output sarif \
              --output-file pathfinder-results.sarif \
              --fail-on critical,high
      - store_artifacts:
          path: pathfinder-results.sarif
          destination: pathfinder-results.sarif

workflows:
  security-scan:
    jobs:
      - code-pathfinder-sast

Version Pinning

Pin to a specific image tag like shivasurya/code-pathfinder:v2.0.2 instead of stable-latest for reproducible builds. stable-latest always tracks the latest stable release.

No native SARIF viewer in CircleCI

CircleCI does not display SARIF files natively. The artifact is downloadable from the Artifacts tab. Omit --output-file to stream results to the job log as SARIF on stdout instead.

Configuration Options

All pathfinder ci flags can be passed in the command block.

Flag	Description	Default
--rules	Path to local Python SDK rules file or directory	—
--ruleset	Remote ruleset(s) from codepathfinder.dev/registry. Use multiple `--ruleset` flags for multiple rulesets.	—
--project	Path to source code to scan	.
--skip-tests	Skip test files (test_.py, _test.py, conftest.py)	true
--output	Output format: sarif, json, or csv	sarif
--output-file	Write output to file. Omit to stream to stdout.	—
--fail-on	Exit code 1 if findings match severities: critical, high, medium, low (comma-separated)	—
--no-diff	Disable diff-aware scanning and scan all files	false
--verbose	Show statistics and timing information	false
--debug	Show detailed debug diagnostics with timestamps	false
--refresh-rules	Force refresh of cached rulesets	false

Common Use Cases

Python Security

Scan Python projects for vulnerabilities:

yaml

jobs:
  python-sast:
    docker:
      - image: shivasurya/code-pathfinder:stable-latest
    steps:
      - checkout
      - run:
          name: Python Security Scan
          command: |
            pathfinder ci --project . \
              --ruleset python/all \
              --fail-on critical,high \
              --output sarif \
              --output-file results.sarif
      - store_artifacts:
          path: results.sarif

Docker Security

Scan Dockerfiles and docker-compose files:

yaml

jobs:
  docker-sast:
    docker:
      - image: shivasurya/code-pathfinder:stable-latest
    steps:
      - checkout
      - run:
          name: Docker Security Scan
          command: |
            pathfinder ci --project . \
              --ruleset docker/all \
              --ruleset docker-compose/all \
              --output sarif \
              --output-file results.sarif
      - store_artifacts:
          path: results.sarif

PR-only Scanning

Run scans only on non-main branches (i.e. PR branches) using workflow filters:

yaml

workflows:
  pr-security-scan:
    jobs:
      - code-pathfinder-sast:
          filters:
            branches:
              ignore: main

Monorepo — Parallel Jobs

Scan multiple directories in parallel:

yaml

version: 2.1

jobs:
  scan-backend:
    docker:
      - image: shivasurya/code-pathfinder:stable-latest
    steps:
      - checkout
      - run:
          name: Scan Backend
          command: |
            pathfinder ci --project ./backend \
              --ruleset python/all \
              --output sarif --output-file backend-results.sarif
      - store_artifacts:
          path: backend-results.sarif

  scan-infra:
    docker:
      - image: shivasurya/code-pathfinder:stable-latest
    steps:
      - checkout
      - run:
          name: Scan Infrastructure
          command: |
            pathfinder ci --project ./infrastructure \
              --ruleset docker/all \
              --ruleset docker-compose/all \
              --output sarif --output-file infra-results.sarif
      - store_artifacts:
          path: infra-results.sarif

workflows:
  security-scan:
    jobs:
      - scan-backend
      - scan-infra

Viewing Results

CircleCI has no native SARIF viewer. Two options to see findings:

Stream to job log (stdout)

Omit --output-file — results stream as SARIF JSON to stdout and appear in the job log:

yaml

- run:
    name: Run Code Pathfinder SAST
    command: |
      pathfinder ci --project . \
        --ruleset python/all \
        --ruleset docker/all \
        --ruleset docker-compose/all \
        --output sarif

Save as downloadable artifact

Use store_artifacts to make the SARIF file available in the Artifacts tab:

yaml

- run:
    name: Run Code Pathfinder SAST
    command: |
      pathfinder ci --project . \
        --ruleset python/all \
        --ruleset docker/all \
        --ruleset docker-compose/all \
        --output sarif \
        --output-file pathfinder-results.sarif
- store_artifacts:
    path: pathfinder-results.sarif

Scheduled Scans

CircleCI uses Scheduled Pipelines configured via the UI or API — not via config.yml. The legacy triggers/schedule syntax in config is deprecated.

Go to Project Settings → Triggers in the CircleCI UI
Add a new scheduled trigger with your cron expression (e.g. 0 0 * * 0 for weekly)
Point it at the workflow below

Your config.yml just needs the job and workflow defined:

yaml

version: 2.1

jobs:
  code-pathfinder-sast:
    docker:
      - image: shivasurya/code-pathfinder:stable-latest
    steps:
      - checkout
      - run:
          name: Run Code Pathfinder SAST
          command: |
            pathfinder ci --project . \
              --ruleset python/all \
              --ruleset docker/all \
              --ruleset docker-compose/all \
              --output sarif \
              --output-file pathfinder-results.sarif
      - store_artifacts:
          path: pathfinder-results.sarif

workflows:
  security-scan:
    jobs:
      - code-pathfinder-sast

Troubleshooting

No vulnerabilities detected

Enable debug and verbose mode to see exactly what is being scanned:

yaml

- run:
    name: Run Code Pathfinder SAST
    command: |
      pathfinder ci --project . \
        --ruleset python/all \
        --debug --verbose \
        --output sarif \
        --output-file results.sarif

Job timeout

CircleCI defaults to a 10-minute no-output timeout. Use no_output_timeout for large repos, or scan a subdirectory:

yaml

- run:
    name: Run Code Pathfinder SAST
    no_output_timeout: 30m
    command: |
      pathfinder ci --project ./src \
        --ruleset python/all \
        --verbose \
        --output sarif \
        --output-file results.sarif

Force full scan (disable diff-aware)

By default, pathfinder ci auto-detects CI context and may scan only changed files. Force a full scan:

yaml

- run:
    name: Run Code Pathfinder SAST
    command: |
      pathfinder ci --project . \
        --ruleset python/all \
        --no-diff \
        --output sarif \
        --output-file results.sarif

Cache issues with remote rulesets

Force refresh cached rulesets:

yaml

- run:
    name: Run Code Pathfinder SAST
    command: |
      pathfinder ci --project . \
        --ruleset python/all \
        --refresh-rules \
        --output sarif \
        --output-file results.sarif