GitLab CI Integration

Integrate Code Pathfinder into your GitLab CI pipelines for automated security scanning with Security Dashboard integration.

Quick Start

Add this to your .gitlab-ci.yml:

yaml

stages:
  - security

security-scan:
  stage: security
  image:
    name: shivasurya/code-pathfinder:stable-latest
    entrypoint: [""]
  script:
    - pathfinder ci --project . --ruleset python/all --ruleset docker/all --ruleset docker-compose/all --output sarif --output-file pathfinder-results.sarif --fail-on critical,high
  artifacts:
    reports:
      sast: pathfinder-results.sarif
    paths:
      - pathfinder-results.sarif
    when: always

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.

Configuration Options

All pathfinder ci flags are available in the script step.

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

security-scan:
  stage: security
  image:
    name: shivasurya/code-pathfinder:stable-latest
    entrypoint: [""]
  script:
    - pathfinder ci --project . --ruleset python/all --fail-on critical,high --output sarif --output-file results.sarif
  artifacts:
    reports:
      sast: results.sarif
    when: always

Docker Security

Scan Dockerfiles and docker-compose files:

yaml

security-scan:
  stage: security
  image:
    name: shivasurya/code-pathfinder:stable-latest
    entrypoint: [""]
  script:
    - pathfinder ci --project . --ruleset docker/all --ruleset docker-compose/all --verbose --output sarif --output-file results.sarif
  artifacts:
    reports:
      sast: results.sarif
    when: always

Block on Critical Findings

Fail the pipeline if critical or high severity issues are found:

yaml

security-scan:
  stage: security
  image:
    name: shivasurya/code-pathfinder:stable-latest
    entrypoint: [""]
  script:
    - pathfinder ci --project . --ruleset python/all --ruleset docker/all --ruleset docker-compose/all --fail-on critical,high --output sarif --output-file results.sarif
  artifacts:
    reports:
      sast: results.sarif
    when: always
  allow_failure: false

GitLab Security Dashboard

GitLab automatically displays SARIF reports in the Security Dashboard when using artifacts.reports.sast. Name the file gl-sast-report.sarif by convention:

yaml

security-scan:
  stage: security
  image:
    name: shivasurya/code-pathfinder:stable-latest
    entrypoint: [""]
  script:
    - pathfinder ci --project . --ruleset python/all --ruleset docker/all --ruleset docker-compose/all --output sarif --output-file gl-sast-report.sarif
  artifacts:
    reports:
      sast: gl-sast-report.sarif
    when: always

GitLab Security Dashboard

Use the artifacts.reports.sast key to integrate with GitLab's Security Dashboard. Findings appear in merge requests and the project's Security tab automatically.

Merge Request Integration

Run the scan only on merge request events:

yaml

security-scan:
  stage: security
  image:
    name: shivasurya/code-pathfinder:stable-latest
    entrypoint: [""]
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - pathfinder ci --project . --ruleset python/all --ruleset docker/all --ruleset docker-compose/all --output sarif --output-file results.sarif
  artifacts:
    reports:
      sast: results.sarif
    when: always

Scheduled Scans

Create a scheduled pipeline in GitLab (CI/CD → Schedules) and restrict the job to run only on schedules:

yaml

security-scan:
  stage: security
  image:
    name: shivasurya/code-pathfinder:stable-latest
    entrypoint: [""]
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  script:
    - pathfinder ci --project . --ruleset python/all --ruleset docker/all --ruleset docker-compose/all --output sarif --output-file results.sarif
  artifacts:
    reports:
      sast: results.sarif
    when: always

Troubleshooting

No vulnerabilities detected

Enable debug and verbose output:

yaml

security-scan:
  stage: security
  image:
    name: shivasurya/code-pathfinder:stable-latest
    entrypoint: [""]
  script:
    - pathfinder ci --project . --ruleset python/all --debug --verbose --output sarif --output-file results.sarif
  artifacts:
    reports:
      sast: results.sarif
    when: always

Scan full codebase instead of changed files

Disable diff-aware scanning to scan everything:

yaml

script:
  - pathfinder ci --project . --ruleset python/all --no-diff --output sarif --output-file results.sarif

Pipeline timeout

Scan a subdirectory to reduce scope, or set a longer job timeout:

yaml

security-scan:
  timeout: 1h
  image:
    name: shivasurya/code-pathfinder:stable-latest
    entrypoint: [""]
  script:
    - pathfinder ci --project ./src --ruleset python/all --output sarif --output-file results.sarif
  artifacts:
    reports:
      sast: results.sarif
    when: always

Cache issues with remote rulesets

Force refresh cached rulesets:

yaml

script:
  - pathfinder ci --project . --ruleset python/all --refresh-rules --output sarif --output-file results.sarif