Skip to content
Back to search

code-pathfinder

Static Code Analysis for security teams with Inter file taint analysis. Built for finding vulnerabilities, advanced structural search, derive insights and supports MCP

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shivasurya--code-pathfinder/badge.svg)](/listings/shivasurya--code-pathfinder)

HTML

<a href="/listings/shivasurya--code-pathfinder"><img src="/api/listings/shivasurya--code-pathfinder/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Install:**

brew install shivasurya/tap/pathfinder

**Scan a Python project** (rules download automatically):

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

**Scan Dockerfiles:**

pathfinder scan --ruleset docker/all --project .

No config files, no API keys, no cloud accounts. Results in your terminal in seconds.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 320 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="./assets/banner.png" alt="Code Pathfinder - Open-source SAST with cross-file dataflow analysis" width="100%">
  3. </div>
  4. <div align="center">
  5. <h3>Open-source SAST engine that traces vulnerabilities across files and functions</h3>
  6. [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)
  7. [![Build](https://github.com/shivasurya/code-pathfinder/actions/workflows/build.yml/badge.svg)](https://github.com/shivasurya/code-pathfinder/actions/workflows/build.yml)
  8. [![GitHub Release](https://img.shields.io/github/v/release/shivasurya/code-pathfinder?label=release)](https://github.com/shivasurya/code-pathfinder/releases)
  9. [![Apache-2.0 License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/shivasurya/code-pathfinder/blob/main/LICENSE)
  10. [![GitHub Stars](https://img.shields.io/github/stars/shivasurya/code-pathfinder?style=flat)](https://github.com/shivasurya/code-pathfinder/stargazers)
  11. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/shivasurya/code-pathfinder)
  12. </div>
  13. ---
  14. ## Quick Start
  15. **Install:**
  16. ```bash
  17. brew install shivasurya/tap/pathfinder
  18. ```
  19. **Scan a Python project** (rules download automatically):
  20. ```bash
  21. pathfinder scan --ruleset python/all --project .
  22. ```
  23. **Scan Dockerfiles:**
  24. ```bash
  25. pathfinder scan --ruleset docker/all --project .
  26. ```
  27. No config files, no API keys, no cloud accounts. Results in your terminal in seconds.
  28. ---
  29. <!-- TODO: Add demo video/GIF here -->
  30. ## What is Code Pathfinder?
  31. Code 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.
  32. **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.
  33. ### Cross-File Taint Analysis
  34. Most open-source SAST tools operate on single files. Code Pathfinder v2.0 tracks tainted data across file boundaries:
  35. ```
  36. app.py:5 user_input = request.get("query") ← Source: user-controlled input
  37. ↓ calls
  38. db.py:12 cursor.execute(query) ← Sink: SQL execution
  39. ```
  40. The 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.
  41. ### How It Works
  42. ```
  43. Source Code → Tree-sitter AST → Call Graph → Variable Dependency Graph → Taint Analysis → Findings
  44. ↓
  45. Inter-procedural
  46. Taint Summaries
  47. (cross-file flows)
  48. ```
  49. 1. **Parse**: Tree-sitter builds ASTs for Python, Dockerfiles, and Docker Compose files
  50. 2. **Index**: Extract functions, call sites, parameters, and assignments into a queryable call graph
  51. 3. **Analyze**: Build VDGs per function, resolve inter-procedural flows, run taint analysis
  52. 4. **Detect**: Python-based security rules query the graph to find source-to-sink paths
  53. 5. **Report**: Output findings as text, JSON, SARIF (GitHub Code Scanning), or CSV
  54. ## 190 Security Rules, Ready to Use
  55. Rules download from CDN automatically. No need to clone the repo or manage rule files.
  56. | Language | Bundles | Rules | Coverage |
  57. |----------|---------|-------|----------|
  58. | **[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 |
  59. | **[Docker](https://codepathfinder.dev/registry/docker)** | security, best-practice, performance | 37 | Root user, exposed secrets, image pinning, multi-stage builds, layer optimization |
  60. | **[Docker Compose](https://codepathfinder.dev/registry/docker-compose)** | security, networking | 10 | Privileged mode, socket exposure, capability escalation, network isolation |
  61. ```bash
  62. # Scan with a specific bundle
  63. pathfinder scan --ruleset python/django --project .
  64. # Scan with multiple bundles
  65. pathfinder scan --ruleset python/flask --ruleset python/jwt --project .
  66. # Scan a single rule
  67. pathfinder scan --ruleset python/PYTHON-DJANGO-SEC-001 --project .
  68. # Scan all rules for a language
  69. pathfinder scan --ruleset python/all --project .
  70. ```
  71. Browse all rules with examples and test cases at the [Rule Registry](https://codepathfinder.dev/registry).
  72. ## MCP Server for AI Coding Assistants
  73. Code 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.
  74. ```bash
  75. pathfinder serve --project .
  76. ```
  77. The 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.
  78. ## Write Custom Rules
  79. Security rules are Python scripts using the [PathFinder SDK](https://codepathfinder.dev/docs/rules). Define sources, sinks, and sanitizers — the dataflow engine handles the analysis.
  80. Here'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:
  81. ```python
  82. from codepathfinder import calls, flows, QueryType
  83. from codepathfinder.presets import PropagationPresets
  84. class DBCursor(QueryType):
  85. fqns = ["sqlite3.Cursor", "psycopg2.extensions.cursor"]
  86. match_subclasses = True
  87. @python_rule(
  88. id="PYTHON-DJANGO-SEC-001",
  89. name="Django SQL Injection via cursor.execute()",
  90. severity="CRITICAL",
  91. cwe="CWE-89",
  92. )
  93. def detect_django_cursor_sqli():
  94. return flows(
  95. from_sources=[
  96. calls("request.GET.get"),
  97. calls("request.POST.get"),
  98. ],
  99. to_sinks=[
  100. DBCursor.method("execute").tracks(0),
  101. calls("cursor.execute"),
  102. ],
  103. sanitized_by=[calls("escape"), calls("escape_string")],
  104. propagates_through=PropagationPresets.standard(),
  105. scope="global", # cross-file taint analysis
  106. )
  107. ```
  108. ```bash
  109. # Run your custom rules
  110. pathfinder scan --rules ./my_rules/ --project .
  111. ```
  112. Explore 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.
  113. See the [rule writing guide](https://codepathfinder.dev/docs/rules) and [dataflow documentation](https://codepathfinder.dev/docs/dataflow) for more.
  114. ## Installation
  115. ### Homebrew (Recommended)
  116. ```bash
  117. brew install shivasurya/tap/pathfinder
  118. ```
  119. ### pip
  120. Installs the CLI binary and Python SDK for writing rules.
  121. ```bash
  122. pip install codepathfinder
  123. ```
  124. ### Docker
  125. ```bash
  126. docker pull shivasurya/code-pathfinder:stable-latest
  127. docker run --rm -v "$(pwd):/src" \
  128. shivasurya/code-pathfinder:stable-latest \
  129. scan --ruleset python/all --project /src
  130. ```
  131. ### Pre-Built Binaries
  132. Download from [GitHub Releases](https://github.com/shivasurya/code-pathfinder/releases) for Linux (amd64, arm64), macOS (Intel, Apple Silicon), and Windows (x64).
  133. ### From Source
  134. ```bash
  135. git clone https://github.com/shivasurya/code-pathfinder
  136. cd code-pathfinder/sast-engine
  137. gradle buildGo
  138. ./build/go/pathfinder --help
  139. ```
  140. ## Usage
  141. ```bash
  142. # Scan with text output (default)
  143. pathfinder scan --ruleset python/all --project .
  144. # JSON output
  145. pathfinder scan --ruleset python/all --project . --output json --output-file results.json
  146. # SARIF output (GitHub Code Scanning)
  147. pathfinder scan --ruleset python/all --project . --output sarif --output-file results.sarif
  148. # CSV output
  149. pathfinder scan --ruleset python/all --project . --output csv --output-file results.csv
  150. # Fail CI on critical/high findings
  151. pathfinder scan --ruleset python/all --project . --fail-on=critical,high
  152. # MCP server mode
  153. pathfinder serve --project .
  154. # Verbose output with statistics
  155. pathfinder scan --ruleset python/all --project . --verbose
  156. ```
  157. ## GitHub Action
  158. ```yaml
  159. name: Code Pathfinder Security SAST Scan
  160. on:
  161. pull_request:
  162. permissions:
  163. security-events: write
  164. contents: read
  165. pull-requests: write
  166. jobs:
  167. security-scan:
  168. runs-on: ubuntu-latest
  169. steps:
  170. - uses: actions/checkout@v6
  171. with:
  172. fetch-depth: 0
  173. - name: Run Security Scan
  174. uses: shivasurya/code-pathfinder@v2.1.1
  175. with:
  176. ruleset: python/all, docker/all, docker-compose/all
  177. verbose: true
  178. pr-comment: ${{ github.event_name == 'pull_request' }}
  179. pr-inline: ${{ github.event_name == 'pull_request' }}
  180. github-token: ${{ secrets.GITHUB_TOKEN }}
  181. - name: Upload SARIF
  182. uses: github/codeql-action/upload-sarif@v4
  183. if: always()
  184. with:
  185. sarif_file: pathfinder-results.sarif
  186. ```
  187. See the full example: [`.github/workflows/code-pathfinder-scan.yml`](.github/workflows/code-pathfinder-scan.yml)
  188. <details>
  189. <summary><strong>Action Inputs</strong></summary>
  190. | Input | Description | Default |
  191. |-------|-------------|---------|
  192. | `rules` | Path to local Python rule files or directory | - |
  193. | `ruleset` | Remote ruleset(s), comma-separated (e.g., `python/all`, `docker/security`) | - |
  194. | `project` | Path to source code | `.` |
  195. | `output` | Output format: `sarif`, `json`, or `csv` | `sarif` |
  196. | `output-file` | Output file path | `pathfinder-results.sarif` |
  197. | `fail-on` | Fail on severities (e.g., `critical,high`) | - |
  198. | `verbose` | Enable verbose output | `false` |
  199. | `debug` | Enable debug diagnostics with timestamps | `false` |
  200. | `skip-tests` | Skip test files | `true` |
  201. | `refresh-rules` | Force refresh cached rulesets | `false` |
  202. | `disable-metrics` | Disable anonymous usage metrics | `false` |
  203. | `python-version` | Python version to use | `3.12` |
  204. | `pr-comment` | Post summary comment on pull request | `false` |
  205. | `pr-inline` | Post inline review comments for critical/high findings | `false` |
  206. | `github-token` | GitHub token (required when `pr-comment` or `pr-inline` is enabled) | - |
  207. | `no-diff` | Disable diff-aware scanning (scan all files) | `false` |
  208. Either `rules` or `ruleset` is required.
  209. </details>
  210. ## Supported Languages
  211. | Language | Analysis | Status |
  212. |----------|----------|--------|
  213. | **Python** | Cross-file dataflow, taint analysis, call graphs | Stable |
  214. | **Dockerfile** | Instruction analysis, security patterns | Stable |
  215. | **Docker Compose** | Configuration analysis, security patterns | Stable |
  216. | **Go** | AST analysis, call graphs | Coming soon |
  217. ## Contributing
  218. Contributions are welcome. Read the [Contributing Guide](./CONTRIBUTING.md) for setup instructions, how to run tests locally, and the PR process.
  219. ### Pushing an in-product announcement
  220. In-product announcements (workshops, blog posts, security advisories) are
  221. managed via `release/latest.json`. Add an entry to `announcements[]`,
  222. open a PR, and once it merges to `main` the publish workflow uploads the
  223. manifest to the CDN within ~60 seconds. See the version-update-check tech
  224. spec for the schema and `version_range` semantics.
  225. All contributors must sign the [Contributor License Agreement (CLA)](./CLA.md) before any pull request can be merged.
  226. - [Report bugs or request features](https://github.com/shivasurya/code-pathfinder/issues)
  227. - [Ask questions or start a discussion](https://github.com/shivasurya/code-pathfinder/discussions)
  228. - [Write security rules](https://codepathfinder.dev/docs/rules)
  229. ## License
  230. [Apache-2.0](https://github.com/shivasurya/code-pathfinder/blob/main/LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.