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 검증을 거친 30개의 Python 결함, 취약점, 구성, 의존성 사례 내장.

• 하이브리드 검색: 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을 지원합니다. 가져오기时 각 사례는 하나의 안정적인 Chunk를 생성하며, case_id는 ChromaDB와 BM25 문서 식별자로 동시에 사용되어 두 경로의 결과가 어긋나지 않도록 합니다.

M1의 30개 사례 구성:

• 일반 코드 결함 8건

• 보안 취약점 17건

• 구성 리스크 3건

• 의존성 리스크 2건

PDF 및 JSON 처리 방식

CodeGuard의 기본 지식 베이스는 JSON/JSONL을 우선합니다. CWE, 위험 등급 및 수정 제안은 안정적인 구조화 필드가 필요하기 때문입니다. 기존 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 서비스를 호출하고 토큰을 소비합니다. 성공 출력에는 0이 아닌 사례, 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 강화 수정 설명을 생성합니다. 진단도 토큰을 소비합니다. 제3자 서비스로 전송해서는 안 되는 키, 개인 데이터 또는 운영 기밀을 제출하지 마십시오.

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 등록 및 오프라인 엔드투엔드 출력입니다. 프로젝트는 기존 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 전체 파이프라인을 검증했습니다.

이력서에는 실제로 실행하고 이해하며 설명할 수 있는 기능만 작성하고, 측정되지 않은 개선 비율을 기재하지 마십시오.