🦡 codebadger

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

Noticias

codebadger y su artículo adjunto — Bridging Code Property Graphs and Language Models for Program Analysis — han sido aceptados en el Software Vulnerability Management Workshop @ ICSE 2026. 🎉

Related MCP server: CodeBadger Toolkit

Cita

@article{lekssays2026bridging,
  title={Bridging Code Property Graphs and Language Models for Program Analysis},
  author={Lekssays, Ahmed},
  journal={arXiv preprint arXiv:2603.24837},
  year={2026}
}

¿Has encontrado una vulnerabilidad usando codebadger?

Si codebadger te ayudó a descubrir una vulnerabilidad del mundo real, nos encantaría saberlo. Abre una solicitud de extracción (pull request) añadiéndola a TROPHIES.md — incluye el ID de CVE, el proyecto, una descripción breve y la fecha.

Requisitos previos

Antes de comenzar, asegúrate de tener:

• Docker y Docker Compose instalados

• Python 3.10+ (se recomienda Python 3.13)

• pip (gestor de paquetes de Python)

Para verificar tu 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 las consultas)

Verifica que los servicios estén en ejecución:

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

Utiliza el script de limpieza proporcionado para restablecer tu entorno:

bash cleanup.sh

Esto hará lo siguiente:

• Detener y eliminar los contenedores de Docker

• Finalizar 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

Edita 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, edita:

Ruta:

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

Añade 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.

Exploración de código

• list_methods: Lista 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: Lista los sitios de llamada entre funciones (llamador → llamado).

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

• list_parameters: Obtiene nombres, tipos y orden de los parámetros para 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: Construye 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 a 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 arreglos locales de tamaño fijo (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 u 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.

Herramientas personalizadas

Puedes añadir tus propios detectores sin modificar la base de código principal:

1. Escribe una plantilla de consulta en Scala en src/tools/queries/tu_consulta.scala.

2. Registra una función de herramienta de Python en src/tools/custom_tools.py.

3. Reinicia el servidor: la herramienta aparecerá automáticamente en cada cliente MCP.

Consulta CUSTOM_TOOLS_GUIDE.md para obtener la guía completa paso a paso, la referencia de CPGQL y las decisiones de diseño.

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. Crea un entorno virtual e instala las dependencias

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

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

docker-compose up -d

3. Ejecuta pruebas unitarias

pytest tests/ -q

4. Ejecuta pruebas de integración (requiere que Docker Compose esté 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. Ejecuta todas las pruebas

pytest tests/ -q

6. Limpieza después de las pruebas

bash cleanup.sh
docker-compose down

Contribuciones de código

Por favor, sigue estas pautas al contribuir:

1. Sigue las convenciones del repositorio

2. Escribe pruebas para cambios de comportamiento

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

4. Incluye un registro de cambios claro en la descripción de tu PR

5. Actualiza la documentación si es necesario

Configuración

El servidor MCP se puede configurar mediante variables de entorno o config.yaml.

Variables de entorno

Ajustes 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

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

cp config.example.yaml config.yaml

Luego personalízalo 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. Instala las dependencias de telemetría (incluidas en requirements.txt):

pip install opentelemetry-sdk opentelemetry-exporter-otlp

2. Habilita mediante variables de entorno:

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

O mediante 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.