VulnAgent-X 연구 프로토타입

VulnAgent-X는 논문 재현을 위한 멀티 에이전트 취약점/결함 탐지 프로토타입입니다. 로컬 저장소 또는 diff를 입력하면 구조화된 findings, 증거 체인, 위치 결과, 신뢰도 및 실험 로그를 출력합니다.

핵심 기능

• 입력 형식: repo path 또는 unified diff
• 워크플로우: screening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusion
• 출력 필드:
  • issue_type
  • location(file + line range)
  • evidence_summary
  • confidence
  • severity
  • optional_cwe
  • fix_hint
  • evidence_chain
  • counter_evidence
• 인터페이스: CLI + FastAPI
• 재현 가능한 실험: pytest / mypy / ruff + Docker 실행 지원

워크플로우 개요

1. screening: 의심 영역 빠른 선별 (규칙 + 메타데이터 신호)
2. context_expansion: "최소 충분 컨텍스트" 가져오기 (의심 위치 기준 창 추출)
3. scheduler: 신뢰도와 위험에 따른 에스컬레이션 전략 (early_exit / expert_review / verification)
4. router_agent: 각 의심 영역에 전문가 Agent 선택
5. semantic/security/logic: 서로 다른 관점에서 구조화된 주장과 증거 제시
6. sceptic_agent: 반증과 페널티 신호 생성
7. verification: 선택적 동적 검증 (현재는 안전한 플레이스홀더 구현)
8. evidence_fusion: 통합 융합 후 최종 findings 출력

설치 및 실행 방법

1) 환경 준비

요구 사항: Python 3.11+ (현재는 더 높은 버전에서도 실행 가능)

cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

2) CLI 사용

전체 저장소 분석:

.venv/bin/vulnagentx analyze --repo /path/to/repo --output json

diff 파일 분석:

.venv/bin/vulnagentx analyze --diff-file /path/to/patch.diff --output json

요약 출력:

.venv/bin/vulnagentx analyze --repo /path/to/repo --output summary

3) API 사용

서비스 시작:

.venv/bin/uvicorn vulnagentx.app.api:app --reload

상태 확인:

curl http://127.0.0.1:8000/health

분석 요청:

curl -X POST http://127.0.0.1:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"repo_path":"/path/to/repo"}'

4) Docker 실행

docker compose -f docker/docker-compose.yml up --build

5) 품질 검사 및 테스트

.venv/bin/ruff check src tests
.venv/bin/mypy src
.venv/bin/pytest

출력 예시

{
  "run_id": "...",
  "findings": [
    {
      "issue_type": "command_injection",
      "location": {"file_path": "app.py", "start_line": 42, "end_line": 42},
      "evidence_summary": "Command execution surface detected...",
      "confidence": 0.87,
      "severity": "critical",
      "optional_cwe": "CWE-78",
      "fix_hint": "Avoid shell command composition...",
      "source_agents": ["security_agent", "semantic_agent"],
      "evidence_chain": [],
      "counter_evidence": []
    }
  ],
  "metrics": {
    "runtime_seconds": 0.07
  },
  "logs": []
}

파일 용도 설명 (파일별)

루트 디렉터리 및 프로젝트 파일

핵심 소스 코드 (src/vulnagentx)

테스트 파일 (tests)

이번에 구현된 향상 모듈

• 실제 LLM 어댑터: OpenAI + 로컬 Ollama + 자동 팩토리 전환
• 실제 Tree-sitter AST 및 코드 그래프: 함수/import/호출 관계 파싱, 이웃 파일 컨텍스트 확장 지원
• 실제 Semgrep 규칙 세트: 내장 규칙 파일 및 screening 단계 연동
• verification 샌드박스 실행 체인: 작업 계획, 제한된 실행, 타임아웃 제어, 구조화된 결과 기록
• 데이터셋 평가 및 소거: 데이터 로더, 지표 모듈, 실험 및 소거 스크립트