CodeGuard RAG MCP Server

Plataforma basada en RAG + MCP para el diagnóstico de defectos de código y vulnerabilidades en Python

CodeGuard recibe errores de Python, tracebacks o fragmentos de código y, tras la extracción de características estáticas y la búsqueda híbrida Dense + BM25, devuelve la clasificación del problema, el tipo de vulnerabilidad, el CWE, el nivel de riesgo, las evidencias del diagnóstico, la causa raíz, las recomendaciones de corrección, el código seguro y los métodos de verificación. El código del usuario solo se analiza; nunca se ejecuta.

La versión actual es el proyecto personal M1: conserva el RAG modular, ChromaDB, BM25, RRF, Rerank opcional, MCP Server, Streamlit Dashboard y la pila de observabilidad del proyecto original, y concentra el escenario principal en el diagnóstico de defectos de código y vulnerabilidades de seguridad.

Posicionamiento del proyecto

Este proyecto aborda dos tipos de entrada:

• Errores en tiempo de ejecución: como TypeError, KeyError, ImportError; genera la causa raíz del defecto y los pasos de corrección.

• Código peligroso: como shell=True, eval(), deserialización insegura; genera el tipo de vulnerabilidad, el CWE y la forma segura de escribir el código.

M1 solo admite Python. Es una herramienta de diagnóstico auxiliar, no sustituye la auditoría manual de código ni afirma que ya integre Bandit, Semgrep o que pueda detectar todas las vulnerabilidades.

Related MCP server: Lanalyzer MCP Server

Capacidades principales

• Análisis estático de la entrada: extrae el tipo de excepción, los archivos y números de línea del traceback, las API peligrosas y los símbolos clave.

• Base de conocimiento de seguridad estructurada: incluye 30 casos de defectos, vulnerabilidades, configuración y dependencias de Python validados mediante Schema.

• Búsqueda híbrida: el Dense Embedding se encarga de la coincidencia semántica; BM25, de la coincidencia exacta de nombres de excepción, API, CWE, etc.

• Diagnóstico determinista: genera informes estructurados a partir de las evidencias recuperadas; sin evidencias directas de código, reduce la confianza de las conclusiones de seguridad.

• Integración MCP: expone una capacidad de diagnóstico unificada al cliente MCP a través de diagnose_code_issue.

• Salida en dos formatos: devuelve a la vez Markdown en chino, fácil de leer, y JSON, fácil de consumir por programas.

• Regresión offline: las pruebas principales usan Embeddings fijos y resultados de búsqueda fijos, sin depender de API de modelos externos.

Arquitectura del sistema

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

Ubicación principal del código:

• src/security/analysis/: análisis de la entrada y construcción de consultas de búsqueda.

• src/security/loaders/: carga y validación de casos de seguridad JSON/JSONL.

• src/security/ingestion/: escritura del doble índice ChromaDB y BM25.

• src/security/services/: orquestación del diagnóstico, clasificación y estrategias de degradación.

• src/mcp_server/tools/diagnose_code_issue.py: herramienta MCP y formato de informe.

• knowledge/security_cases.json: base de conocimiento de seguridad de M1.

Modelo de datos de los casos de seguridad

Cada caso incluye case_id, issue_kind, error_type, vulnerability_type, cwe, severity, síntomas, patrones peligrosos, causa raíz, código vulnerable, plan de corrección, código seguro, métodos de verificación y fuentes de referencia.

La base de conocimiento admite matrices JSON y JSONL. Al importar, cada caso genera un Chunk estable; case_id se usa como identificador de documento tanto en ChromaDB como en BM25 para evitar el desajuste entre los resultados de ambas vías.

Los 30 casos de M1 se componen de:

• 8 defectos de código comunes

• 17 vulnerabilidades de seguridad

• 3 riesgos de configuración

• 2 riesgos de dependencias

Tratamiento de PDF y JSON

La base de conocimiento principal de CodeGuard usa preferentemente JSON/JSONL, porque el CWE, el nivel de riesgo y las recomendaciones de corrección necesitan campos estructurados estables. La cadena original de ingesta de PDF se conserva y es adecuada para importar posteriormente normas de seguridad, informes de vulnerabilidades o documentación interna:

1. Usa SHA256 para comprobar si el archivo ya se ha procesado.

2. Usa MarkItDown para convertir el texto del PDF a Markdown.

3. Usa PyMuPDF para extraer las imágenes, las guarda en data/images/ y escribe el marcador de posición [IMAGE: id].

4. Opcionalmente usa un Vision LLM para generar descripciones de las imágenes; si falla, se degrada al procesamiento de texto plano.

5. Divide el documento en fragmentos y añade metadatos.

6. Escribe simultáneamente en la base vectorial Dense y en el índice BM25.

El PDF es la puerta de entrada para la búsqueda general de documentos; knowledge/security_cases.json es la principal fuente fiable de los resultados de diagnóstico actuales.

Dense + BM25 + RRF + Rerank

Aquí, Dense Retrieval no es el nombre de un algoritmo concreto, sino una categoría de búsqueda semántica por vectores:

• EmbeddingFactory selecciona DashScope, OpenAI, Azure OpenAI u Ollama Embedding según config/settings.yaml.

• Los vectores de texto se escriben en la colección ChromaDB HNSW; el espacio de distancia es cosine.

• El vector de consulta recupera los vectores de caso según la similitud cosine.

La otra vía usa BM25 para realizar una búsqueda dispersa de palabras clave como TypeError, subprocess.run, shell=True, CWE-78. RRF (Reciprocal Rank Fusion) fusiona precisamente el ranking de la búsqueda semántica Dense y el ranking de la búsqueda por palabras clave de BM25, con rrf_k=60 por defecto. Tras la fusión, se puede habilitar Cross-Encoder o LLM Rerank según la configuración; en M1, el Rerank está desactivado por defecto para facilitar la ejecución local de bajo costo.

Inicio rápido

Los siguientes comandos están pensados para Windows PowerShell y requieren 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]"

El proyecto usa por defecto la interfaz compatible con OpenAI de DashScope: el LLM es qwen3.7-plus, el Embedding es qwen3.7-text-embedding (1024 dimensiones) y la URL base es https://dashscope.aliyuncs.com/compatible-mode/v1. La API Key solo se lee de la variable de entorno local DASHSCOPE_API_KEY; nunca debe escribirse en el repositorio, en settings.yaml ni en los registros.

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

La comprobación de conectividad anterior se ejecuta de forma explícita: solo envía una solicitud corta al LLM y una solicitud de Embedding de un solo texto. El arranque normal y el readiness del Dashboard solo comprueban la configuración local y la base de conocimiento, sin consumir cuota de modelos.

• El directorio predeterminado de ChromaDB es data/db/chroma.

• El directorio del índice BM25 de casos de seguridad es data/db/bm25/code_security_cases.

• La URL base se puede sobrescribir mediante DASHSCOPE_BASE_URL, lo que resulta útil para migrar posteriormente a un dominio exclusivo del espacio de negocio.

Primero ejecute las comprobaciones básicas que no requieren API Key:

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

Importación de casos de seguridad

En el primer uso, o tras cambiar el modelo/dimensiones del Embedding, reconstruya la colección de casos de seguridad con el DashScope Embedding actual:

python scripts\ingest_security_cases.py --rebuild

--rebuild solo reconstruye code_security_cases y su índice BM25 security_; no elimina otras colecciones ni todo el directorio de la base de datos. La importación invoca el servicio de Embedding y consume tokens; si tiene éxito, la salida debe incluir números distintos de cero de casos, Chunks y vectores. La base de conocimiento guarda los identificadores provider, model y dimensions del Embedding actual; si no coinciden con los de una colección ya existente y no vacía, el sistema exigirá una reconstrucción explícita para evitar mezclar vectores antiguos.

Inicio del MCP Server

python -m src.mcp_server.server

Para la configuración de arranque del cliente MCP puede usar:

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

Ejemplo de entrada de la herramienta principal:

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

El servidor también conserva query_knowledge_hub, list_collections y get_document_summary para facilitar la consulta y reutilización de las capacidades RAG originales.

Inicio del Dashboard

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

El Dashboard se abre por defecto en la página «Diagnóstico de vulnerabilidades»; admite pegar errores de Python, fragmentos de código o subir un único archivo .py en UTF-8, y permite descargar informes en Markdown/JSON. El contenido subido solo se analiza en memoria; no se guarda ni se ejecuta. Al hacer clic en «Diagnosticar», el error o el código introducido y el contexto de los casos recuperados se envían a DashScope para generar explicaciones de corrección mejoradas por Qwen; el diagnóstico también consume tokens. No envíe claves, datos personales ni secretos de producción que no deban remitirse a servicios de terceros.

El Embedding puede configurarse más tarde: si no hay Embedding configurado o aún no se ha importado code_security_cases, la página sigue abriéndose con normalidad, pero avisará de que primero debe completar la configuración y ejecutar:

python scripts\ingest_security_cases.py --rebuild

En este estado no se generan resultados de diagnóstico simulados.

Ejemplo de diagnóstico

Entrada:

subprocess.run(user_input, shell=True)

Resultados principales esperados:

• Clasificación: security_vulnerability

• Tipo: Command Injection

• CWE: CWE-78

• Nivel de riesgo: critical

• Evidencia: subprocess-shell

• Corrección: deshabilitar shell=True, usar matrices de argumentos y validación mediante listas permitidas

• Caso similar: PY-SEC-002

Vea el ejemplo completo en docs/examples/codeguard-diagnosis-example.md.

Pruebas y evaluación

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

Un python -m pytest normal solo ejecuta por defecto las pruebas offline y elimina automáticamente las API Keys de DashScope, OpenAI y Azure OpenAI visibles para el proceso de prueba y sus subprocesos. Los casos que invocan servicios de modelos reales se marcan de forma uniforme como llm y deben ejecutarse explícitamente; por ejemplo:

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

Ejecute los comandos anteriores solo si está dispuesto a consumir cuota real de modelos. Los límites mínimos de versión de cliente actualmente compatibles y verificados son chromadb>=1.5.9 y openai>=2.46.0.

La verificación actual cubre el modelo de datos, la validación de casos, el análisis estático, la expansión de consultas, la escritura del doble índice, el diagnóstico determinista, el registro MCP y la salida offline de extremo a extremo. El proyecto conserva los módulos de evaluación originales Ragas/Custom, pero M1 no ofrece cifras de precisión sin validación experimental real.

Limitaciones y direcciones futuras

• M1 solo analiza Python; no ejecuta el código a diagnosticar.

• Los patrones de peligro actuales forman un conjunto de reglas interpretables, no equivalen a un SAST completo.

• La búsqueda Dense real necesita un proveedor de Embedding disponible; sin API Key, la inicialización de MCP y tools/list siguen funcionando, pero la búsqueda híbrida real devolverá un error de configuración legible.

• Sin resultados de búsqueda, devuelve degraded=true, confianza 0.0, e indica que se aporte más contexto.

• Si solo hay similitud con la base de conocimiento pero no hay evidencias estáticas de código coincidentes, no se determina directamente como vulnerabilidad; devuelve degraded=true y confianza 0.0.

• La confianza de M1 usa una jerarquía de evidencias interpretable; no interpreta las puntuaciones brutas heterogéneas de RRF, BM25 o cosine directamente como probabilidades.

• El código original no se inserta directamente en las consultas remotas de Embedding; las API Keys, tokens, contraseñas y credenciales Bearer habituales presentes en las excepciones se enmascaran previamente.

• En el futuro se pueden añadir exploración de archivos/repositorios, normalización de resultados de Bandit/Semgrep, métricas de Golden Test Set y soporte multilingüe.

Referencia para el currículum

Diseñé e implementé de forma independiente una plataforma basada en RAG + MCP para el diagnóstico de defectos de código y vulnerabilidades en Python, construí una base de conocimiento de 30 casos de seguridad estructurados y una cadena de importación con validación JSON/JSONL; adopté recuperación de doble vía Dense Embedding + BM25, fusión RRF y Rerank opcional y, combinando evidencias de patrones peligrosos estáticos, generé CWE, nivel de riesgo, causa raíz y plan de corrección, exponiendo una herramienta de diagnóstico estandarizada mediante MCP; validé la cadena completa de ChromaDB, BM25 y MCP stdio mediante pruebas offline de Unit / Integration / E2E.

En el currículum solo deben escribirse las funcionalidades que uno mismo ha ejecutado, comprende y puede explicar; no deben incluirse porcentajes de mejora no medidos.