Code Pathfinder

With AI tools generating thousands of lines of code in seconds, the bottleneck has shifted from writing code to reviewing and securing it at scale. Traditional static analysis tools struggle with modern AI-generated codebases that mix languages, frameworks, and infrastructure-as-code in the same repository.

Code Pathfinder flips this model. Instead of brittle regex or AST pattern matching per language, it indexes your entire codebase as structured, queryable data (AST, CFG, DFG). Write language-agnostic queries that trace data flows across Python, Dockerfiles, and docker-compose in a single rule—critical for CVE detection and vulnerability research when you need to understand how dependencies are used, what privileges they run with, and what attack surface they expose.

What it is

• Open-source SAST that combines structural analysis (call graphs, dataflow, taint tracking) with AI to understand real exploit paths, not just regex hits.
• AI-powered vulnerability hunting via SecureFlow, which layers 10+ models (Claude, GPT, Gemini, Grok, Ollama, etc.) on top of deterministic analysis for context-aware triage.
• Developer-first workflow with IDE integration, CLI, and CI support so security checks land where code is written and reviewed.

Why it's different

• Graph-first engine: builds a rich representation of functions, endpoints, DB calls, and dataflows to cut false positives and surface real source‑to‑sink issues.
• LLM as validator, not oracle: uses models to explain, prioritize, and validate findings after structural analysis, keeping behavior predictable and reproducible.
• Privacy‑first, BYOK: your code stays local; you bring your own keys and talk directly to providers with no vendor-side code ingestion.

Where it fits in your stack

• Local & IDE: SecureFlow VS Code extension (VS Code Marketplace | Open VSX) for real‑time security feedback as you type.
• CLI & agents: SecureFlow CLI runs agentic loops over your repo (profile, read, trace, validate) to hunt vulnerabilities with the same ergonomics as modern AI coding tools.
• Pipelines & reporting: integrates into CI/CD and exports to formats and systems like SARIF, GitHub Advanced Security, and DefectDojo so findings flow into existing governance.

Project components

• Code Pathfinder CLI – structural security scanner and query engine for code graphs, better than grep/AST‑only search for paths and patterns.
• SecureFlow CLI – AI‑powered vulnerability hunter that uses agent loops and 10+ models for deep, context‑aware scans across real projects.
• SecureFlow VS Code extension (VS Code Marketplace | Open VSX) – in‑editor experience for running scans, reviewing traces, and getting AI‑validated security insights without leaving your workspace.
• Custom Rules – write your own security rules using the PathFinder query language to detect project-specific vulnerabilities and patterns.

Supported Languages

• Python – Full support for security analysis and vulnerability detection
• Docker – Dockerfile security scanning
• Docker Compose – Configuration analysis and security checks
• Go – Coming soon

Installation

Homebrew (Recommended)

The easiest way to install on macOS or Linux. Available from version 0.0.34 onwards.

brew install shivasurya/tap/pathfinder

pip

Install via pip to get both the CLI binary and Python DSL for writing security rules.

pip install codepathfinder

Verify installation:

# Test CLI binary
pathfinder --version

# Test Python DSL
python -c "from codepathfinder import rule, calls; print('DSL OK')"

Supported platforms: Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), Windows (x64)

Migrating from npm? The npm package is deprecated. Run npm uninstall -g codepathfinder then pip install codepathfinder.

Docker

Ideal for CI/CD pipelines and containerized workflows.

docker pull shivasurya/code-pathfinder:stable-latest

# Run a scan
docker run --rm -v "./src:/src" \
  shivasurya/code-pathfinder:stable-latest \
  scan --project /src --rules /src/rules

Pre-Built Binaries

Download platform-specific binaries from GitHub Releases. Available for Linux (amd64, arm64), macOS (Intel, Apple Silicon), and Windows (x64).

chmod u+x pathfinder
./pathfinder --help

From Source

Build from source for the latest features. Requires Gradle and Go.

git clone https://github.com/shivasurya/code-pathfinder
cd code-pathfinder/sast-engine
gradle buildGo
./build/go/pathfinder --help

Usage

Scan Command (Interactive)

# Basic scan (text output to console)
pathfinder scan --rules rules/ --project /path/to/project

# With verbose output
pathfinder scan --rules rules/ --project . --verbose

# With debug output
pathfinder scan --rules rules/ --project . --debug

# JSON output to file
pathfinder scan --rules rules/ --project . --output json --output-file results.json

# SARIF output to file (GitHub Code Scanning compatible)
pathfinder scan --rules rules/ --project . --output sarif --output-file results.sarif

# CSV output to file
pathfinder scan --rules rules/ --project . --output csv --output-file results.csv

# JSON output to stdout (for piping)
pathfinder scan --rules rules/ --project . --output json | jq .

# Fail on specific severities
pathfinder scan --rules rules/ --project . --fail-on=critical,high

GitHub Action

Add security scanning to your CI/CD pipeline in just a few lines.

Best Practice: Pin to a specific version (e.g., @v1.2.0) for stability and reproducibility. Using @main will always pull the latest changes, which may introduce breaking changes.

# .github/workflows/security-scan.yml
name: Security Scan

on: [push, pull_request]

permissions:
  security-events: write
  contents: read

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

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

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

Scan Dockerfiles:

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

Use local rules:

      - name: Run Custom Rules
        uses: shivasurya/code-pathfinder@v1.2.0
        with:
          rules: python-sdk/examples/owasp_top10.py

Action Inputs

Note: Either rules or ruleset must be specified.

Available Remote Rulesets

Python:

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

Docker:

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

Acknowledgements

Code Pathfinder uses tree-sitter for all language parsers.

License

Licensed under AGPL-3.0.