Анализ гипотез безопасности — Документация CodeGraph

Процесс формирует гипотезы уязвимостей по доступной базе знаний, проверяет их по Code Property Graph и отмечает как подтверждённые, отклонённые или неопределённые. Результаты гипотез используются для анализа уязвимости и безопасности кода.

Выберите интерфейс

CLI подходит для локального анализа явно указанного CPG, подробных фильтров, инкрементальных запусков, файлов отчёта и экспорта fuzz-целей. MCP удобен, когда у авторизованной агентской сессии уже есть контекст проекта и нужен типизированный результат.

Текущие границы реализации:

src/cli/analysis_commands/hypothesis_commands.py — регистрация и аргументы CLI;
src/mcp/tools/query_suite/hypothesis.py — инструмент codegraph_security_hypothesis_run.

Перед автоматизацией сверяйтесь с --help или live-схемой MCP установленной ревизии.

Запуск через CLI

Для анализа нужен явный путь к CPG в DuckDB:

python -m src.cli hypothesis run --db path/to/project.duckdb

Если важна воспроизводимость, задайте язык, объём, порог и формат явно:

python -m src.cli hypothesis run \
  --db path/to/project.duckdb \
  --language C \
  --max 50 \
  --min-priority 0.5 \
  --format json \
  --output hypothesis-report.json \
  --human-language ru

JSON-отчёт содержит идентификатор пакета, счётчики выполнения и результатов, время и ограниченный набор полей гипотез. Сохраняйте рядом проиндексированную Git-ревизию и аргументы команды.

Ограничение scope

Для фокусировки используйте повторяемый --category, список --cwe через запятую или такой же список --cve. Для анализа только изменённых файлов добавьте --incremental --base-ref <git-ref>.

Если соответствующие входные данные не входят в оценку, применяйте --exclude-fixtures, --exclude-mocks, --exclude-generated или повторяемый --exclude-category. Исключения меняют смысл пустого результата, поэтому фиксируйте их в доказательствах, а не прячьте в wrapper script.

Выбранный CPG должен соответствовать проверяемой ревизии репозитория. Команда не обновляет старый граф автоматически.

Проверка покрытия и экспорт целей

Перед выбором фильтров посмотрите доступные элементы базы знаний и зарегистрированные провайдеры:

python -m src.cli hypothesis list-cwes --format json
python -m src.cli hypothesis providers

Экспортируйте поддерживаемые fuzz- или DAST-цели с явными БД и каталогом результата:

python -m src.cli hypothesis export \
  --db path/to/project.duckdb \
  --format generic \
  --output fuzz_targets

Доступны форматы afl, libfuzzer и generic. Перед запуском проверьте сгенерированные цели, настройки сборки, ограничения входа и безопасность выполнения.

Запуск через MCP

Найдите codegraph_security_hypothesis_run в активном клиенте. Инструмент принимает action со значением run, list_cwes или list_providers, а также поддерживаемые поля языка, объёма, приоритета, категории и языка отчёта.

MCP получает CPG из авторизованного runtime-контекста проекта. Не передавайте сырой db_path через agent-facing вызов. Доступность инструмента для текущего клиента определяется активным профилем и подтверждается работающим вызовом.

Настройка и правила типизированных вызовов описаны в руководстве оператора MCP.

Интерпретация результатов

«Подтверждена» означает, что процесс собрал доказательства по текущим правилам проверки. «Отклонена» — что проверенная гипотеза им не соответствует. «Неопределённа» — что доступного графа или доказательств недостаточно для решения.

Оценки и агрегированные метрики характеризуют конкретный запуск и размеченный набор, а не общую точность продукта. Перед triage проверьте исходные позиции, доказательства запроса, категорию, привязку CWE, исключения и свежесть графа. Находки с высоким влиянием подтверждайте вручную и подходящими security-тестами.

Ограничения и безопасное использование

Языковые паттерны и покрытие CPG определяют, какие слабости можно проверить.
Отсутствие гипотезы означает отсутствие совпадения в доступной области; слабость проверяется отдельным анализом.
Сгенерированные fuzz-цели исполняемы и требуют обычной песочницы и ревью.
Отчёты могут раскрывать структуру репозитория и чувствительные находки; контролируйте хранение.
Для приёмки релиза всё равно нужны заданные задачей доказательства AppSec, QA, трассировки и рантайма.

Для системных границ доверия используйте моделирование угроз, а для рисков зависимостей — SCA/SBOM: эти процессы отвечают на разные вопросы.