CodeGuard RAG MCP Server

Платформа диагностики дефектов и уязвимостей Python-кода на основе RAG + MCP

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 и ключевых символов.

• Структурированная база знаний по безопасности: 30 встроенных проверенных по Schema случаев дефектов, уязвимостей, конфигураций и зависимостей Python.

• Гибридный поиск: Dense Embedding отвечает за семантическое соответствие, BM25 — за точное совпадение имён исключений, API, CWE и т.д.

• Детерминированная диагностика: формирование структурированного отчёта на основе найденных доказательств; при отсутствии прямых доказательств в коде уверенность в выводе о безопасности снижается.

• Интеграция с MCP: единая диагностическая возможность, доступная MCP-клиенту через diagnose_code_issue.

• Двухформатный вывод: одновременно возвращаются удобочитаемый 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. При импорте один случай порождает один стабильный Chunk; case_id используется как идентификатор документа одновременно для ChromaDB и BM25, что предотвращает рассинхронизацию результатов двух путей.

30 случаев M1 состоят из:

• 8 обычных дефектов кода

• 17 уязвимостей безопасности

• 3 рисков конфигурации

• 2 рисков зависимостей

Обработка PDF и JSON

Основная база знаний CodeGuard отдаёт приоритет JSON/JSONL, поскольку для CWE, уровня риска и рекомендаций по исправлению требуются стабильные структурированные поля. Существующий конвейер приёма PDF сохранён и подходит для последующего импорта нормативов безопасности, отчётов об уязвимостях или внутренних документов:

1. Проверка по SHA256, был ли файл уже обработан.

2. Преобразование текста PDF в Markdown с помощью MarkItDown.

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 выбирает DashScope, OpenAI, Azure OpenAI или Ollama Embedding в соответствии с config/settings.yaml.

• Текстовые векторы записываются в коллекцию ChromaDB HNSW, пространство расстояний — cosine.

• Вектор запроса и векторы случаев сопоставляются по cosine similarity.

Другой путь использует 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]"

По умолчанию проект использует OpenAI-совместимый интерфейс DashScope: 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-запрос и один запрос Embedding для одного текста. Обычный запуск и готовность (readiness) Dashboard проверяют только локальную конфигурацию и базу знаний и не расходуют квоту моделей.

• Каталог ChromaDB по умолчанию — data/db/chroma.

• Каталог BM25-индекса случаев безопасности — data/db/bm25/code_security_cases.

• Base URL можно переопределить через DASHSCOPE_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 и его BM25-индекс security_, не удаляя другие коллекции или весь каталог базы данных. Импорт вызывает сервис Embedding и расходует token; успешный вывод должен содержать ненулевые количества случаев, Chunk и векторов. База знаний сохраняет идентификаторы provider, model и dimensions текущего Embedding; если они не совпадают с уже существующей непустой коллекцией, система потребует явного пересоздания, чтобы избежать смешивания старых векторов.

Запуск 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, фрагментов кода или загрузку одного файла .py в кодировке UTF-8, а также скачивание отчётов 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 по умолчанию запускает только офлайн-тесты и автоматически удаляет API Key DashScope, OpenAI и Azure OpenAI, видимые тестовому процессу и его дочерним процессам. Тесты, которые вызывают реальные сервисы моделей, единообразно помечаются как llm и должны запускаться явно; например:

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

Запускайте приведённую выше команду, только если готовы расходовать реальную квоту моделей. Текущий минимальный поддерживаемый и проверенный состав версий клиентов: chromadb>=1.5.9 и openai>=2.46.0.

Текущая проверка охватывает модель данных, валидацию случаев, статический разбор, расширение запросов, запись двойного индекса, детерминированную диагностику, регистрацию MCP и офлайн-вывод от начала до конца. Проект сохраняет исходные модули оценки 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 и поддержку нескольких языков.

Формулировка для резюме

Самостоятельно спроектировал и реализовал платформу диагностики дефектов и уязвимостей Python-кода на основе RAG + MCP, построил базу знаний из 30 структурированных случаев безопасности и конвейер импорта с валидацией JSON/JSONL; применил двухпутевой поиск Dense Embedding + BM25, слияние RRF и опциональный Rerank, а на основе доказательств статических опасных паттернов вывел CWE, уровень риска, первопричину и план исправления; через MCP предоставил стандартизированный диагностический инструмент; офлайн-тестами Unit / Integration / E2E проверил ChromaDB, BM25 и MCP stdio по полному контуру.

В резюме следует указывать только те функции, которые вы действительно запускали, понимаете и можете объяснить; не вписывайте неизмеренные показатели улучшения.