Quickstart

Let's say you have a Flask app. User input comes in through a route in app.py, gets passed to a helper function, and ends up in a raw SQL query over in db.py. Classic cross-file taint flow. Most scanners miss it because they only look at one file at a time.

Code Pathfinder v2.0 does not miss it. It tracks data across function calls, across files, across your whole project. Here is how you see it work.

Install the CLI:

brew install shivasurya/tap/pathfinder

Then point it at your project:

pathfinder scan --ruleset python/flask --project .

That is it. Two commands. Code Pathfinder pulls 190+ security rules from the registry, builds a graph of your entire codebase, and traces data flow across every file. Here is what the output looks like when it finds that cross-file SQL injection:

PYTHON-FLASK-SEC-001: SQL Injection via unsanitized user input
Severity: HIGH

  Taint Flow:
    [source] app.py:12  username = request.args.get("username")
         |
         +-> app.py:13  result = fetch_user(username)
         |
         +-> db.py:7    def fetch_user(name):
         |
    [sink] db.py:9      cursor.execute("SELECT * FROM users WHERE name = '" + name + "'")

Look at that trace. The scanner picked up request.args.get() as a source in one file, followed the data through a function call into another file, and flagged the string concatenation in the SQL query as the sink. Cross-file taint analysis, no configuration needed.

If your project is clean, you will see a summary with zero findings and a list of which rulesets were checked. Either way, you know in seconds.

Installation

You already saw the Homebrew command above. Here are all the ways to install Code Pathfinder, depending on what you prefer.

Using Homebrew

Works on macOS and Linux. This is the fastest path.

brew install shivasurya/tap/pathfinder

This taps the repository and installs the latest version. It also installs the codepathfinder Python package so you can write custom rules right away. Update later with brew upgrade pathfinder.

Need a specific version? Pin it:

brew install shivasurya/tap/[email protected]

Using pip

Installs both the CLI and the Python SDK. Requires Python 3.8+.

pip install codepathfinder
pathfinder --help

Using Chocolatey (Windows)

On Windows, Chocolatey is the simplest option.

choco install code-pathfinder

After installation, pathfinder is available from any terminal. Update with choco upgrade code-pathfinder.

Using Docker

Good for CI pipelines where you want a reproducible environment.

docker pull shivasurya/code-pathfinder:stable-latest

Run a scan:

docker run --rm -v "./src:/src" \
  shivasurya/code-pathfinder:stable-latest \
  ci --project /src --ruleset cpf/java

Pre-Built Binaries

Grab a binary for your platform from GitHub Releases. Available for Linux (amd64, arm64), macOS (Intel, Apple Silicon), and Windows (x64).

# Download the latest release for your platform
chmod u+x pathfinder
./pathfinder --help

From Source

If you want unreleased features or plan to contribute. Requires Gradle and Go.

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

Add It to CI

Once you have seen the scan work locally, the natural next step is running it on every pull request. Here is a GitHub Actions workflow that does exactly that:

# .github/workflows/security.yml
name: Security Scan
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Code Pathfinder
        run: pip install codepathfinder
      - name: Run scan
        run: pathfinder scan --ruleset python/flask --project . --format sarif --output results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

The --format sarif flag gives you SARIF output, which GitHub understands natively. Your findings show up as annotations right on the PR diff. The cross-file taint traces come through too, so reviewers can see the full data flow path without leaving the code review.

Write Custom Rules

The built-in rulesets cover a lot, but every codebase has its own patterns. Maybe you have an internal ORM that should never accept raw strings, or a logging function that must not receive PII. You can write a rule for that in Python using the SDK:

from codepathfinder import Rule, MethodMatcher

class NoRawQueryStrings(Rule):
    id = "CUSTOM-001"
    severity = "HIGH"
    message = "Raw string passed to internal ORM query method"

    def match(self):
        return MethodMatcher("db.raw_query").arg(0).is_tainted()

The SDK gives you matchers for method calls, arguments, return values, and full taint tracking. You can publish your custom rules to the registry so your team can pull them down automatically.

Browse the Registry

Code Pathfinder ships with 190+ security rules covering Java, Python, JavaScript, Go, and Dockerfile analysis. The rules cover OWASP Top 10, common CVE patterns, and framework-specific issues for Flask, Django, Spring, and more. You can browse all of them in the rule registry, test them against sample code in the playground, and pull them into your scans with a single flag.

Next Steps