code-pathfinder

Веб-сайт · Документация · Реестр правил · MCP-сервер · Блог

Быстрый старт

Установка:

brew install shivasurya/tap/pathfinder

Сканирование Python-проекта (правила загружаются автоматически):

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

Сканирование Dockerfile:

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

Никаких конфигурационных файлов, ключей API или облачных аккаунтов. Результаты в терминале за секунды.

Related MCP server: CodeAudit Agent

Что такое Code Pathfinder?

Code Pathfinder — это движок статического анализа с открытым исходным кодом, который строит граф вашей кодовой базы и отслеживает потоки данных. Он разбирает исходный код в абстрактные синтаксические деревья, строит графы вызовов между файлами и выполняет анализ распространения меток (taint analysis) для поиска уязвимостей типа «источник-сток», охватывающих несколько файлов и границ функций.

v2.0 представляет межфайловый анализ потоков данных: отслеживание пользовательского ввода от HTTP-обработчика в одном файле через вспомогательные функции до SQL-запроса в другом файле. Это тот вид анализа, который полностью упускают инструменты, основанные на сопоставлении шаблонов.

Межфайловый анализ распространения меток (Taint Analysis)

Большинство open-source 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 строит AST для Python, Dockerfile и Docker Compose файлов

2. Индексация: Извлекает функции, точки вызова, параметры и присваивания в запрашиваемый граф вызовов

3. Анализ: Строит VDG для каждой функции, разрешает межпроцедурные потоки, выполняет анализ распространения меток

4. Обнаружение: Правила безопасности на Python запрашивают граф для поиска путей «источник-сток»

5. Отчёт: Выводит результаты в виде текста, JSON, SARIF (GitHub Code Scanning) или CSV

190 правил безопасности, готовых к использованию

Правила автоматически загружаются с CDN. Нет необходимости клонировать репозиторий или управлять файлами правил.

# 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 .

Просматривайте все правила с примерами и тестовыми случаями в Реестре правил.

MCP-сервер для AI-ассистентов программирования

Code Pathfinder работает как MCP-сервер, предоставляя Claude Code, Cursor, Cline и другим AI-ассистентам доступ к графам вызовов, потокам данных и анализу безопасности. Больше контекста, чем LSP, с фокусом на безопасность и структуру кода.

pathfinder serve --project .

MCP-сервер предоставляет инструменты для запросов к графу кода: поиск вызывающих/вызываемых функций, отслеживание потоков данных, поиск шаблонов и выполнение правил безопасности — всё это доступно AI-ассистенту во время проверки кода или разработки.

Написание собственных правил

Правила безопасности — это Python-скрипты, использующие PathFinder SDK. Определите источники, стоки и санитайзеры — движок анализа потоков данных обработает анализ.

Вот реальное правило из репозитория (PYTHON-DJANGO-SEC-001), которое обнаруживает SQL-инъекции в Django:

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 .

Изучите все 190 правил в каталоге rules/ или просмотрите Реестр правил. Ознакомьтесь с руководством по написанию правил и документацией по потокам данных, чтобы написать свои собственные.

См. руководство по написанию правил и документацию по потокам данных для получения дополнительной информации.

Установка

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/code-pathfinder@v2.1.1
        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

Требуется указать либо rules, либо ruleset.

Поддерживаемые языки

Участие в разработке

Вклад приветствуется. Прочтите Руководство по участию для получения инструкций по настройке, запуску тестов локально и процессу PR.

Публикация объявления внутри продукта

Внутренние объявления (воркшопы, записи в блоге, уведомления о безопасности) управляются через release/latest.json. Добавьте запись в announcements[], откройте PR, и после слияния в main рабочий процесс публикации загружает манифест на CDN в течение ~60 секунд. См. техническую спецификацию проверки обновления версии для схемы и семантики version_range.

Все участники должны подписать Лицензионное соглашение с участником (CLA) до того, как любой pull request может быть принят.

• Сообщить об ошибках или запросить функции

• Задать вопросы или начать обсуждение

• Написать правила безопасности

Лицензия

Apache-2.0