CodeGuard RAG MCP Server

Plattform zur Diagnose von Python-Codefehlern und Sicherheitslücken auf Basis von RAG + MCP

CodeGuard empfängt Python-Fehler, Tracebacks oder Codeausschnitte, extrahiert statische Merkmale und führt eine Hybridsuche mit Dense + BM25 durch. Zurückgegeben werden Problemklassifikation, Schwachstellentyp, CWE, Risikostufe, Belege, Ursache, Reparaturempfehlung, sicherer Code und Verifikationsmethode. Benutzercode wird nur geparst, nicht ausgeführt.

Die aktuelle Version ist das persönliche Projekt M1: Die modularen RAG-, ChromaDB-, BM25-, RRF-, optionalen Rerank-, MCP-Server-, Streamlit-Dashboard- und Observability-Technologien des ursprünglichen Projekts bleiben erhalten, während der Kernanwendungsfall auf die Diagnose von Codefehlern und Sicherheitsschwachstellen fokussiert wird.

Projektpositionierung

Das Projekt behandelt zwei Arten von Eingaben:

• Laufzeitfehler: wie TypeError, KeyError, ImportError; ausgegeben werden Fehlerursache und Reparaturschritte.

• Gefährlicher Code: wie shell=True, eval(), unsichere Deserialisierung; ausgegeben werden Schwachstellentyp, CWE und sichere Schreibweise.

M1 unterstützt nur Python. Es handelt sich um ein unterstützendes Diagnosetool, das keine manuelle Code-Überprüfung ersetzt und nicht beansprucht, Bandit oder Semgrep bereits integriert zu haben oder alle Schwachstellen zu finden.

Related MCP server: Lanalyzer MCP Server

Kernfunktionen

• Statische Eingabeanalyse: Extraktion von Ausnahmetyp, Traceback-Dateien und Zeilennummern, gefährlichen APIs und Schlüsselsymbolen.

• Strukturierte Sicherheits-Wissensbasis: Enthält 30 Schema-geprüfte Python-Fehler-, Schwachstellen-, Konfigurations- und Abhängigkeitsfälle.

• Hybridsuche: Dense Embedding übernimmt semantisches Matching, BM25 exaktes Matching für Ausnahmenamen, APIs, CWEs usw.

• Deterministische Diagnose: Erzeugt strukturierte Berichte auf Basis von Suchbelegen; ohne direkten Codebeleg wird die Konfidenz der Sicherheitsaussage herabgestuft.

• MCP-Anbindung: Stellt über diagnose_code_issue eine einheitliche Diagnosefähigkeit für MCP-Clients bereit.

• Zweiformat-Ausgabe: Gibt gleichzeitig gut lesbares chinesisches Markdown und maschinenlesbares JSON zurück.

• Offline-Regression: Die Kerntests verwenden feste Embeddings und feste Suchergebnisse; sie sind nicht von externen Modell-APIs abhängig.

Systemarchitektur

报错 / traceback / Python 代码
              │
              ▼
    SecurityInputParser
   异常、位置、危险模式、符号
              │
              ▼
    SecurityQueryBuilder
 精确词 + 安全语义扩展 + CWE
              │
       ┌──────┴──────┐
       ▼             ▼
Dense Retrieval   BM25 Retrieval
ChromaDB/cosine   关键词精确召回
       └──────┬──────┘
              ▼
         RRF Fusion
              │
        Optional Rerank
              │
              ▼
      DiagnosticService
  分类、证据、置信度、修复方案
              │
              ▼
 diagnose_code_issue (MCP)
      Markdown + JSON 报告

Wichtige Codestellen:

• src/security/analysis/: Eingabeanalyse und Konstruktion von Suchanfragen.

• src/security/loaders/: Laden und Validieren von JSON/JSONL-Sicherheitsfällen.

• src/security/ingestion/: Schreiben der Dual-Indizes ChromaDB und BM25.

• src/security/services/: Diagnose-Orchestrierung, Klassifikation und Degradierungsstrategie.

• src/mcp_server/tools/diagnose_code_issue.py: MCP-Tool und Berichtsformat.

• knowledge/security_cases.json: M1-Sicherheitswissensbasis.

Datenmodell der Sicherheitsfälle

Jeder Fall enthält case_id, issue_kind, error_type, vulnerability_type, cwe, severity, Symptome, Gefahrenmuster, Ursache, verwundbaren Code, Reparaturplan, sicheren Code, Verifikationsmethode und Referenzquelle.

Die Wissensbasis unterstützt JSON-Arrays und JSONL. Beim Import erzeugt ein Fall einen stabilen Chunk; case_id wird sowohl als Dokumentkennung für ChromaDB als auch für BM25 verwendet, um eine Vermischung der beiden Ergebnisse zu vermeiden.

Die 30 Fälle von M1 setzen sich zusammen aus:

• 8 gewöhnlichen Codefehlern

• 17 Sicherheitsschwachstellen

• 3 Konfigurationsrisiken

• 2 Abhängigkeitsrisiken

Verarbeitung von PDF und JSON

Die Hauptwissensbasis von CodeGuard bevorzugt JSON/JSONL, da CWE, Risikostufe und Reparaturempfehlungen stabile strukturierte Felder benötigen. Die ursprüngliche PDF-Aufnahmepipeline bleibt erhalten und eignet sich für den späteren Import von Sicherheitsrichtlinien, Schwachstellenberichten oder internen Dokumenten:

1. SHA256 wird verwendet, um zu prüfen, ob die Datei bereits verarbeitet wurde.

2. MarkItDown wandelt den PDF-Text in Markdown um.

3. PyMuPDF extrahiert Bilder, speichert sie unter data/images/ und schreibt den Platzhalter [IMAGE: id].

4. Optional erzeugt ein Vision-LLM Beschreibungen für Bilder; bei Fehlern wird auf reine Textverarbeitung zurückgegriffen.

5. Das Dokument wird in Blöcke zerlegt und mit Metadaten angereichert.

6. Es wird gleichzeitig in die Dense-Vektorbibliothek und den BM25-Index geschrieben.

PDF ist der allgemeine Dokumentenabruf-Einstieg; knowledge/security_cases.json ist die wichtigste Vertrauensgrundlage für die aktuellen Diagnoseergebnisse.

Dense + BM25 + RRF + Rerank

Dense Retrieval ist hier kein konkreter Algorithmusname, sondern eine Klasse semantischer Vektorabfragen:

• EmbeddingFactory wählt anhand von config/settings.yaml zwischen DashScope-, OpenAI-, Azure OpenAI- oder Ollama-Embeddings.

• Textvektoren werden in die ChromaDB-HNSW-Collection geschrieben; der Distanzraum ist cosine.

• Abfragevektoren und Fallvektoren werden nach Cosine-Ähnlichkeit abgerufen.

Auf der anderen Seite führt BM25 eine spärliche Stichwortsuche nach Begriffen wie TypeError, subprocess.run, shell=True, CWE-78 durch. RRF (Reciprocal Rank Fusion) kombiniert genau diese Rangliste der semantischen Dense-Suche mit der Rangliste der BM25-Stichwortsuche; der Standardwert ist rrf_k=60. Nach der Fusion kann je nach Konfiguration ein Cross-Encoder- oder LLM-Rerank aktiviert werden; M1 hat Rerank standardmäßig deaktiviert, um einen kostengünstigen lokalen Betrieb zu ermöglichen.

Schnellstart

Die folgenden Befehle richten sich an Windows PowerShell und erfordern Python 3.11+.

cd <project-directory>
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev]"

Das Projekt verwendet standardmäßig die OpenAI-kompatible Schnittstelle von DashScope: LLM ist qwen3.7-plus, Embedding ist qwen3.7-text-embedding (1024 Dimensionen), die Base-URL lautet https://dashscope.aliyuncs.com/compatible-mode/v1. Der API-Schlüssel wird nur aus der lokalen Umgebungsvariable DASHSCOPE_API_KEY gelesen und darf niemals in das Repository, in settings.yaml oder in Logs geschrieben werden.

$env:DASHSCOPE_API_KEY="<仅在本机设置，不要写入仓库>"
python scripts\check_dashscope_connectivity.py

Die oben genannte Konnektivitätsprüfung wird explizit ausgeführt: Sie sendet nur eine kurze LLM-Anfrage und eine Embedding-Anfrage für einen einzelnen Text. Der normale Start und die Dashboard-Bereitschaft prüfen nur lokale Konfiguration und Wissensbasis und verbrauchen keine Modellkontingente.

• Das Standardverzeichnis für ChromaDB ist data/db/chroma.

• Das BM25-Indexverzeichnis für Sicherheitsfälle ist data/db/bm25/code_security_cases.

• Die Base-URL kann über DASHSCOPE_BASE_URL überschrieben werden, was später eine Migration zu einer domänenspezifischen Geschäftsumgebung ermöglicht.

Führen Sie zuerst die grundlegenden Prüfungen ohne API-Schlüssel aus:

python main.py
python -m pytest tests\unit\security tests\unit\test_diagnose_code_issue.py -v

Sicherheitsfälle importieren

Beim ersten Gebrauch oder nach einem Wechsel von Embedding-Modell/-Dimensionen wird die Sammlung von Sicherheitsfällen mit dem aktuellen DashScope-Embedding neu aufgebaut:

python scripts\ingest_security_cases.py --rebuild

--rebuild erstellt nur code_security_cases und den zugehörigen security_-BM25-Index neu; andere Collections oder das gesamte Datenbankverzeichnis werden nicht gelöscht. Der Import ruft den Embedding-Dienst auf und verbraucht Token; die erfolgreiche Ausgabe sollte von Null verschiedene Zahlen für Fälle, Chunks und Vektoren enthalten. Die Wissensbasis speichert die Kennung des aktuellen Embeddings (provider, model, dimensions). Weicht diese von einer bereits vorhandenen, nicht leeren Collection ab, verlangt das System einen expliziten Neubau, um eine Vermischung alter Vektoren zu vermeiden.

MCP-Server starten

python -m src.mcp_server.server

Die Startkonfiguration für den MCP-Client kann wie folgt aussehen:

{
  "command": "<project-directory>\\.venv\\Scripts\\python.exe",
  "args": ["-m", "src.mcp_server.server"],
  "cwd": "<project-directory>"
}

Beispieleingabe für das Kern-Tool:

{
  "name": "diagnose_code_issue",
  "arguments": {
    "error_message": "",
    "code_snippet": "subprocess.run(user_input, shell=True)",
    "language": "python",
    "top_k": 5
  }
}

Der Server behält außerdem query_knowledge_hub, list_collections und get_document_summary, um die ursprünglichen RAG-Fähigkeiten anzusehen und wiederzuverwenden.

Dashboard starten

python -m streamlit run src\observability\dashboard\app.py

Das Dashboard öffnet standardmäßig die Seite „Schwachstellendiagnose“. Es unterstützt das Einfügen von Python-Fehlern, Codeausschnitten oder das Hochladen einer einzelnen UTF-8-.py-Datei sowie das Herunterladen von Markdown-/JSON-Berichten. Hochgeladene Inhalte werden nur im Speicher geparst, weder gespeichert noch ausgeführt. Nach dem Klick auf „Diagnose“ werden die eingegebenen Fehler oder Codes zusammen mit dem Kontext der abgerufenen Fälle an DashScope gesendet, um eine durch Qwen verbesserte Reparaturerklärung zu erzeugen; die Diagnose verbraucht ebenfalls Token. Bitte übermitteln Sie keine Schlüssel, personenbezogenen Daten oder Produktionsgeheimnisse, die nicht an Drittanbieterdienste gesendet werden sollten.

Das Embedding kann später konfiguriert werden: Wenn kein Embedding konfiguriert oder code_security_cases noch nicht importiert wurde, lässt sich die Seite weiterhin normal öffnen, weist aber darauf hin, zuerst die Konfiguration abzuschließen und Folgendes auszuführen:

python scripts\ingest_security_cases.py --rebuild

In diesem Zustand werden keine simulierten Diagnoseergebnisse erzeugt.

Diagnosebeispiel

Eingabe:

subprocess.run(user_input, shell=True)

Erwartete Kernresultate:

• Klassifikation: security_vulnerability

• Typ: Command Injection

• CWE: CWE-78

• Risikostufe: critical

• Beleg: subprocess-shell

• Reparatur: shell=True deaktivieren, Parameter-Array und Allowlist-Validierung verwenden

• Ähnliche Fälle: PY-SEC-002

Das vollständige Beispiel finden Sie unter docs/examples/codeguard-diagnosis-example.md.

Tests und Bewertung

python -m pytest tests\unit\security tests\unit\test_diagnose_code_issue.py `
  tests\integration\test_security_case_ingestion.py `
  tests\e2e\test_codeguard_diagnosis.py -v

python -m ruff check src\security `
  src\mcp_server\tools\diagnose_code_issue.py `
  scripts\ingest_security_cases.py `
  tests\unit\security `
  tests\unit\test_diagnose_code_issue.py `
  tests\e2e\test_codeguard_diagnosis.py

Ein normales python -m pytest führt standardmäßig nur Offline-Tests aus und entfernt automatisch die für den Testprozess und seine Unterprozesse sichtbaren DashScope-, OpenAI- und Azure-OpenAI-API-Schlüssel. Testfälle, die echte Modelldienste aufrufen, sind einheitlich mit llm markiert und müssen explizit ausgeführt werden; zum Beispiel:

python -m pytest -m llm tests\integration\test_chunk_refiner_llm.py -v

Führen Sie die oben genannten Befehle nur aus, wenn Sie bereit sind, echte Modellkontingente zu verbrauchen. Die aktuell unterstützten und verifizierten Mindestversionen der Clients sind chromadb>=1.5.9 und openai>=2.46.0.

Die derzeitige Verifizierung umfasst Datenmodell, Fallvalidierung, statisches Parsing, Abfrageerweiterung, Dual-Index-Schreiben, deterministische Diagnose, MCP-Registrierung und Offline-End-to-End-Ausgabe. Das Projekt behält die ursprünglichen Ragas/Custom-Bewertungsmodule bei, aber M1 liefert keine Genauigkeitszahlen, die nicht durch tatsächliche Experimente verifiziert wurden.

Einschränkungen und weitere Richtungen

• M1 analysiert nur Python und führt den zu diagnostizierenden Code nicht aus.

• Die aktuellen Gefahrenmuster sind eine erklärbare Regelmenge und kein vollständiges SAST.

• Die tatsächliche Dense-Suche benötigt einen verfügbaren Embedding-Provider; ohne API-Schlüssel funktionieren die MCP-Initialisierung und tools/list weiterhin, aber die echte Hybridsuche gibt einen lesbaren Konfigurationsfehler zurück.

• Ohne Suchergebnis wird degraded=true mit Konfidenz 0.0 zurückgegeben, mit dem Hinweis, Kontext zu ergänzen.

• Wenn nur eine Wissensbasis-Ähnlichkeit vorliegt, aber kein passender statischer Codebeleg, wird nicht direkt auf eine Schwachstelle geschlossen, sondern degraded=true und Konfidenz 0.0 zurückgegeben.

• M1 verwendet für die Konfidenz eine erklärbare Belegebenen-Struktur und interpretiert die heterogenen Rohwerte von RRF, BM25 oder cosine nicht direkt als Wahrscheinlichkeiten.

• Originalcode wird nicht direkt in entfernte Embedding-Abfragen eingefügt; in Ausnahmen enthaltene häufige API-Schlüssel, Tokens, Passwörter und Bearer-Anmeldedaten werden zuvor maskiert.

• Später können Datei-/Repository-Scans, Bandit/Semgrep-Ergebnisnormalisierung, Metriken für Golden-Test-Sets und Mehrsprachenunterstützung hinzugefügt werden.

Referenz für den Lebenslauf

Eigenständig entworfen und implementiert eine auf RAG + MCP basierende Plattform zur Diagnose von Python-Codefehlern und Sicherheitslücken; eine Wissensbasis mit 30 strukturierten Sicherheitsfällen sowie eine JSON/JSONL-Validierungs- und Import-Pipeline aufgebaut; Dense-Embedding- und BM25-Dual-Retrieval, RRF-Fusion und optionales Rerank eingesetzt; in Kombination mit statischen Belegen für Gefahrenmuster werden CWE, Risikostufe, Ursache und Reparaturplan ausgegeben; über MCP wird ein standardisiertes Diagnosewerkzeug bereitgestellt; die gesamte Kette aus ChromaDB, BM25 und MCP-Studio wird mit Unit-/Integrations-/E2E-Offlinetests verifiziert.

Im Lebenslauf sollten nur Funktionen genannt werden, die man tatsächlich ausgeführt, verstanden und erklären kann; keine ungemessenen Verbesserungsquoten angeben.