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

Quick Start

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

name: Security Scan

on: [push, pull_request]

permissions:
  security-events: write
  contents: read

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

  - name: Run Security Scan
    uses: shivasurya/code-pathfinder@v1.2.0
    with:
      ruleset: python/deserialization, docker/security

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

:::tip[Version Pinning] Always pin to a specific version like @v1.2.0 for stability. Using @main may introduce breaking changes. :::

Configuration Options

All inputs are optional except you must specify either rules or ruleset.

Rule Sources

Scan Configuration

Output Options

Advanced Options

Common Use Cases

Python Security

Scan Python projects for deserialization, Django, and Flask vulnerabilities:

- name: Python Security Scan
  uses: shivasurya/code-pathfinder@v1.2.0
  with:
ruleset: python/deserialization, python/django, python/flask
fail-on: critical,high

Docker Security

Scan Dockerfiles and docker-compose files:

- name: Docker Security Scan
  uses: shivasurya/code-pathfinder@v1.2.0
  with:
ruleset: docker/security, docker/best-practice
verbose: true

Custom Rules

Use your own security rules written with Python SDK:

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

Fail on Critical

Block PRs if critical or high severity issues are found:

- name: Security Scan with Blocking
  uses: shivasurya/code-pathfinder@v1.2.0
  with:
ruleset: python/deserialization, docker/security
fail-on: critical,high

Debug Mode

Enable debug output to troubleshoot scanning issues:

- name: Debug Security Scan
  uses: shivasurya/code-pathfinder@v1.2.0
  with:
ruleset: python/deserialization
debug: true
verbose: true

Remote Rulesets

Code Pathfinder provides curated security rulesets hosted at codepathfinder.dev/registry.

Python Rulesets

• python/deserialization - Unsafe pickle.loads() RCE detection
• python/django - Django SQL injection patterns
• python/flask - Flask security misconfigurations

Docker Rulesets

• docker/security - Critical and high-severity security issues
• docker/best-practice - Dockerfile optimization and best practices
• docker/performance - Performance optimization for container images

Using Multiple Rulesets

Scan with multiple rulesets in a single run:

ruleset: >-
  python/deserialization,
  python/django,
  python/flask,
  docker/security,
  docker/best-practice

The >- YAML syntax allows multi-line formatting for better readability.

GitHub Code Scanning Integration

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

Complete Workflow Example

name: Security Scan

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

# Required for uploading to GitHub Security tab
permissions:
  security-events: write
  contents: read

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

  - name: Run Code Pathfinder
    uses: shivasurya/code-pathfinder@v1.2.0
    with:
      ruleset: python/deserialization, docker/security
      project: .
      verbose: true

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

:::note[SARIF Upload] Use if: always() to ensure SARIF uploads even if the scan finds vulnerabilities. This provides visibility in GitHub's Security tab. :::

Output Formats

SARIF (Default)

GitHub-compatible format for security alerts:

output: sarif
output-file: pathfinder-results.sarif

JSON

Machine-readable format for custom processing:

output: json
output-file: scan-results.json

CSV

Spreadsheet-friendly format for reporting:

output: csv
output-file: vulnerabilities.csv

Text

Human-readable console output (not recommended for CI):

output: text

Troubleshooting

No vulnerabilities detected but expected

Enable debug mode to see what's being scanned:

debug: true
verbose: true

Scans timing out

Large repositories may need more resources. Consider scanning specific directories:

project: ./src

False positives

Exclude test files from scanning (enabled by default):

skip-tests: true

Cache issues with remote rulesets

Force refresh cached rulesets:

refresh-rules: true

Action Outputs

The action provides these outputs for use in subsequent steps:

Using Outputs

- name: Run Security Scan
  id: scan
  uses: shivasurya/code-pathfinder@v1.2.0
  with:
ruleset: python/deserialization

- name: Print Version
  run: echo "Scanned with version ${{ steps.scan.outputs.version }}"

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:

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

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

Examples Repository

For more examples, see the example workflows in the Code Pathfinder repository.