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 スクリプトです。ソース、シンク、サニタイザーを定義すると、データフローエンジンが分析を実行します。

Django の SQL インジェクションを検出する、リポジトリ内の実際のルール（PYTHON-DJANGO-SEC-001）を紹介します。

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

ビルド済みバイナリ

Linux（amd64、arm64）、macOS（Intel、Apple Silicon）、Windows（x64）向けのバイナリをGitHub リリースからダウンロードできます。

ソースからビルド

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）に署名する必要があります。

• バグの報告や機能のリクエスト
• 質問やディスカッションの開始
• セキュリティルールの作成

ライセンス

Apache-2.0