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": []
}

Описание назначения файлов (пофайлово)

Корневые и проектные файлы

Файл	Назначение
.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)