renweimeng/vlun-agent-xVulnAgent-X: Многоуровневый агентный фреймворк для обнаружения уязвимостей на уровне репозитория
VulnAgent-X — это многоагентный прототип обнаружения уязвимостей/дефектов, ориентированный на воспроизведение результатов научных исследований. На вход подаётся локальный репозиторий или diff, на выходе — структурированные findings, цепочки доказательств, результаты локализации, уровень уверенности и журналы экспериментов.
repo path или unified diffscreening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusionissue_typelocation(file + line range)evidence_summaryconfidenceseverityoptional_cwefix_hintevidence_chaincounter_evidencescreening: быстрая проверка подозрительных областей (правила + сигналы метаданных)context_expansion: получение «минимально достаточного контекста» (извлечение окон на основе подозрительных локаций)scheduler: стратегия эскалации на основе уровня уверенности и риска (early_exit / expert_review / verification)router_agent: выбор экспертного Agent для каждой подозрительной областиsemantic/security/logic: формирование структурированных утверждений и доказательств с разных точек зренияsceptic_agent: генерация контраргументов и штрафных сигналовverification: опциональная динамическая проверка (в настоящее время — безопасная заглушка)evidence_fusion: объединение и вывод итоговых findingsТребования: Python 3.11+ (в настоящее время также работает на более новых версиях)
cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
Анализ всего репозитория:
.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
Запуск сервиса:
.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"}'
docker compose -f docker/docker-compose.yml up --build
.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": []
}
| Файл | Назначение |
|---|---|
.env.example | Шаблон переменных окружения (необязательные настройки, например уровень логирования). |
pyproject.toml | Сборка проекта, зависимости, точки входа скриптов, конфигурация pytest/ruff/mypy. |
README.md | Основной README (с кнопкой переключения языка, по умолчанию — китайский). |
README.zh.md | Полная документация на китайском языке. |
README.en.md | Полная документация на английском языке. |
docker/Dockerfile | Файл сборки контейнерного образа для API-сервиса. |
docker/docker-compose.yml | Локальный запуск контейнерного сервиса одной командой. |
rules/semgrep/vulnagentx-rules.yml | Встроенный набор правил Semgrep (инъекция команд / SQL-инъекция / десериализация / небезопасный C API). |
scripts/run_experiment.py | Скрипт пакетного запуска экспериментов на наборах данных, выводящий прогнозы в JSONL. |
scripts/evaluate.py | Читает результаты экспериментов и вычисляет метрики обнаружения/локализации/эффективности. |
scripts/run_ablation.py | Скрипт абляционных экспериментов (no_semgrep/no_treesitter/no_sceptic/no_verification). |
src/vulnagentx)| Файл | Назначение |
|---|---|
src/vulnagentx/__init__.py | Определение версии пакета и экспортируемых объектов. |
src/vulnagentx/app/__init__.py | Инициализация подпакета app. |
src/vulnagentx/app/cli.py | Точка входа CLI (vulnagentx analyze). |
src/vulnagentx/app/api.py | Точка входа FastAPI-сервиса (/health, /analyze). |
src/vulnagentx/app/schemas.py | Pydantic-схемы запросов/ответов API. |
src/vulnagentx/core/__init__.py | Инициализация подпакета core. |
src/vulnagentx/core/state.py | Модель глобального состояния: области, доказательства, выводы Agent, Finding, журналы, метрики. |
src/vulnagentx/core/screening.py | Быстрая проверка первого этапа, извлечение подозрительных областей. |
src/vulnagentx/core/context_expansion.py | Расширение контекста: извлечение минимального окна кода на основе локации. |
src/vulnagentx/core/scheduler.py | Стратегия эскалации с учётом уверенности (early_exit/expert_review/verification). |
src/vulnagentx/core/verification.py | Опциональный модуль динамической проверки (в настоящее время — безопасная заглушка). |
src/vulnagentx/core/evidence_fusion.py | Объединение доказательств от нескольких Agent, вывод итоговых findings. |
src/vulnagentx/core/workflow.py | Точка входа сквозной оркестрации VulnAgentWorkflow. |
src/vulnagentx/agents/__init__.py | Агрегированный экспорт Agent. |
src/vulnagentx/agents/base.py | Абстрактный базовый класс Agent и инструменты получения контекста. |
src/vulnagentx/agents/router_agent.py | Маршрутизирующий Agent: назначает экспертного Agent для каждой подозрительной области. |
tests)| Файл | Назначение |
|---|---|
tests/test_agents.py | Модульные тесты: структурированный вывод и логика контраргументов каждого Agent. |
tests/test_end_to_end.py | Сквозной тест: основной процесс от входного репозитория до итоговых findings. |
tests/test_research_modules.py | Тесты новых модулей: построение графа Tree-sitter, цепочка выполнения verification, метрики оценки. |
OpenAI + локальный Ollama + автоматическое переключение фабрикойsrc/vulnagentx/agents/semantic_agent.py| Семантический агент: риски семантического уровня (например, нулевые указатели, десериализация, проглатывание исключений). |
src/vulnagentx/agents/security_agent.py | Агент безопасности: правила уязвимостей (инъекция команд, SQL-инъекция, выход за границы и т.д.). |
src/vulnagentx/agents/logic_bug_agent.py | Агент логики: дефекты бизнес-логики/потока управления (границы, деление на ноль, отсутствие авторизации и т.д.). |
src/vulnagentx/agents/sceptic_agent.py | Агент-скептик: генерирует контраргументы, штрафы за конфликты, снижает уверенность. |
src/vulnagentx/adapters/__init__.py | Инициализация подпакета адаптеров. |
src/vulnagentx/adapters/sandbox_adapter.py | Исполнитель в ограниченной песочнице дочернего процесса (тайм-аут, без shell) для verification. |
src/vulnagentx/adapters/semgrep_adapter.py | Адаптер Semgrep CLI (включается опционально). |
src/vulnagentx/adapters/treesitter_adapter.py | Реальный адаптер Tree-sitter (при доступности парсит AST и связи вызовов/импортов, при недоступности — деградация). |
src/vulnagentx/adapters/llm/__init__.py | Агрегированный экспорт LLM-адаптеров. |
src/vulnagentx/adapters/llm/base.py | Интерфейс протокола LLM-адаптера. |
src/vulnagentx/adapters/llm/mock_adapter.py | Mock LLM для офлайн-тестирования. |
src/vulnagentx/adapters/llm/openai_adapter.py | Адаптер официального OpenAI SDK. |
src/vulnagentx/adapters/llm/local_adapter.py | Адаптер локальных моделей (Ollama HTTP API). |
src/vulnagentx/adapters/llm/factory.py | Автоматический выбор LLM-адаптера по конфигурации с откатом на Mock. |
src/vulnagentx/retrieval/repo_graph.py | Индекс графа кода и поиск соседних файлов (на основе пересечения символов AST). |
src/vulnagentx/datasets/base.py | Общая структура образцов наборов данных и чтение JSONL/CSV. |
src/vulnagentx/datasets/devign.py | Точка загрузки данных Devign. |
src/vulnagentx/datasets/bigvul.py | Точка загрузки данных Big-Vul. |
src/vulnagentx/datasets/primevul.py | Точка загрузки данных PrimeVul. |
src/vulnagentx/datasets/jit.py | Точка загрузки данных JIT. |
src/vulnagentx/eval/detection_metrics.py | Метрики обнаружения (Precision/Recall/F1/Accuracy). |
src/vulnagentx/eval/localization_metrics.py | Метрики локализации (Top-1/Top-3/MRR). |
src/vulnagentx/eval/efficiency_metrics.py | Метрики эффективности (среднее время выполнения, P95, среднее число findings). |
src/vulnagentx/eval/ablations.py | Логика выполнения абляционных экспериментов. |
src/vulnagentx/utils/config.py | Центр конфигурации рабочего процесса (флаги env/CLI/API). |