Apoya el Desarrollo

Si este proyecto ayuda tu trabajo, apoya el mantenimiento continuo y nuevas funcionalidades.

Dirección de Donación en ETH
0x11282eE5726B3370c8B480e321b3B2aA13686582

Escanee el código QR o copie la dirección de billetera anterior.

Una herramienta CLI en Rust que descubre recursivamente repositorios Git, captura cambios de estado, genera diferencias, extrae elementos de código con fragmentos completos y produce informes centrados en seguridad para flujos de revisión de código y auditoría.

🎯 Características Principales

Descubrimiento de repositorios: Escanea directorios recursivamente en busca de repos Git con filtros configurables
Seguimiento de estado: Captura el estado previo/posterior a pull con hashes de commits, mensajes y detección de cambios sin commit
Generación de diferencias: Creación automática de diferencias N vs N-1 e históricas con manifiestos de archivos
Extracción de elementos: Analiza diferencias para identificar funciones, estructuras, clases, importaciones y más en más de 10 lenguajes
Fragmentos de código: Extrae código completo antes/después con detección de límites y ventanas de contexto
Etiquetado de seguridad: 18 patrones de seguridad integrados (crypto, auth, secretos, inyección SQL, XSS, etc.)
Informes multi-formato: Salidas JSON, Markdown, texto y SARIF con resumen de seguridad entre repositorios
Modo de diferencia entre ramas: Diferencia dos referencias (ramas, tags, commits) en un solo repositorio — ideal para revisiones de PR
Rendimiento: Procesamiento paralelo con barras de progreso, caché LRU y modo incremental

¿Por qué no solo usar bash?

Una línea como ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done solo muestra diferencias en bruto. DiffCatcher añade descubrimiento recursivo, extracción de elementos de código, detección de patrones de seguridad, salida SARIF para CI/CD, procesamiento paralelo y agregación de seguridad entre repositorios. Ver comparación completa más abajo.

🚀 Instalación

Desde Código Fuente

git clone https://github.com/Teycir/DiffCatcher.git
cd DiffCatcher
cargo build --release
./target/release/diffcatcher --help

Requisitos

Rust 1.70+
Git 2.0+

⚡ Inicio Rápido

# Escanear todos los repositorios en un directorio (solo fetch, sin modificaciones)
diffcatcher ~/projects

# Obtener actualizaciones y generar informe de seguridad
diffcatcher ~/projects --pull -o ./report

# Diferencia dos ramas en un solo repositorio (modo revisión de PR)
diffcatcher ./my-repo --diff main..feature/auth -o ./pr-report

# Generar salida SARIF para GitHub Code Scanning
diffcatcher ~/projects --summary-format sarif,json -o ./report

# Ejecución en seco para ver qué se escanearía
diffcatcher ~/projects --dry-run

# Escaneo rápido con 8 trabajadores en paralelo
diffcatcher ~/projects -j 8 --quiet

📖 Uso

Escaneo Básico

# Escanear con configuración por defecto (solo fetch)
diffcatcher <ROOT_DIR>

# Directorio de salida personalizado
diffcatcher ~/projects -o ./my-report

# Incluir repositorios anidados y seguir enlaces simbólicos
diffcatcher ~/projects --nested --follow-symlinks

# Omitir directorios ocultos
diffcatcher ~/projects --skip-hidden

Modos de Pull

# Solo fetch (por defecto - sin cambios en el árbol de trabajo)
diffcatcher ~/projects

# Realizar pull de cambios
diffcatcher ~/projects --pull

# Forzar pull con stash/pop para repositorios sucios
diffcatcher ~/projects --pull --force-pull

# Usar estrategia rebase
diffcatcher ~/projects --pull --pull-strategy rebase

# Omitir totalmente fetch/pull (solo diferencias históricas)
diffcatcher ~/projects --no-pull

Opciones de Extracción

# Omitir extracción de elementos (solo diferencias en bruto)
diffcatcher ~/projects --no-summary-extraction

# Extraer elementos pero omitir fragmentos de código
diffcatcher ~/projects --no-snippets

# Ajustar contexto de fragmentos y límites
diffcatcher ~/projects --snippet-context 10 --max-snippet-lines 300

# Limitar elementos por diferencia
diffcatcher ~/projects --max-elements 1000

Etiquetado de Seguridad

# Omitir etiquetado de seguridad
diffcatcher ~/projects --no-security-tags

# Incluir archivos de prueba en el análisis de seguridad
diffcatcher ~/projects --include-test-security

# Usar patrones de seguridad personalizados
diffcatcher ~/projects --security-tags-file ./custom-patterns.json

Archivo de Configuración

DiffCatcher puede cargar automáticamente la configuración local del proyecto desde:

<ROOT_DIR>/.diffcatcher.toml (por defecto)
un archivo personalizado mediante --config <FILE>
deshabilitado con --no-config

Ejemplo:

output = "reports-local"
no_pull = true
history_depth = 2
summary_formats = ["json", "txt"]
no_security_tags = false

[plugins]
security_pattern_files = ["plugins/security-extra.json"]
extractor_files = ["plugins/extractors.json"]

Los indicadores CLI aún anulan los valores de configuración cuando se establecen explícitamente.

Sistema de Plugins

DiffCatcher soporta dos tipos de plugins:

Plugins de patrones de seguridad mediante --security-plugin-file <FILE> (repetible)
Plugins de extractores mediante --extractor-plugin-file <FILE> (repetible)

El formato del plugin de seguridad coincide con el JSON de --security-tags-file (version, mode, tags).

Formato del plugin extractor:

{
  "version": 1,
  "extractors": [
    {
      "name": "policy-rule",
      "kind": "Config",
      "regex": "^policy\\s+([A-Za-z_][A-Za-z0-9_]*)"
    }
  ]
}

Modo de Diferencia entre Ramas (Revisión de PR)

# Diferencia dos ramas en un solo repositorio
diffcatcher ./my-repo --diff main..feature/auth

# Diferencia commits específicos
diffcatcher ./my-repo --diff abc123..def456

# Diferencia con salida SARIF para integración en CI
diffcatcher ./my-repo --diff origin/main..HEAD --summary-format sarif -o ./pr-report

El indicador --diff BASE..HEAD omite el descubrimiento de repositorios y fetch/pull — diferencia directamente dos referencias (ramas, tags o SHAs de commit) y ejecuta el proceso completo de extracción + etiquetado de seguridad sobre el resultado.

Salida SARIF

# Generar SARIF junto con otros formatos
diffcatcher ~/projects --summary-format sarif,json,md

# Solo SARIF para subida a CI/CD
diffcatcher ~/projects --summary-format sarif -o ./report

Cuando sarif está incluido en --summary-format, se escribe un archivo results.sarif en la raíz del informe. Este archivo sigue el estándar SARIF 2.1.0 y se integra con GitHub Code Scanning, VS Code SARIF Viewer, Azure DevOps y otras herramientas compatibles con SARIF.

Funcionalidades Avanzadas

# Modo incremental (omitir repositorios sin cambios)
diffcatcher ~/projects --incremental -o ./report

# Filtrar por patrón de rama
diffcatcher ~/projects --branch-filter "main"

# Ajustar profundidad histórica
diffcatcher ~/projects --history-depth 5

# Salida JSON para CI/CD
diffcatcher ~/projects --quiet --json > result.json

# Salida verbosa con rutas descubiertas
diffcatcher ~/projects --verbose

📁 Estructura del Informe

<report_dir>/
├── summary.json                    # Resumen global
├── summary.md                      # Resumen en Markdown
├── results.sarif                   # Salida SARIF 2.1.0 (cuando --summary-format sarif)
├── security_overview.json          # Agregación de seguridad entre repositorios
├── security_overview.md
├── <repo-name>/
│   ├── status.json                 # Estado del repositorio
│   ├── pull_log.txt
│   └── diffs/
│       ├── diff_N_vs_N-1.patch     # Diferencia unificada en bruto
│       ├── changes_N_vs_N-1.txt    # Manifiesto de archivos
│       ├── summary_N_vs_N-1.json   # Extracción de elementos
│       ├── summary_N_vs_N-1.md
│       └── snippets/
│           ├── 001_validate_token_ADDED.rs
│           ├── 002_check_permissions_BEFORE.rs
│           ├── 002_check_permissions_AFTER.rs
│           └── 002_check_permissions.diff
└── ...

⚙️ Configuración

Indicadores CLI

Consulte diffcatcher --help para todas las opciones.

Patrones de Seguridad Personalizados

Cree un archivo JSON con patrones personalizados:

{
  "version": 1,
  "mode": "extend",
  "tags": [
    {
      "tag": "pii-handling",
      "description": "Procesamiento de datos PII",
      "severity": "High",
      "patterns": ["ssn", "social_security", "passport"]
    }
  ]
}

Use con --security-tags-file ./patterns.json

🏗️ Arquitectura

src/
├── cli.rs              # Análisis de argumentos
├── scanner.rs          # Descubrimiento de repositorios
├── git/                # Operaciones Git
│   ├── commands.rs     # Envoltorios Git
│   ├── state.rs        # Captura de estado
│   ├── diff.rs         # Generación de diferencias
│   └── file_retrieval.rs
├── extraction/         # Extracción de elementos
│   ├── parser.rs       # Analizador de diferencias unificadas
│   ├── elements.rs     # Detección de elementos
│   ├── snippets.rs     # Extracción de fragmentos de código
│   ├── boundary.rs     # Seguimiento de corchetes/sangría
│   └── languages/      # Patrones específicos de lenguaje
├── security/           # Etiquetado de seguridad
│   ├── tagger.rs       # Coincidencia de patrones
│   ├── patterns.rs     # Patrones integrados
│   └── overview.rs     # Agregación entre repositorios
└── report/             # Generación de informes
    ├── writer.rs       # Estructura de directorios
    ├── json.rs         # Serialización JSON
    ├── sarif.rs        # Salida SARIF 2.1.0
    ├── markdown.rs     # Formateo Markdown
    └── snippet_writer.rs

Comparación con Bash

Una línea simple de bash puede listar diferencias:

ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done

Esto funciona para comprobaciones rápidas, pero DiffCatcher añade capacidades significativas:

La línea bash tiene ~100 bytes. DiffCatcher es una herramienta de auditoría centrada en seguridad con extracción completa de elementos de código.

🧪 Pruebas

# Ejecutar todas las pruebas
cargo test

# Ejecutar un conjunto específico de pruebas
cargo test security_tagger

# Ejecutar con salida
cargo test -- --nocapture

La cobertura de pruebas incluye:

Pruebas unitarias para extracción, etiquetado de seguridad, detección de límites
Pruebas de integración para captura de estado, generación de diferencias, informes
Pruebas de archivos dorados para precisión de extracción
Pruebas de casos extremos (HEAD separada, repositorios desnudos, un solo commit)

Benchmarks de Rendimiento

# Compilar binarios de benchmark
cargo bench --no-run

# Ejecutar el conjunto de benchmarks
cargo bench --bench core_bench

El código fuente de los benchmarks está en benches/core_bench.rs y mide el rendimiento del analizador/extracción.

CI/CD

Se incluyen workflows de GitHub Actions:

.github/workflows/ci.yml: verificación de formato, clippy, pruebas, compilación de benchmarks
.github/workflows/release.yml: empaquetado de versiones basado en tags y publicación de releases en GitHub

📚 Documentación

Documentación del Proyecto

Plan.md - Especificación completa (v1.2)
Roadmap.md - Hoja de ruta de implementación y progreso
Referencia de patrones de seguridad (ver src/security/patterns.rs)

Documentación del Código

Todos los módulos incluyen documentación en línea completa. Módulos clave:

src/extraction/parser.rs - Analizador de diferencias unificadas con extracción de fragmentos
src/extraction/elements.rs - Detección de elementos de código consciente del lenguaje
src/extraction/snippets.rs - Extracción de fragmentos de código completos con detección de límites
src/security/tagger.rs - Motor de coincidencia de patrones de seguridad
src/git/commands.rs - Envoltorios de operaciones Git

Generar documentación API completa:

cargo doc --open

🏷️ Etiquetas

#rust #git #security #code-review #diff-analysis #static-analysis #devops #cli-tool #audit #vulnerability-detection #code-quality #snippet-extraction #parallel-processing #security-scanning

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

Haga un fork del repositorio
Cree una rama de características
Añada pruebas para la nueva funcionalidad
Asegúrese de que cargo test pasa
Envíe un pull request

`-o, --output`	`./reports/<timestamp>`	Directorio de salida del informe
`-j, --parallel`	`4`	Procesamiento concurrente de repositorios
`-t, --timeout`	`120`	Tiempo de espera para operaciones Git (segundos)
`-d, --history-depth`	`2`	Commits históricos para diferenciar
`--snippet-context`	`5`	Líneas de contexto alrededor de cambios
`--max-snippet-lines`	`200`	Máximo de líneas por fragmento
`--max-elements`	`500`	Máximo de elementos por diferencia
`--diff`	—	Diferencia dos referencias en un solo repositorio (`BASE..HEAD`)
`--summary-format`	`json,md`	Formatos de salida: `json`, `md`, `txt`, `sarif`

Descubrimiento recursivo	Solo elementos de nivel superior	Repositorios anidados, enlaces simbólicos, filtros
Seguimiento de estado	Ninguno	Hashes de commit, detección de cambios, registros de pull
Comprensión de código	Solo diferencia en bruto	Extrae funciones/estructuras/clases en más de 10 lenguajes
Fragmentos de código	Ninguno	Antes/después completo con ventanas de contexto
Análisis de seguridad	Ninguno	18 patrones integrados (autenticación, crypto, secretos, SQLi, XSS)
Formatos de salida	Solo terminal	JSON, Markdown, SARIF (GitHub Code Scanning)
Vista entre repositorios	Por repositorio	Informe de seguridad agregado en todos los repositorios
Rendimiento	Secuencial	Trabajadores paralelos, caché LRU, modo incremental
Integración CI/CD	Ninguna	Carga SARIF a GitHub/Azure DevOps
Manejo de errores	Supresión `
Manejo de rutas	Fallos con espacios	Maneja correctamente todos los nombres de ruta
Contexto histórico	`HEAD~1` fijo	Profundidad configurable, seguimiento de estado

Más Populares

DiffCatcher