Code Pathfinder

---

快速开始

安装：

brew install shivasurya/tap/pathfinder

扫描 Python 项目（规则会自动下载）：

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

扫描 Dockerfile：

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

无需配置文件、API 密钥或云账户。几秒钟内即可在终端查看结果。

---

什么是 Code Pathfinder？

Code Pathfinder 是一款开源静态分析引擎，它会为代码库构建图，并追踪数据在其中的流动方式。它会将源代码解析为抽象语法树，构建跨文件调用图，并运行污点分析，以发现跨越多个文件和函数边界的源到汇漏洞。

v2.0 引入了跨文件数据流分析：追踪用户输入从一个文件中的 HTTP 处理程序，经由辅助函数，最终进入另一个文件中的 SQL 查询。这类分析正是模式匹配工具完全无法做到的。

跨文件污点分析

大多数开源 SAST 工具只分析单个文件。Code Pathfinder v2.0 可跨文件边界追踪受污染的数据：

app.py:5    user_input = request.get("query")     ← Source: user-controlled input
  ↓ calls
db.py:12    cursor.execute(query)                  ← Sink: SQL execution

引擎会为每个函数构建变量依赖图（VDG），然后通过过程间污点传递摘要将各图连接起来。当 user_input 流入另一个文件中的函数参数时，污点会沿调用图传播至汇点。

工作原理

Source Code → Tree-sitter AST → Call Graph → Variable Dependency Graph → Taint Analysis → Findings
                                     ↓
                              Inter-procedural
                              Taint Summaries
                              (cross-file flows)

1. 解析：Tree-sitter 为 Python、Dockerfile 和 Docker Compose 文件构建 AST
2. 索引：提取函数、调用点、参数和赋值，并构建可查询的调用图
3. 分析：为每个函数构建 VDG，解析过程间数据流，并运行污点分析
4. 检测：基于 Python 的安全规则查询图，以查找源到汇路径
5. 报告：以文本、JSON、SARIF（GitHub Code Scanning）或 CSV 格式输出发现结果

190 条开箱即用的安全规则

规则会自动从 CDN 下载。无需克隆仓库或管理规则文件。

语言	规则包	规则数	覆盖范围
Python	django, flask, aws_lambda, cryptography, jwt, lang, deserialization, pyramid	158	SQL 注入、RCE、SSRF、路径遍历、XSS、反序列化、加密误用、JWT 漏洞
Docker	security, best-practice, performance	37	root 用户、暴露的密钥、镜像固定、多阶段构建、层优化
Docker Compose	security, networking	10	特权模式、套接字暴露、权限提升、网络隔离

# Scan with a specific bundle
pathfinder scan --ruleset python/django --project .

# Scan with multiple bundles
pathfinder scan --ruleset python/flask --ruleset python/jwt --project .

# Scan a single rule
pathfinder scan --ruleset python/PYTHON-DJANGO-SEC-001 --project .

# Scan all rules for a language
pathfinder scan --ruleset python/all --project .

在规则注册表中浏览所有规则、示例和测试用例。

面向 AI 编码助手的 MCP 服务

Code Pathfinder 以 MCP 服务的形式运行，让 Claude Code、Cursor、Cline 和其他 AI 助手能够访问调用图、数据流和安全分析。比 LSP 提供更多上下文，专注于安全性和代码结构。

pathfinder serve --project .

MCP 服务提供用于查询代码图的工具：查找调用方／被调用方、追踪数据流、搜索模式以及运行安全规则——这些工具都可供 AI 助手在代码审查或开发过程中使用。

编写自定义规则

安全规则是使用 PathFinder SDK 编写的 Python 脚本。定义来源、汇点和净化器——数据流引擎会负责分析。

以下是仓库中的一条实际规则（PYTHON-DJANGO-SEC-001），用于检测 Django 中的 SQL 注入：

from codepathfinder import calls, flows, QueryType
from codepathfinder.presets import PropagationPresets

class DBCursor(QueryType):
    fqns = ["sqlite3.Cursor", "psycopg2.extensions.cursor"]
    match_subclasses = True

@python_rule(
    id="PYTHON-DJANGO-SEC-001",
    name="Django SQL Injection via cursor.execute()",
    severity="CRITICAL",
    cwe="CWE-89",
)
def detect_django_cursor_sqli():
    return flows(
        from_sources=[
            calls("request.GET.get"),
            calls("request.POST.get"),
        ],
        to_sinks=[
            DBCursor.method("execute").tracks(0),
            calls("cursor.execute"),
        ],
        sanitized_by=[calls("escape"), calls("escape_string")],
        propagates_through=PropagationPresets.standard(),
        scope="global",  # cross-file taint analysis
    )

# Run your custom rules
pathfinder scan --rules ./my_rules/ --project .

在 rules/ 目录中探索全部 190 条规则，或浏览规则注册表。请参阅规则编写指南和数据流文档，编写自己的规则。

如需了解更多信息，请参阅规则编写指南和数据流文档。

安装

Homebrew（推荐）

brew install shivasurya/tap/pathfinder

pip

安装 CLI 二进制文件和用于编写规则的 Python SDK。

pip install codepathfinder

Docker

docker pull shivasurya/code-pathfinder:stable-latest

docker run --rm -v "$(pwd):/src" \
  shivasurya/code-pathfinder:stable-latest \
  scan --ruleset python/all --project /src

预编译二进制文件

从 GitHub Releases 下载适用于 Linux（amd64、arm64）、macOS（Intel、Apple Silicon）和 Windows（x64）的版本。

从源代码安装

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

使用方法

# Scan with text output (default)
pathfinder scan --ruleset python/all --project .

# JSON output
pathfinder scan --ruleset python/all --project . --output json --output-file results.json

# SARIF output (GitHub Code Scanning)
pathfinder scan --ruleset python/all --project . --output sarif --output-file results.sarif

# CSV output
pathfinder scan --ruleset python/all --project . --output csv --output-file results.csv

# Fail CI on critical/high findings
pathfinder scan --ruleset python/all --project . --fail-on=critical,high

# MCP server mode
pathfinder serve --project .

# Verbose output with statistics
pathfinder scan --ruleset python/all --project . --verbose

GitHub Action

name: Code Pathfinder Security SAST Scan

on:
  pull_request:

permissions:
  security-events: write
  contents: read
  pull-requests: write

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Run Security Scan
        uses: shivasurya/[email protected]
        with:
          ruleset: python/all, docker/all, docker-compose/all
          verbose: true
          pr-comment: ${{ github.event_name == 'pull_request' }}
          pr-inline: ${{ github.event_name == 'pull_request' }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

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

请参阅完整示例：.github/workflows/code-pathfinder-scan.yml

Action 输入项

输入项	描述	默认值
rules	本地 Python 规则文件或目录的路径	-
ruleset	远程规则集，多个规则集以逗号分隔（例如，python/all、docker/security）	-
project	源代码路径	.
output	输出格式：sarif、json 或 csv	sarif
output-file	输出文件路径	pathfinder-results.sarif
fail-on	触发失败的严重级别（例如，critical,high）	-
verbose	启用详细输出	false
debug	启用带时间戳的调试诊断信息	false
skip-tests	跳过测试文件	true
refresh-rules	强制刷新缓存的规则集	false
disable-metrics	禁用匿名使用情况指标	false
python-version	要使用的 Python 版本	3.12
pr-comment	在拉取请求中发布摘要评论	false
pr-inline	对严重／高严重级别发现发布行内审查评论	false
github-token	GitHub 令牌（启用 pr-comment 或 pr-inline 时必需）	-
no-diff	禁用差异感知扫描（扫描所有文件）	false

必须提供 rules 或 ruleset。

支持的语言

语言	分析	状态
Python	跨文件数据流、污点分析、调用图	稳定
Dockerfile	指令分析、安全模式	稳定
Docker Compose	配置分析、安全模式	稳定
Go	AST 分析、调用图	即将推出

参与贡献

欢迎贡献。请阅读贡献指南，了解环境设置说明、如何在本地运行测试以及 PR 流程。

推送产品内公告

产品内公告（研讨会、博客文章、安全公告）通过 release/latest.json 管理。向 announcements[] 添加一条条目，创建 PR；合并到 main 后，发布工作流会在约 60 秒内将 清单上传到 CDN。有关架构和 version_range 语义，请参阅 version-update-check 技术 规范。

所有贡献者都必须先签署贡献者许可协议（CLA），PR 才能合并。

• 报告 Bug 或请求新功能
• 提问或发起讨论
• 编写安全规则

许可证

Apache-2.0