CodeGuard RAG MCP Server

RAG + MCP ベースの Python コード欠陥・脆弱性診断プラットフォーム

CodeGuard は Python エラー、traceback、コード断片を受け取り、静的特徴抽出と Dense + BM25 ハイブリッド検索を経て、問題分類、脆弱性タイプ、CWE、リスクレベル、 判断エビデンス、根本原因、修正提案、安全なコード、検証方法を返す。ユーザーコードは 解析のみ行われ、実行はされない。

現在のバージョンは個人プロジェクト M1 である。元プロジェクトのモジュール型 RAG、 ChromaDB、BM25、RRF、任意の Rerank、MCP Server、Streamlit Dashboard、 可観測性テクノロジースタックを維持し、中核シナリオをコード欠陥とセキュリティ 脆弱性診断に絞り込んでいる。

プロジェクトの位置付け

このプロジェクトは二種類の入力に対応する：

• 実行時エラー：TypeError、KeyError、ImportError など。欠陥の根本原因と修正手順を出力。

• 危険なコード：shell=True、eval()、安全でない逆シリアル化など。脆弱性タイプ、CWE、安全な書き方を出力。

M1 は Python のみをサポートする。補助診断ツールであり、人手によるコード監査を 代替するものではなく、Bandit、Semgrep との統合やあらゆる脆弱性の発見を謳うもの でもない。

Related MCP server: Lanalyzer MCP Server

中核機能

• 静的入力解析：例外タイプ、traceback のファイルと行番号、危険な API、重要シンボルを抽出。

• 構造化セキュリティ知識ベース：Schema 検証済みの Python 欠陥、脆弱性、設定、依存関係ケースを 30 件内蔵。

• ハイブリッド検索：Dense Embedding が意味的マッチングを、BM25 が例外名、API、CWE などの正確なマッチングを担当。

• 決定的診断：検索エビデンスから構造化レポートを生成。直接的なコードエビデンスがない場合はセキュリティ結論の信頼度を下げる。

• MCP 接続：diagnose_code_issue を通じて MCP Client に統一的診断能力を公開。

• 二形式出力：読みやすい中国語 Markdown とプログラム消費向け JSON を同時に返す。

• オフライン回帰：中核テストは固定 Embedding と固定検索結果を使用し、外部モデル API に依存しない。

システムアーキテクチャ

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

主要コードの場所：

• src/security/analysis/：入力解析と検索クエリ構築。

• src/security/loaders/：JSON/JSONL セキュリティケースの読み込みと検証。

• src/security/ingestion/：ChromaDB と BM25 の二重インデックス書き込み。

• src/security/services/：診断オーケストレーション、分類、ダウングレード戦略。

• src/mcp_server/tools/diagnose_code_issue.py：MCP ツールとレポート形式。

• knowledge/security_cases.json：M1 セキュリティ知識ベース。

セキュリティケースのデータモデル

各ケースには case_id、issue_kind、error_type、vulnerability_type、 cwe、severity、症状、危険パターン、根本原因、脆弱なコード、修正案、 安全なコード、検証方法、参考ソースが含まれる。

知識ベースは JSON 配列と JSONL をサポートする。インポート時は 1 ケースにつき 1 つの安定した Chunk が生成され、case_id は ChromaDB と BM25 の両方のドキュメント 識別子として使用され、二系統の結果のずれを防ぐ。

M1 の 30 ケースの内訳：

• 通常のコード欠陥 8 件

• セキュリティ脆弱性 17 件

• 設定リスク 3 件

• 依存関係リスク 2 件

PDF と JSON の処理方法

CodeGuard のメイン知識ベースは、CWE、リスクレベル、修正提案に安定した構造化 フィールドが必要なため、JSON/JSONL を優先する。元の PDF 取り込みパイプラインは 維持されており、今後セキュリティ規範、脆弱性レポート、社内ドキュメントの取り込みに 適している：

1. SHA256 を使用してファイルが処理済みかどうかを判定する。

2. MarkItDown を使用して PDF テキストを Markdown に変換する。

3. PyMuPDF を使用して画像を抽出し、data/images/ に保存して [IMAGE: id] プレースホルダーを書き込む。

4. オプションで Vision LLM を使用して画像の説明を生成する。失敗時はプレーンテキスト処理にダウングレードする。

5. ドキュメントをチャンク分割し、Metadata を補足する。

6. Dense ベクトルライブラリと BM25 インデックスの両方に書き込む。

PDF は汎用ドキュメント検索のエントリポイントである。knowledge/security_cases.json は 現在の診断結果の主要な信頼ソースである。

Dense + BM25 + RRF + Rerank

ここでの Dense Retrieval は特定のアルゴリズム名ではなく、意味ベクトル検索の分類である：

• EmbeddingFactory は config/settings.yaml に従って DashScope、OpenAI、Azure OpenAI、Ollama Embedding から選択する。

• テキストベクトルは ChromaDB HNSW コレクションに書き込まれ、距離空間は cosine。

• クエリベクトルとケースベクトルは cosine 類似度で再呼び出しされる。

もう一方は BM25 を使用して TypeError、subprocess.run、shell=True、CWE-78 などのキーワードでスパース検索を行う。RRF（Reciprocal Rank Fusion）が統合するのは Dense 意味検索ランキングと BM25 キーワード検索ランキングで、デフォルトは rrf_k=60 である。融合後は設定に応じて Cross-Encoder または LLM Rerank を 有効化できる。M1 はデフォルトで Rerank を無効化しており、ローカルでの低コスト 実行を容易にしている。

クイックスタート

以下のコマンドは Windows PowerShell 向けで、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]"

プロジェクトはデフォルトで DashScope の OpenAI 互換インターフェースを使用する。 LLM は qwen3.7-plus、Embedding は qwen3.7-text-embedding（1024 次元）、 Base URL は https://dashscope.aliyuncs.com/compatible-mode/v1 である。API Key は ローカル環境変数 DASHSCOPE_API_KEY からのみ読み取られ、リポジトリ、 settings.yaml、ログに決して書き込まれない。

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

上記の接続チェックは明示的に実行される。短い LLM リクエスト 1 回と単一テキストの Embedding リクエスト 1 回のみを送信する。通常の起動と Dashboard readiness チェックは ローカル設定と知識ベースのみを確認し、モデルクォータを消費しない。

• ChromaDB のデフォルトディレクトリは data/db/chroma。

• セキュリティケースの BM25 インデックスディレクトリは data/db/bm25/code_security_cases。

• DASHSCOPE_BASE_URL で Base URL を上書きでき、将来のビジネススペース専用ドメインへの移行に対応する。

まず API Key を必要としない基本チェックを実行する：

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

セキュリティケースのインポート

初回使用時、または Embedding モデル/次元を切り替えた後は、現在の DashScope Embedding を使用してセキュリティケースコレクションを再構築する：

python scripts\ingest_security_cases.py --rebuild

--rebuild は code_security_cases とその security_ BM25 インデックスのみを 再構築し、他のコレクションやデータベースディレクトリ全体は削除しない。インポートは Embedding サービスを呼び出して token を消費する。成功出力にはゼロ以外のケース数、 Chunk 数、ベクトル数が含まれている必要がある。知識ベースは現在の Embedding の provider、model、dimensions 識別子を保存し、既存の非空コレクションと一致しない 場合は明示的な再構築を要求し、古いベクトルの混用を避ける。

MCP Server の起動

python -m src.mcp_server.server

MCP Client の起動設定は次を使用できる：

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

中核ツールの入力例：

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

サーバーには query_knowledge_hub、list_collections、get_document_summary も残っており、既存の RAG 機能の確認と再利用が容易である。

Dashboard の起動

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

Dashboard はデフォルトで「脆弱性診断」ページを開き、Python エラーやコード断片の 貼り付け、単一の UTF-8 .py ファイルのアップロードに対応し、Markdown/JSON レポートをダウンロードできる。アップロードされた内容はメモリ内でのみ解析され、 保存や実行はされない。「診断」をクリックすると、入力されたエラーやコードは検索された ケースコンテキストとともに DashScope に送信され、Qwen 拡張の修正説明が生成される。 診断も token を消費する。第三者サービスに送信すべきでない秘密鍵、個人データ、 本番機密を送信しないこと。

Embedding は後から設定できる。Embedding が未設定、または code_security_cases が 未インポートの場合でもページは正常に開くが、設定を完了して以下を実行するよう 促すメッセージが表示される：

python scripts\ingest_security_cases.py --rebuild

この状態ではシミュレーション診断結果は生成されない。

診断例

入力：

subprocess.run(user_input, shell=True)

期待される中核結果：

• 分類：security_vulnerability

• タイプ：Command Injection

• CWE：CWE-78

• リスクレベル：critical

• エビデンス：subprocess-shell

• 修正：shell=True を無効化し、引数配列と許可リスト検証を使用

• 類似ケース：PY-SEC-002

完全な例は docs/examples/codeguard-diagnosis-example.md を参照。

テストと評価

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

通常の python -m pytest はデフォルトでオフラインテストのみを実行し、テストプロセスと その子プロセスから見える DashScope、OpenAI、Azure OpenAI API Key を自動的に削除する。 実際のモデルサービスを呼び出すテストケースは一律 llm とマークされ、明示的に実行する 必要がある。例：

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

実際のモデルクォータを消費する準備ができた場合のみ上記のコマンドを実行すること。 現在サポート・検証されているクライアントバージョンの下限は chromadb>=1.5.9 と openai>=2.46.0 である。

現在の検証範囲はデータモデル、ケース検証、静的解析、クエリ拡張、二重インデックス書き込み、 決定的診断、MCP 登録、オフライン E2E 出力である。プロジェクトには元の Ragas/Custom 評価モジュールが残っているが、M1 は実際の実験で検証されていない精度数値は提供しない。

制限と今後の方向性

• M1 は Python のみを解析し、診断対象のコードは実行しない。

• 現在の危険パターンは解釈可能なルールセットであり、完全な SAST とは同等ではない。

• 実際の Dense 検索には利用可能な Embedding Provider が必要である。API Key がない場合でも MCP 初期化と tools/list は動作するが、実際のハイブリッド検索は読みやすい設定エラーを返す。

• 検索結果がない場合は degraded=true、信頼度 0.0 を返し、コンテキストの追加を促す。

• 知識ベースの類似性のみで一致する静的コードエビデンスがない場合は、脆弱性と直接判定せず、 degraded=true と信頼度 0.0 を返す。

• M1 の信頼度は解釈可能なエビデンス階層を使用し、RRF、BM25、cosine の異種生スコアを 直接確率として解釈しない。

• 元のコードはリモート Embedding クエリに直接連結されない。例外内の一般的な API Key、 Token、Password、Bearer 認証情報は事前にマスクされる。

• 今後の拡張として、ファイル/リポジトリスキャン、Bandit/Semgrep 結果の正規化、 Golden Test Set メトリクス、多言語サポートが可能である。

履歴書での表現参考

RAG + MCP ベースの Python コード欠陥・脆弱性診断プラットフォームを独自に設計・実装し、 30 件の構造化セキュリティケース知識ベースと JSON/JSONL 検証インポートパイプラインを構築。 Dense Embedding + BM25 の二系統再呼び出し、RRF 融合、任意の Rerank を採用し、 静的危険パターンのエビデンスと組み合わせて CWE、リスクレベル、根本原因、修正案を出力し、 MCP を通じて標準化診断ツールを公開。Unit / Integration / E2E オフラインテストで ChromaDB、BM25、MCP stdio の全パイプラインを検証。

履歴書には実際に実行し、理解し、説明できる機能のみを書き、未測定の改善率は 記入しないこと。