Bug Hunter — Аудит кода с использованием состязательных методов для агентов ИИ

Bug Hunter — это скилл для аудита кода с использованием состязательных методов, который работает как многоагентный pipeline: Hunter находит баги, Skeptic оспаривает каждое утверждение, а Referee выносит финальный вердикт на основе доказательств. По умолчанию инструмент работает в режиме scan-only и не редактирует файлы без явного разрешения.

Почему adversarial подход

Типичные AI-инструменты для code review выдают длинный список предположительных проблем, а разработчику остаётся выяснять, какие из них реальны. Bug Hunter каждое нахождение Treat как claim, который должен выдержать противодействие: Hunter объясняет конкретный runtime-сбой и триггер, Skeptic пытается опровергнуть утверждение, проверяя защитные механизмы, а Referee сопоставляет обе стороны и выносит вердикт — REAL_BUG, NOT_A_BUG или MANUAL_REVIEW.

Такое разделение снижает количество false positive и делает результаты аудиторски прозрачными. Результаты, которые не удалось однозначно установить, помечаются как MANUAL_REVIEW или unreviewed — они не маскируются под чистые.

Архитектура пайплайна

Полный цикл выглядит так:

risk triage → adaptive plan → architecture recon → retrieval planning
→ Hunter findings → documentation checks → Skeptic challenges
→ Referee verdicts → hybrid verification → report
→ (опционально) fix plan → fixes → verification

Каждый этап генерирует свой JSON-артефакт: triage.json, hunter-findings.json, skeptic.json, referee.json, scan-report.json и другие. Все контракты схематизированы — битый или отсутствующий артефакт считается провалом фазы, а не признаком чистого скана.

Три основные роли

Skeptic имеет 14 жёстких исключений для повторяющихся не-багов: нахождения только в тестах, документационные находки, отсутствие аудит-логирования, rate-limiting suggestions, ReDoS без демонстрации медленного payload и другие. Referee при ≤20 находках перечитывает каждую независимо; при большем числе — проверяет все Critical и топ-15.

Возможности анализа

Детерминированная risk triage

Перед тем как модель читает исходники, scripts/triage.cjs инвентаризует цель, фильтрует неисходный код, оценивает риск файлов и формирует порядок сканирования. Это детерминированный проход без затрат токенов модели.

Runtime behavioral bug detection

Hunter ищет ошибки, влияющие на реальное поведение: неправильные условия, off-by-one, injection, authorization bypass, path traversal, SSRF, XSS, race conditions, swallowed exceptions, ошибки кодирования и serialization, несоответствие API-контрактов между caller и callee, resource leaks и отсутствие валидации на trust boundaries.

Cross-file и boundary analysis

Многие production-баги живут не в одной функции. Bug Hunter проверяет место, где предположения меняются: caller считает, что callee валидировал input, но это не так; промежуточный слой проглатывает ошибку; два модуля работают с shared state без координации.

Документационная верификация

AI-ревью часто ломается, когда он угадывает поведение библиотеки. Bug Hunter может обратиться к Context Hub или Context7 для проверки version-sensitive claim. Lookups привязаны к конкретному claim, а не к broad search по всем import'ам.

Безопасность

STRIDE, CWE, CVSS

Каждая security-находка классифицируется по STRIDE (Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege), CWE и CVSS 3.1. Дополнительно фиксируются reachability и exploitability.

Зависимости и CVE

Флаг --deps добавляет lockfile-aware dependency scanning для JavaScript/TypeScript: npm audit, pnpm audit, yarn npm audit, bun audit. Поддерживаются package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock. Для Python, Go, и Rust парсеры ещё не реализованы — результат scanner-unsupported.

Threat modeling

Команда --threat-model генерирует .bug-hunter/threat-model.md с STRIDE-картой: entry points, trust boundaries, sensitive data flows, assets и угрозы.

Установка и использование

Установка из GitHub source:

npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent codex

Поддерживаемые агенты: Claude Code (claude-code), Codex (codex), Cursor (cursor), GitHub Copilot (copilot), Kiro (kiro), Windsurf (windsurf), OpenCode (opencode), Factory Droid CLI (droid), другие file-based агенты (agents).

Быстрый старт — отправьте в репозитории:

Use the bug-hunter skill to scan this repository. Do not edit files.
Return the final report and call out every item that needs manual review.

Рекомендованный первый запуск — scan-only и single-pass. Полная coverage через --loop.

Основные сценарии

Безопасность по умолчанию

• Без флагов — scan-only и single-pass.
• --loop меняет поведение coverage, но не даёт право редактирования.
• --fix разрешает reviewed edits после прохождения Referee/remediation gating.
• --approve запрашивает reviewed/default permission mode хост-агента.
• --autonomous разрешает unattended eligible edits.
• --auto-commit отдельно даёт commit permission — проверяйте harvested commit paths перед merge.

По умолчанию bundled regression fixture показывает precision 1.00, recall 1.00, F1 1.00 с нулевым количеством false positive. Это метрики bundled harness и fixture, а не независимый benchmark для каждого репозитория.

Поддерживаемые языки

Анализ исходников работает с JavaScript, TypeScript, Python, Go, Rust, Java, Kotlin, Ruby, PHP, C#, Swift, Scala, C и C++ через agent reasoning и repository evidence. Dependency audit парсинг поддерживает только JavaScript и TypeScript.