🦡 codebadger

Ein containerisierter Model Context Protocol (MCP)-Server, der statische Codeanalysen mithilfe der Code Property Graph (CPG)-Technologie von Joern bereitstellt, mit Unterstützung für Java, C/C++, JavaScript, Python, Go, Kotlin, C#, Ghidra, Jimple, PHP, Ruby und Swift.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes installiert haben:

• Docker und Docker Compose

• Python 3.10+ (Python 3.13 empfohlen)

• pip (Python-Paketmanager)

So überprüfen Sie Ihr Setup:

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

Schnellstart

1. Python-Abhängigkeiten installieren

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

# Install dependencies
pip install -r requirements.txt

2. Docker-Dienste starten (Joern)

docker compose up -d

Dies startet:

• Joern Server: Engine für statische Codeanalyse (führt CPG-Generierung und Abfragen aus)

Überprüfen Sie, ob die Dienste laufen:

docker compose ps

3. MCP-Server starten

# Start the server
python main.py &

Der MCP-Server ist unter http://localhost:4242 verfügbar.

4. Alle Dienste stoppen

# Stop MCP server (Ctrl+C in terminal)

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

Bereinigungsskript

Verwenden Sie das bereitgestellte Bereinigungsskript, um Ihre Umgebung zurückzusetzen:

bash cleanup.sh

Dies bewirkt:

• Stoppen und Entfernen von Docker-Containern

• Beenden verwaister Joern/MCP-Prozesse

• Löschen des Python-Caches (__pycache__, .pytest_cache)

• Optionales Löschen des Playground-Verzeichnisses (CPGs und zwischengespeicherte Codebasen)

Integrationen

GitHub Copilot-Integration

Bearbeiten Sie die MCP-Konfigurationsdatei für VS Code (GitHub Copilot):

Pfad:

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

Beispielkonfiguration:

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

Claude Code-Integration

Um codebadger in Claude Desktop zu integrieren, bearbeiten Sie:

Pfad:

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

Fügen Sie Folgendes hinzu:

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

Verfügbare Tools

Core

• generate_cpg: Generiert einen Code Property Graph (CPG) für eine Codebasis (lokaler Pfad oder GitHub-URL).

• get_cpg_status: Überprüft, ob ein CPG existiert, und ruft Status-Metadaten ab.

• run_cpgql_query: Führt eine rohe CPGQL-Abfrage gegen ein CPG aus und gibt strukturierte Ergebnisse zurück.

• get_cpgql_syntax_help: Zeigt CPGQL-Syntax-Hilfen, Tipps und Lösungen für häufige Fehler an.

Code-Browsing

• list_methods: Listet Methoden/Funktionen mit optionalen Regex-/Dateifiltern auf.

• list_files: Zeigt Quelldateien als paginierte Baumansicht an.

• get_method_source: Ruft den Quellcode für eine benannte Methode ab.

• list_calls: Listet Aufrufstellen zwischen Funktionen auf (Aufrufer → Aufgerufener).

• get_call_graph: Erstellt einen menschenlesbaren Aufrufgraph (eingehend oder ausgehend).

• list_parameters: Ruft Parameternamen, Typen und Reihenfolge für eine Methode ab.

• get_codebase_summary: Hochgradige Metriken (Dateien, Methoden, Aufrufe, Sprache).

• get_code_snippet: Gibt einen Dateiausschnitt anhand von Start-/Endzeilennummern zurück.

Semantische Analyse

• get_cfg: Erstellt einen Kontrollflussgraphen (Knoten und Kanten) für eine Methode.

• get_type_definition: Untersucht Struktur-/Klassentypen und deren Mitglieder.

• get_macro_expansion: Erkennt heuristisch wahrscheinlich makroerweiterte Aufrufe.

Taint- & Schwachstellenanalyse

• find_taint_sources: Findet wahrscheinliche externe Eingangspunkte (Quellen).

• find_taint_sinks: Lokalisiert gefährliche Senken, in die kontaminierte Daten fließen können.

• find_taint_flows: Erkennt Datenflüsse von Quellen zu Senken (Taint-Analyse).

• get_program_slice: Erstellt Rückwärts-/Vorwärts-Programmslices für einen Aufruf.

• get_variable_flow: Verfolgt Datenabhängigkeiten für eine Variable an einem Ort.

• find_bounds_checks: Sucht nach Grenzwertprüfungen in der Nähe eines Pufferzugriffs.

• find_use_after_free: Heuristische Erkennung von Use-After-Free-Mustern.

• find_double_free: Erkennt potenzielle Double-Free-Probleme.

• find_null_pointer_deref: Findet wahrscheinliche Null-Pointer-Dereferenzierungen.

• find_integer_overflow: Erkennt Integer-Überlaufmuster.

• find_format_string_vulns: Erkennt Format-String-Schwachstellen (CWE-134), bei denen nicht-literale Formatargumente an Funktionen der printf-Familie übergeben werden.

• find_heap_overflow: Erkennt Heap-Überlauf-Schwachstellen (CWE-122), bei denen Schreibvorgänge in Heap-Puffer ihre zugewiesene Größe überschreiten können.

• find_stack_overflow: Erkennt Stack-Pufferüberlauf-Schwachstellen (CWE-121), bei denen Schreibvorgänge in lokale Arrays fester Größe (z. B. char buf[64]) ihre deklarierte Dimension überschreiten können.

• find_toctou: Erkennt Time-of-Check-Time-of-Use-Race-Conditions (CWE-367), bei denen eine Datei mit access()/stat() geprüft und dann in einem separaten Schritt geöffnet oder bearbeitet wird.

• find_uninitialized_reads: Erkennt das Lesen nicht initialisierter Variablen (CWE-457), bei denen lokale Variablen verwendet werden, bevor ihnen ein Wert zugewiesen wurde.

Mitwirken & Tests

Vielen Dank für Ihren Beitrag! Hier ist eine kurze Anleitung für den Einstieg in das Ausführen von Tests und das Mitwirken am Code.

Voraussetzungen

• Python 3.10+ (3.13 wird in CI verwendet)

• Docker und Docker Compose (für Integrationstests)

Lokales Entwicklungs-Setup

1. Erstellen Sie eine virtuelle Umgebung und installieren Sie Abhängigkeiten

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

2. Starten Sie Docker-Dienste (für Integrationstests)

docker-compose up -d

3. Führen Sie Unit-Tests aus

pytest tests/ -q

4. Führen Sie Integrationstests aus (erfordert laufendes Docker Compose)

# Start MCP server in background
python main.py &

# Run integration tests
pytest tests/integration -q

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

5. Führen Sie alle Tests aus

pytest tests/ -q

6. Bereinigung nach dem Testen

bash cleanup.sh
docker-compose down

Code-Beiträge

Bitte befolgen Sie diese Richtlinien, wenn Sie einen Beitrag leisten:

1. Befolgen Sie die Repository-Konventionen

2. Schreiben Sie Tests für Verhaltensänderungen

3. Stellen Sie sicher, dass alle Tests bestehen, bevor Sie einen PR einreichen

4. Fügen Sie ein klares Changelog in Ihre PR-Beschreibung ein

5. Aktualisieren Sie die Dokumentation bei Bedarf

Konfiguration

Der MCP-Server kann über Umgebungsvariablen oder config.yaml konfiguriert werden.

Umgebungsvariablen

Wichtige Einstellungen (optional - Standardwerte werden angezeigt):

# 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

Konfigurationsdatei

Erstellen Sie eine config.yaml aus config.example.yaml:

cp config.example.yaml config.yaml

Passen Sie diese dann nach Bedarf an.

Telemetrie (OpenTelemetry)

CodeBadger verfügt über eine integrierte OpenTelemetry-Unterstützung für verteiltes Tracing. Wenn aktiviert, werden alle MCP-Tool-Aufrufe automatisch nachverfolgt, zusätzlich zu benutzerdefinierten Spans für CPG-Generierung, Joern-Server-Management und Abfrageausführung.

Schnellstart

1. Installieren Sie die Telemetrie-Abhängigkeiten (in requirements.txt enthalten):

pip install opentelemetry-sdk opentelemetry-exporter-otlp

2. Aktivieren Sie diese über Umgebungsvariablen:

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

Oder über config.yaml:

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

Lokale Entwicklung mit 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

Was wird nachverfolgt

Konfigurationsreferenz

Wenn Telemetrie deaktiviert ist (Standard), ist das gesamte Tracing ein No-Op ohne Overhead.