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-[email protected]
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-[email protected]
with:
ruleset: python/all
fail-on: critical,high
Docker Security
Scan Dockerfiles and docker-compose files:
yaml
- name: Docker Security Scan
uses: shivasurya/code-[email protected]
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-[email protected]
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-[email protected]
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-[email protected]
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-[email protected]
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-[email protected]
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-[email protected]
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-[email protected]
with:
ruleset: python/all
project: ./src
Cache issues with remote rulesets
Force refresh cached rulesets:
yaml
- name: Run Code Pathfinder
uses: shivasurya/code-[email protected]
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-[email protected]
# ⚠️ Risky - always pulls latest changes
uses: shivasurya/code-pathfinder@main