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

Neuigkeiten

codebadger und das dazugehörige Paper — Bridging Code Property Graphs and Language Models for Program Analysis — wurden auf dem Software Vulnerability Management Workshop @ ICSE 2026 angenommen. 🎉

Related MCP server: Smart Code Reviewer

Zitierung

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

Haben Sie eine Sicherheitslücke mit codebadger gefunden?

Wenn codebadger Ihnen geholfen hat, eine reale Sicherheitslücke zu entdecken, würden wir gerne davon erfahren. Erstellen Sie einen Pull Request, um sie zu TROPHIES.md hinzuzufügen — geben Sie die CVE-ID, das Projekt, eine einzeilige Beschreibung und das Datum an.

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. Die Docker-Dienste starten (Joern)

docker compose up -d

Dies startet:

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

Überprüfen Sie, ob die Dienste laufen:

docker compose ps

3. Den 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 wird:

• Docker-Container stoppen und entfernen

• Verwaiste Joern/MCP-Prozesse beenden

• Python-Cache löschen (__pycache__, .pytest_cache)

• Optional das Playground-Verzeichnis leeren (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

Kern

• 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: Hochrangige 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() überprü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.

Benutzerdefinierte Tools

Sie können Ihre eigenen Detektoren hinzufügen, ohne den Kerncode zu ändern:

1. Schreiben Sie eine Scala-Abfragevorlage in src/tools/queries/your_query.scala.

2. Registrieren Sie eine Python-Toolfunktion in src/tools/custom_tools.py.

3. Starten Sie den Server neu — das Tool erscheint automatisch in jedem MCP-Client.

Siehe CUSTOM_TOOLS_GUIDE.md für die vollständige Schritt-für-Schritt-Anleitung, CPGQL-Referenz und Designentscheidungen.

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 Beitragen von 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 beim Mitwirken:

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-Serververwaltung 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 ü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.