Bitbucket Pipelines Integration

Integrate Code Pathfinder into your Bitbucket Pipelines for automated security scanning using the official Docker image.

Quick Start

Add this to your bitbucket-pipelines.yml:

yaml

image: shivasurya/code-pathfinder:stable-latest

pipelines:
  pull-requests:
    '**':
      - step:
          name: Code Pathfinder SAST
          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:
            - pathfinder-results.sarif
  default:
    - step:
        name: Code Pathfinder SAST
        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:
          - pathfinder-results.sarif

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 Bitbucket

Bitbucket does not natively display SARIF files — the artifact is a downloadable file only. Unlike GitHub (Code Scanning tab) or GitLab (Security Dashboard), there is no built-in security findings UI. To surface findings as PR annotations, use the Bitbucket Code Insights API.

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

pipelines:
  default:
    - step:
        name: Python Security Scan
        script:
          - pathfinder ci --project . --ruleset python/all --fail-on critical,high --output sarif --output-file results.sarif
        artifacts:
          - results.sarif

Docker Security

Scan Dockerfiles and docker-compose files:

yaml

pipelines:
  default:
    - step:
        name: Docker Security Scan
        script:
          - pathfinder ci --project . --ruleset docker/all --ruleset docker-compose/all --verbose --output sarif --output-file results.sarif
        artifacts:
          - results.sarif

Monorepo Parallel Scans

Scan specific directories in a monorepo:

yaml

pipelines:
  default:
    - parallel:
        - step:
            name: Scan Backend
            script:
              - pathfinder ci --project ./backend --ruleset python/all --output sarif --output-file backend-results.sarif
            artifacts:
              - backend-results.sarif
        - step:
            name: Scan Infrastructure
            script:
              - pathfinder ci --project ./infrastructure --ruleset docker/all --ruleset docker-compose/all --output sarif --output-file infra-results.sarif
            artifacts:
              - infra-results.sarif

Security Gate

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

yaml

pipelines:
  default:
    - step:
        name: Security Gate
        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:
          - results.sarif

Pull Request Integration

Run on both the default branch and all pull requests:

yaml

image: shivasurya/code-pathfinder:stable-latest

pipelines:
  default:
    - step:
        name: Code Pathfinder SAST
        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:
          - pathfinder-results.sarif
  pull-requests:
    '**':
      - step:
          name: PR Security Scan
          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:
            - pathfinder-results.sarif

Scheduled Scans

Run security scans on a schedule using Bitbucket's custom pipeline trigger:

yaml

image: shivasurya/code-pathfinder:stable-latest

pipelines:
  custom:
    weekly-security-scan:
      - step:
          name: Weekly SAST Scan
          script:
            - pathfinder ci --project . --ruleset python/all --ruleset docker/all --ruleset docker-compose/all --output sarif --output-file pathfinder-results.sarif
          artifacts:
            - pathfinder-results.sarif

Schedule the weekly-security-scan custom pipeline via Repository settings > Schedules in the Bitbucket UI.

Troubleshooting

Pipeline not triggering on pull requests

The default pipeline runs on branch pushes, not PR creation. Add a pull-requests section to trigger on PRs:

yaml

pipelines:
  pull-requests:
    '**':       # matches all PR source branches
      - step:
          name: Code Pathfinder SAST
          script:
            - pathfinder ci --project . --ruleset python/all --output sarif --output-file results.sarif
          artifacts:
            - results.sarif

Also ensure Pipelines are enabled: Repository settings → Pipelines → Settings → Enable Pipelines.

No vulnerabilities detected

Enable debug and verbose output to see detailed scan progress:

yaml

script:
  - pathfinder ci --project . --ruleset python/all --debug --verbose --output sarif --output-file results.sarif

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

Large repositories

For large codebases, double the step's memory and CPU allocation:

yaml

- step:
    name: Code Pathfinder SAST
    size: 2x
    script:
      - pathfinder ci --project . --ruleset python/all --ruleset docker/all --ruleset docker-compose/all --output sarif --output-file results.sarif
    artifacts:
      - results.sarif

Pipeline timeout

Bitbucket's default step limit is 120 minutes. Override with max-time (in minutes) or scan a subdirectory:

yaml

- step:
    name: Code Pathfinder SAST
    max-time: 60
    script:
      - pathfinder ci --project ./src --ruleset python/all --output sarif --output-file results.sarif
    artifacts:
      - results.sarif

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