{
  "markdown": "<div align=\"center\">\n  <img src=\"./assets/banner.png\" alt=\"Code Pathfinder - Open-source SAST with cross-file dataflow analysis\" width=\"100%\">\n</div>\n\n<div align=\"center\">\n\n<h3>Open-source SAST engine that traces vulnerabilities across files and functions</h3>\n\n[Website](https://codepathfinder.dev/) · [Docs](https://codepathfinder.dev/docs/quickstart) · [Rule Registry](https://codepathfinder.dev/registry) · [MCP Server](https://codepathfinder.dev/mcp) · [Blog](https://codepathfinder.dev/blog)\n\n[![Build](https://github.com/shivasurya/code-pathfinder/actions/workflows/build.yml/badge.svg)](https://github.com/shivasurya/code-pathfinder/actions/workflows/build.yml)\n[![GitHub Release](https://img.shields.io/github/v/release/shivasurya/code-pathfinder?label=release)](https://github.com/shivasurya/code-pathfinder/releases)\n[![Apache-2.0 License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/shivasurya/code-pathfinder/blob/main/LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/shivasurya/code-pathfinder?style=flat)](https://github.com/shivasurya/code-pathfinder/stargazers)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/shivasurya/code-pathfinder)\n\n</div>\n\n---\n\n## Quick Start\n\n**Install:**\n\n```bash\nbrew install shivasurya/tap/pathfinder\n```\n\n**Scan a Python project** (rules download automatically):\n\n```bash\npathfinder scan --ruleset python/all --project .\n```\n\n**Scan Dockerfiles:**\n\n```bash\npathfinder scan --ruleset docker/all --project .\n```\n\nNo config files, no API keys, no cloud accounts. Results in your terminal in seconds.\n\n---\n\n<!-- TODO: Add demo video/GIF here -->\n\n## What is Code Pathfinder?\n\nCode Pathfinder is an open-source static analysis engine that builds a graph of your codebase and traces how data flows through it. It parses source code into Abstract Syntax Trees, constructs call graphs across files, and runs taint analysis to find source-to-sink vulnerabilities that span multiple files and function boundaries.\n\n**v2.0** introduces **cross-file dataflow analysis**: trace user input from an HTTP handler in one file through helper functions and into a SQL query in another file. This is the kind of analysis that pattern-matching tools miss entirely.\n\n### Cross-File Taint Analysis\n\nMost open-source SAST tools operate on single files. Code Pathfinder v2.0 tracks tainted data across file boundaries:\n\n```\napp.py:5    user_input = request.get(\"query\")     ← Source: user-controlled input\n  ↓ calls\ndb.py:12    cursor.execute(query)                  ← Sink: SQL execution\n```\n\nThe engine builds a Variable Dependency Graph (VDG) per function, then connects them through inter-procedural taint transfer summaries. When `user_input` flows into a function parameter in another file, the taint propagates through the call graph to the sink.\n\n### How It Works\n\n```\nSource Code → Tree-sitter AST → Call Graph → Variable Dependency Graph → Taint Analysis → Findings\n                                     ↓\n                              Inter-procedural\n                              Taint Summaries\n                              (cross-file flows)\n```\n\n1. **Parse**: Tree-sitter builds ASTs for Python, Dockerfiles, and Docker Compose files\n2. **Index**: Extract functions, call sites, parameters, and assignments into a queryable call graph\n3. **Analyze**: Build VDGs per function, resolve inter-procedural flows, run taint analysis\n4. **Detect**: Python-based security rules query the graph to find source-to-sink paths\n5. **Report**: Output findings as text, JSON, SARIF (GitHub Code Scanning), or CSV\n\n## 190 Security Rules, Ready to Use\n\nRules download from CDN automatically. No need to clone the repo or manage rule files.\n\n| Language | Bundles | Rules | Coverage |\n|----------|---------|-------|----------|\n| **[Python](https://codepathfinder.dev/registry/python)** | django, flask, aws_lambda, cryptography, jwt, lang, deserialization, pyramid | 158 | SQL injection, RCE, SSRF, path traversal, XSS, deserialization, crypto misuse, JWT vulnerabilities |\n| **[Docker](https://codepathfinder.dev/registry/docker)** | security, best-practice, performance | 37 | Root user, exposed secrets, image pinning, multi-stage builds, layer optimization |\n| **[Docker Compose](https://codepathfinder.dev/registry/docker-compose)** | security, networking | 10 | Privileged mode, socket exposure, capability escalation, network isolation |\n\n```bash\n# Scan with a specific bundle\npathfinder scan --ruleset python/django --project .\n\n# Scan with multiple bundles\npathfinder scan --ruleset python/flask --ruleset python/jwt --project .\n\n# Scan a single rule\npathfinder scan --ruleset python/PYTHON-DJANGO-SEC-001 --project .\n\n# Scan all rules for a language\npathfinder scan --ruleset python/all --project .\n```\n\nBrowse all rules with examples and test cases at the [Rule Registry](https://codepathfinder.dev/registry).\n\n## MCP Server for AI Coding Assistants\n\nCode Pathfinder runs as an [MCP server](https://codepathfinder.dev/mcp), giving Claude Code, Cursor, Cline, and other AI assistants access to call graphs, data flows, and security analysis. More context than LSP, focused on security and code structure.\n\n```bash\npathfinder serve --project .\n```\n\nThe MCP server exposes tools for querying the code graph: find callers/callees, trace data flows, search for patterns, and run security rules — all available to the AI assistant during code review or development.\n\n## Write Custom Rules\n\nSecurity rules are Python scripts using the [PathFinder SDK](https://codepathfinder.dev/docs/rules). Define sources, sinks, and sanitizers — the dataflow engine handles the analysis.\n\nHere's a real rule from the repo ([`PYTHON-DJANGO-SEC-001`](./rules/python/django/PYTHON-DJANGO-SEC-001/rule.py)) that detects SQL injection in Django:\n\n```python\nfrom codepathfinder import calls, flows, QueryType\nfrom codepathfinder.presets import PropagationPresets\n\nclass DBCursor(QueryType):\n    fqns = [\"sqlite3.Cursor\", \"psycopg2.extensions.cursor\"]\n    match_subclasses = True\n\n@python_rule(\n    id=\"PYTHON-DJANGO-SEC-001\",\n    name=\"Django SQL Injection via cursor.execute()\",\n    severity=\"CRITICAL\",\n    cwe=\"CWE-89\",\n)\ndef detect_django_cursor_sqli():\n    return flows(\n        from_sources=[\n            calls(\"request.GET.get\"),\n            calls(\"request.POST.get\"),\n        ],\n        to_sinks=[\n            DBCursor.method(\"execute\").tracks(0),\n            calls(\"cursor.execute\"),\n        ],\n        sanitized_by=[calls(\"escape\"), calls(\"escape_string\")],\n        propagates_through=PropagationPresets.standard(),\n        scope=\"global\",  # cross-file taint analysis\n    )\n```\n\n```bash\n# Run your custom rules\npathfinder scan --rules ./my_rules/ --project .\n```\n\nExplore all 190 rules in the [`rules/`](./rules) directory or browse the [Rule Registry](https://codepathfinder.dev/registry). See the [rule writing guide](https://codepathfinder.dev/docs/rules) and [dataflow documentation](https://codepathfinder.dev/docs/dataflow) to write your own.\n\nSee the [rule writing guide](https://codepathfinder.dev/docs/rules) and [dataflow documentation](https://codepathfinder.dev/docs/dataflow) for more.\n\n## Installation\n\n### Homebrew (Recommended)\n\n```bash\nbrew install shivasurya/tap/pathfinder\n```\n\n### pip\n\nInstalls the CLI binary and Python SDK for writing rules.\n\n```bash\npip install codepathfinder\n```\n\n### Docker\n\n```bash\ndocker pull shivasurya/code-pathfinder:stable-latest\n\ndocker run --rm -v \"$(pwd):/src\" \\\n  shivasurya/code-pathfinder:stable-latest \\\n  scan --ruleset python/all --project /src\n```\n\n### Pre-Built Binaries\n\nDownload from [GitHub Releases](https://github.com/shivasurya/code-pathfinder/releases) for Linux (amd64, arm64), macOS (Intel, Apple Silicon), and Windows (x64).\n\n### From Source\n\n```bash\ngit clone https://github.com/shivasurya/code-pathfinder\ncd code-pathfinder/sast-engine\ngradle buildGo\n./build/go/pathfinder --help\n```\n\n## Usage\n\n```bash\n# Scan with text output (default)\npathfinder scan --ruleset python/all --project .\n\n# JSON output\npathfinder scan --ruleset python/all --project . --output json --output-file results.json\n\n# SARIF output (GitHub Code Scanning)\npathfinder scan --ruleset python/all --project . --output sarif --output-file results.sarif\n\n# CSV output\npathfinder scan --ruleset python/all --project . --output csv --output-file results.csv\n\n# Fail CI on critical/high findings\npathfinder scan --ruleset python/all --project . --fail-on=critical,high\n\n# MCP server mode\npathfinder serve --project .\n\n# Verbose output with statistics\npathfinder scan --ruleset python/all --project . --verbose\n```\n\n## GitHub Action\n\n```yaml\nname: Code Pathfinder Security SAST Scan\n\non:\n  pull_request:\n\npermissions:\n  security-events: write\n  contents: read\n  pull-requests: write\n\njobs:\n  security-scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n        with:\n          fetch-depth: 0\n\n      - name: Run Security Scan\n        uses: shivasurya/code-pathfinder@v2.1.1\n        with:\n          ruleset: python/all, docker/all, docker-compose/all\n          verbose: true\n          pr-comment: ${{ github.event_name == 'pull_request' }}\n          pr-inline: ${{ github.event_name == 'pull_request' }}\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n\n      - name: Upload SARIF\n        uses: github/codeql-action/upload-sarif@v4\n        if: always()\n        with:\n          sarif_file: pathfinder-results.sarif\n```\n\nSee the full example: [`.github/workflows/code-pathfinder-scan.yml`](.github/workflows/code-pathfinder-scan.yml)\n\n<details>\n<summary><strong>Action Inputs</strong></summary>\n\n| Input | Description | Default |\n|-------|-------------|---------|\n| `rules` | Path to local Python rule files or directory | - |\n| `ruleset` | Remote ruleset(s), comma-separated (e.g., `python/all`, `docker/security`) | - |\n| `project` | Path to source code | `.` |\n| `output` | Output format: `sarif`, `json`, or `csv` | `sarif` |\n| `output-file` | Output file path | `pathfinder-results.sarif` |\n| `fail-on` | Fail on severities (e.g., `critical,high`) | - |\n| `verbose` | Enable verbose output | `false` |\n| `debug` | Enable debug diagnostics with timestamps | `false` |\n| `skip-tests` | Skip test files | `true` |\n| `refresh-rules` | Force refresh cached rulesets | `false` |\n| `disable-metrics` | Disable anonymous usage metrics | `false` |\n| `python-version` | Python version to use | `3.12` |\n| `pr-comment` | Post summary comment on pull request | `false` |\n| `pr-inline` | Post inline review comments for critical/high findings | `false` |\n| `github-token` | GitHub token (required when `pr-comment` or `pr-inline` is enabled) | - |\n| `no-diff` | Disable diff-aware scanning (scan all files) | `false` |\n\nEither `rules` or `ruleset` is required.\n\n</details>\n\n## Supported Languages\n\n| Language | Analysis | Status |\n|----------|----------|--------|\n| **Python** | Cross-file dataflow, taint analysis, call graphs | Stable |\n| **Dockerfile** | Instruction analysis, security patterns | Stable |\n| **Docker Compose** | Configuration analysis, security patterns | Stable |\n| **Go** | AST analysis, call graphs | Coming soon |\n\n## Contributing\n\nContributions are welcome. Read the [Contributing Guide](./CONTRIBUTING.md) for setup instructions, how to run tests locally, and the PR process.\n\n### Pushing an in-product announcement\n\nIn-product announcements (workshops, blog posts, security advisories) are\nmanaged via `release/latest.json`. Add an entry to `announcements[]`,\nopen a PR, and once it merges to `main` the publish workflow uploads the\nmanifest to the CDN within ~60 seconds. See the version-update-check tech\nspec for the schema and `version_range` semantics.\n\nAll contributors must sign the [Contributor License Agreement (CLA)](./CLA.md) before any pull request can be merged.\n\n- [Report bugs or request features](https://github.com/shivasurya/code-pathfinder/issues)\n- [Ask questions or start a discussion](https://github.com/shivasurya/code-pathfinder/discussions)\n- [Write security rules](https://codepathfinder.dev/docs/rules)\n\n## License\n\n[Apache-2.0](https://github.com/shivasurya/code-pathfinder/blob/main/LICENSE)\n",
  "bytes": 12181,
  "sha": "f4696fb724c7f53a67a775e8d5e662ec0fdc6f9bb05e7e422f7704f32a85097f",
  "repo_slug": "shivasurya/code-pathfinder",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_codepathfinder_pathfinder_ed614324/readme"
}