🦡 codebadger

Un servidor del Protocolo de Contexto de Modelo (MCP) en contenedores que proporciona análisis de código estático utilizando la tecnología de Grafo de Propiedades de Código (CPG) de Joern, con soporte para Java, C/C++, JavaScript, Python, Go, Kotlin, C#, Ghidra, Jimple, PHP, Ruby y Swift.

Requisitos previos

Antes de comenzar, asegúrese de tener:

• Docker y Docker Compose instalados

• Python 3.10+ (se recomienda Python 3.13)

• pip (gestor de paquetes de Python)

Para verificar su configuración:

docker --version
docker-compose --version
python --version

Inicio rápido

1. Instalar dependencias de Python

# Create a virtual environment (optional but recommended)
python -m venv venv

# Install dependencies
pip install -r requirements.txt

2. Iniciar los servicios de Docker (Joern)

docker compose up -d

Esto inicia:

• Servidor Joern: Motor de análisis de código estático (ejecuta la generación de CPG y consultas)

Verifique que los servicios se estén ejecutando:

docker compose ps

3. Iniciar el servidor MCP

# Start the server
python main.py &

El servidor MCP estará disponible en http://localhost:4242.

4. Detener todos los servicios

# Stop MCP server (Ctrl+C in terminal)

# Stop Docker services
docker-compose down
# Optional: Clean up everything
bash cleanup.sh

Script de limpieza

Utilice el script de limpieza proporcionado para restablecer su entorno:

bash cleanup.sh

Esto hará lo siguiente:

• Detener y eliminar los contenedores de Docker

• Finalizar los procesos huérfanos de Joern/MCP

• Limpiar la caché de Python (__pycache__, .pytest_cache)

• Opcionalmente, limpiar el directorio de pruebas (CPGs y bases de código en caché)

Integraciones

Integración con GitHub Copilot

Edite el archivo de configuración de MCP para VS Code (GitHub Copilot):

Ruta:

~/.config/Code/User/mcp.json

Ejemplo de configuración:

{
  "inputs": [],
  "servers": {
    "codebadger": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

Integración con Claude Code

Para integrar codebadger en Claude Desktop, edite:

Ruta:

Claude → Settings → Developer → Edit Config → claude_desktop_config.json

Agregue lo siguiente:

{
  "mcpServers": {
    "codebadger": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

Herramientas disponibles

Núcleo

• generate_cpg: Genera un Grafo de Propiedades de Código (CPG) para una base de código (ruta local o URL de GitHub).

• get_cpg_status: Comprueba si existe un CPG y recupera metadatos de estado.

• run_cpgql_query: Ejecuta una consulta CPGQL sin procesar contra un CPG y devuelve resultados estructurados.

• get_cpgql_syntax_help: Muestra ayudantes de sintaxis CPGQL, consejos y correcciones de errores comunes.

Navegación de código

• list_methods: Enumera métodos/funciones con filtros opcionales de regex/archivo.

• list_files: Muestra los archivos fuente como una vista de árbol paginada.

• get_method_source: Recupera el código fuente de un método nombrado.

• list_calls: Enumera los sitios de llamada entre funciones (llamador → llamado).

• get_call_graph: Crea un grafo de llamadas legible por humanos (entrante o saliente).

• list_parameters: Obtiene nombres, tipos y orden de los parámetros de un método.

• get_codebase_summary: Métricas de alto nivel (archivos, métodos, llamadas, lenguaje).

• get_code_snippet: Devuelve un fragmento de archivo por números de línea de inicio/fin.

Análisis semántico

• get_cfg: Produce un grafo de flujo de control (nodos y aristas) para un método.

• get_type_definition: Inspecciona tipos de estructura/clase y sus miembros.

• get_macro_expansion: Detecta heurísticamente llamadas probablemente expandidas por macros.

Análisis de contaminación y vulnerabilidades

• find_taint_sources: Encuentra puntos de entrada externos probables (fuentes).

• find_taint_sinks: Localiza sumideros peligrosos donde pueden fluir datos contaminados.

• find_taint_flows: Detecta flujos de datos desde fuentes a sumideros (análisis de contaminación).

• get_program_slice: Crea cortes de programa hacia atrás/adelante para una llamada.

• get_variable_flow: Rastrea dependencias de datos para una variable en una ubicación.

• find_bounds_checks: Busca comprobaciones de límites cerca de un acceso al búfer.

• find_use_after_free: Detección heurística de patrones de uso después de liberación (use-after-free).

• find_double_free: Detecta posibles problemas de doble liberación.

• find_null_pointer_deref: Encuentra probables desreferencias de puntero nulo.

• find_integer_overflow: Detecta patrones de desbordamiento de enteros.

• find_format_string_vulns: Detecta vulnerabilidades de cadena de formato (CWE-134) donde se pasan argumentos de formato no literales a funciones de la familia printf.

• find_heap_overflow: Detecta vulnerabilidades de desbordamiento de montón (CWE-122) donde las escrituras en búferes de montón pueden exceder su tamaño asignado.

• find_stack_overflow: Detecta vulnerabilidades de desbordamiento de búfer de pila (CWE-121) donde las escrituras en matrices locales de tamaño fijo (p. ej., char buf[64]) pueden exceder su dimensión declarada.

• find_toctou: Detecta condiciones de carrera de tipo Time-of-Check-Time-of-Use (CWE-367) donde un archivo se verifica con access()/stat() y luego se abre o se opera en un paso separado.

• find_uninitialized_reads: Detecta lecturas de variables no inicializadas (CWE-457) donde se utilizan variables locales antes de asignarles un valor.

Contribuciones y pruebas

¡Gracias por contribuir! Aquí tienes una guía rápida para empezar a ejecutar pruebas y contribuir con código.

Requisitos previos

• Python 3.10+ (se usa 3.13 en CI)

• Docker y Docker Compose (para pruebas de integración)

Configuración de desarrollo local

1. Cree un entorno virtual e instale las dependencias

python -m venv venv
pip install -r requirements.txt

2. Inicie los servicios de Docker (para pruebas de integración)

docker-compose up -d

3. Ejecute pruebas unitarias

pytest tests/ -q

4. Ejecute pruebas de integración (requiere Docker Compose en ejecución)

# Start MCP server in background
python main.py &

# Run integration tests
pytest tests/integration -q

# Stop MCP server
pkill -f "python main.py"

5. Ejecute todas las pruebas

pytest tests/ -q

6. Limpieza después de las pruebas

bash cleanup.sh
docker-compose down

Contribuciones de código

Siga estas pautas al contribuir:

1. Siga las convenciones del repositorio

2. Escriba pruebas para cambios de comportamiento

3. Asegúrese de que todas las pruebas pasen antes de enviar el PR

4. Incluya un registro de cambios claro en la descripción de su PR

5. Actualice la documentación si es necesario

Configuración

El servidor MCP se puede configurar a través de variables de entorno o config.yaml.

Variables de entorno

Configuraciones clave (opcional - se muestran los valores predeterminados):

# Server
MCP_HOST=0.0.0.0
MCP_PORT=4242

# Joern
JOERN_BINARY_PATH=joern
JOERN_JAVA_OPTS="-Xmx4G -Xms2G -XX:+UseG1GC -Dfile.encoding=UTF-8"

# CPG Generation
CPG_GENERATION_TIMEOUT=600
MAX_REPO_SIZE_MB=500

# Query
QUERY_TIMEOUT=30
QUERY_CACHE_ENABLED=true
QUERY_CACHE_TTL=300

# Telemetry (OpenTelemetry)
OTEL_ENABLED=false
OTEL_SERVICE_NAME=codebadger
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Archivo de configuración

Cree un config.yaml a partir de config.example.yaml:

cp config.example.yaml config.yaml

Luego personalícelo según sea necesario.

Telemetría (OpenTelemetry)

CodeBadger tiene soporte integrado para OpenTelemetry para el rastreo distribuido. Cuando está habilitado, todas las llamadas a herramientas MCP se rastrean automáticamente, además de rangos personalizados para la generación de CPG, la gestión del servidor Joern y la ejecución de consultas.

Inicio rápido

1. Instale las dependencias de telemetría (incluidas en requirements.txt):

pip install opentelemetry-sdk opentelemetry-exporter-otlp

2. Habilite a través de variables de entorno:

export OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
python main.py

O a través de config.yaml:

telemetry:
  enabled: true
  service_name: codebadger
  otlp_endpoint: http://localhost:4317
  otlp_protocol: grpc  # or "http/protobuf"

Desarrollo local con Jaeger

# Start Jaeger (provides UI at http://localhost:16686)
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Start CodeBadger with telemetry
OTEL_ENABLED=true python main.py

Qué se rastrea

Referencia de configuración

Cuando la telemetría está deshabilitada (predeterminado), todo el rastreo es una operación nula sin sobrecarga.