code-pathfinder

Sitio web · Documentación · Registro de reglas · Servidor MCP · Blog

Inicio rápido

Instalación:

brew install shivasurya/tap/pathfinder

Escanea un proyecto Python (las reglas se descargan automáticamente):

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

Escanea Dockerfiles:

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

Sin archivos de configuración, sin claves API, sin cuentas en la nube. Resultados en tu terminal en segundos.

Related MCP server: CodeAudit Agent

¿Qué es Code Pathfinder?

Code Pathfinder es un motor de análisis estático de código abierto que construye un grafo de tu base de código y rastrea cómo fluyen los datos a través de él. Analiza el código fuente en Árboles de Sintaxis Abstracta, construye grafos de llamadas entre archivos y ejecuta análisis de contaminación para encontrar vulnerabilidades de origen a sumidero que abarcan múltiples archivos y límites de funciones.

v2.0 introduce análisis de flujo de datos entre archivos: rastrea la entrada del usuario desde un manejador HTTP en un archivo a través de funciones auxiliares hasta una consulta SQL en otro archivo. Este es el tipo de análisis que las herramientas de coincidencia de patrones pasan por alto por completo.

Análisis de Contaminación entre Archivos

La mayoría de las herramientas SAST de código abierto operan en archivos individuales. Code Pathfinder v2.0 rastrea datos contaminados a través de los límites de los archivos:

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

El motor construye un Grafo de Dependencia de Variables (VDG) por función, luego los conecta mediante resúmenes de transferencia de contaminación interprocedimental. Cuando user_input fluye hacia un parámetro de función en otro archivo, la contaminación se propaga a través del grafo de llamadas hasta el sumidero.

Cómo funciona

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

1. Analizar: Tree-sitter construye ASTs para Python, Dockerfiles y archivos Docker Compose

2. Indexar: Extrae funciones, sitios de llamada, parámetros y asignaciones en un grafo de llamadas consultable

3. Analizar: Construye VDGs por función, resuelve flujos interprocedimentales, ejecuta análisis de contaminación

4. Detectar: Las reglas de seguridad basadas en Python consultan el grafo para encontrar rutas de origen a sumidero

5. Informar: Muestra los hallazgos como texto, JSON, SARIF (Escaneo de Código de GitHub) o CSV

190 Reglas de Seguridad, Listas para Usar

Las reglas se descargan desde CDN automáticamente. No es necesario clonar el repositorio ni gestionar archivos de reglas.

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

Explora todas las reglas con ejemplos y casos de prueba en el Registro de reglas.

Servidor MCP para Asistentes de Codificación con IA

Code Pathfinder funciona como un servidor MCP, proporcionando a Claude Code, Cursor, Cline y otros asistentes de IA acceso a grafos de llamadas, flujos de datos y análisis de seguridad. Más contexto que LSP, centrado en seguridad y estructura del código.

pathfinder serve --project .

El servidor MCP expone herramientas para consultar el grafo de código: encontrar llamantes/llamados, rastrear flujos de datos, buscar patrones y ejecutar reglas de seguridad, todo disponible para el asistente de IA durante la revisión o el desarrollo de código.

Escribir Reglas Personalizadas

Las reglas de seguridad son scripts de Python que utilizan el SDK de PathFinder. Define fuentes, sumideros y sanitizadores; el motor de flujo de datos maneja el análisis.

Aquí hay una regla real del repositorio (PYTHON-DJANGO-SEC-001) que detecta inyección SQL en 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 .

Explora las 190 reglas en el directorio rules/ o navega por el Registro de reglas. Consulta la guía de escritura de reglas y la documentación de flujo de datos para escribir las tuyas propias.

Consulta la guía de escritura de reglas y la documentación de flujo de datos para más información.

Instalación

Homebrew (Recomendado)

brew install shivasurya/tap/pathfinder

pip

Instala el binario CLI y el SDK de Python para escribir reglas.

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

Binarios Precompilados

Descarga desde GitHub Releases para Linux (amd64, arm64), macOS (Intel, Apple Silicon) y Windows (x64).

Desde el Código Fuente

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

Uso

# 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

Acción de GitHub

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

Consulta el ejemplo completo: .github/workflows/code-pathfinder-scan.yml

Se requiere rules o ruleset.

Lenguajes Soportados

Contribuir

Las contribuciones son bienvenidas. Lee la Guía de Contribución para instrucciones de configuración, cómo ejecutar pruebas localmente y el proceso de PR.

Publicar un anuncio dentro del producto

Los anuncios dentro del producto (talleres, publicaciones de blog, avisos de seguridad) se gestionan a través de release/latest.json. Añade una entrada a announcements[], abre un PR, y una vez que se fusione en main, el flujo de trabajo de publicación sube el manifiesto al CDN en aproximadamente 60 segundos. Consulta la especificación técnica de verificación de actualización de versión para el esquema y la semántica de version_range.

Todos los contribuyentes deben firmar el Acuerdo de Licencia de Contribuyente (CLA) antes de que cualquier pull request pueda ser fusionado.

• Reportar errores o solicitar funciones

• Hacer preguntas o iniciar una discusión

• Escribir reglas de seguridad

Licencia

Apache-2.0