GitHub Actions Integration

Integrate Code Pathfinder directly into your GitHub workflows for automated security scanning on every push and pull request.

PR Comments & Inline Findings

Code Pathfinder can post security findings as PR summary comments and inline review annotations on GitHub pull requests — no GHAS subscription required. Read the full walkthrough →

Quick Start

Add this workflow to .github/workflows/security-scan.yml:

yaml

name: Security Scan

on: [push, pull_request]

permissions:
  security-events: write
  contents: read

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Security Scan
        uses: shivasurya/code-pathfinder@v2.0.2
        with:
          ruleset: python/all, docker/all, docker-compose/all
          fail-on: critical,high

      - name: Upload to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: pathfinder-results.sarif

Version Pinning

Always pin to a specific version like @v2.0.2 for stability. Using @main may introduce breaking changes.

Configuration Options

All inputs are optional except you must specify either rules or ruleset. The ruleset input accepts comma-separated values.

Input	Description	Default
rules	Path to local Python SDK rules file or directory	—
ruleset	Remote ruleset(s) from codepathfinder.dev/registry. Comma-separated for multiple.	—
project	Path to source code to scan	.
skip-tests	Skip scanning test files (`test_.py`, `_test.py`, etc.)	true
output	Output format: sarif, json, or csv	sarif
output-file	Output file path	pathfinder-results.sarif
fail-on	Fail build on 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
pr-comment	Post a summary comment on the pull request with scan results	false
pr-inline	Post inline review comments for critical/high severity findings	false
github-token	GitHub token for posting PR comments. Required when `pr-comment` or `pr-inline` is enabled.	—
disable-metrics	Disable anonymous usage metrics collection	false
python-version	Python version used to install the action	3.12

Common Use Cases

Python Security

Scan Python projects for vulnerabilities:

yaml

- name: Python Security Scan
  uses: shivasurya/code-pathfinder@v2.0.2
  with:
    ruleset: python/all
    fail-on: critical,high

Docker Security

Scan Dockerfiles and docker-compose files:

yaml

- name: Docker Security Scan
  uses: shivasurya/code-pathfinder@v2.0.2
  with:
    ruleset: docker/all, docker-compose/all
    verbose: true

Custom Rules

Use your own security rules written with the Python SDK:

yaml

- name: Custom Security Scan
  uses: shivasurya/code-pathfinder@v2.0.2
  with:
    rules: .security/custom-rules.py
    output: json
    output-file: scan-results.json

Block on Critical Findings

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

yaml

- name: Security Gate
  uses: shivasurya/code-pathfinder@v2.0.2
  with:
    ruleset: python/all, docker/all, docker-compose/all
    fail-on: critical,high

GitHub Code Scanning Integration

Upload SARIF results to GitHub Advanced Security for security alerts, code annotations, and vulnerability tracking.

yaml

name: Security Scan

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

permissions:
  security-events: write
  contents: read

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Code Pathfinder
        uses: shivasurya/code-pathfinder@v2.0.2
        with:
          ruleset: python/all, docker/all, docker-compose/all
          project: .
          verbose: true

      - name: Upload SARIF to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: pathfinder-results.sarif

SARIF Upload

Use if: always() to ensure SARIF uploads even when the scan finds vulnerabilities and exits with code 1. This provides visibility in GitHub's Security tab regardless of scan outcome.

PR Comments & Inline Findings

Code Pathfinder can post a summary comment and inline review annotations directly on pull requests — no GHAS subscription needed. Enable pr-comment and/or pr-inline with a GitHub token:

yaml

- name: Run Code Pathfinder
  uses: shivasurya/code-pathfinder@v2.0.2
  with:
    ruleset: python/all, docker/all, docker-compose/all
    pr-comment: ${{ github.event_name == 'pull_request' }}
    pr-inline: ${{ github.event_name == 'pull_request' }}
    github-token: ${{ secrets.GITHUB_TOKEN }}

Troubleshooting

No vulnerabilities detected

Enable debug and verbose output to see what is being scanned:

yaml

- name: Run Code Pathfinder
  uses: shivasurya/code-pathfinder@v2.0.2
  with:
    ruleset: python/all
    debug: true
    verbose: true

Scan full codebase instead of changed files

By default, diff-aware scanning only scans changed files. Disable it to scan everything:

yaml

- name: Run Code Pathfinder
  uses: shivasurya/code-pathfinder@v2.0.2
  with:
    ruleset: python/all
    no-diff: true

Scans timing out

Scan a specific subdirectory to reduce scope:

yaml

- name: Run Code Pathfinder
  uses: shivasurya/code-pathfinder@v2.0.2
  with:
    ruleset: python/all
    project: ./src

Cache issues with remote rulesets

Force refresh cached rulesets:

yaml

- name: Run Code Pathfinder
  uses: shivasurya/code-pathfinder@v2.0.2
  with:
    ruleset: python/all
    refresh-rules: true

Security Considerations

The GitHub Action implements defense-in-depth against command injection:

All user inputs are validated before execution
Dangerous shell metacharacters are blocked
Bash arrays with proper quoting prevent injection
No use of eval, source, or code evaluation

Version pinning prevents supply chain attacks:

yaml

# ✅ Good - pins to specific release
uses: shivasurya/code-pathfinder@v2.0.2

# ⚠️ Risky - always pulls latest changes
uses: shivasurya/code-pathfinder@main