Анализ гипотез безопасности

При проверке безопасности инженер начинает с вопроса: может ли недоверенный ввод попасть в опасную операцию, можно ли обойти проверку прав, относится ли известная слабость к этому коду? Чтобы ответить, нужно найти входные точки, связи и условия выполнения. Один подозрительный фрагмент ещё не объясняет, как проблема проявится в приложении.

CodeGraph превращает такие предположения в гипотезы и проверяет их по графу свойств кода (Code Property Graph, CPG). Гипотеза задаёт предмет проверки, а граф помогает исследовать структуру программы и доступные связи. Процесс использует базу знаний и зарегистрированные провайдеры шаблонов. Каждая проверенная гипотеза получает результат: подтверждена, отклонена или неопределённа.

Команда получает материал для исследования: что проверяли, какие запросы выполнены, какие предположения подтвердились и где доказательств недостаточно. Это помогает сосредоточить ручную проверку на конкретных местах кода. Инженер использует найденные позиции и доказательства запроса для проверки условий эксплуатации и подготовки теста безопасности.

От предположения к проверке

Рассмотрим учебный вопрос: может ли значение из HTTP-запроса повлиять на SQL-запрос? Специалист сначала выбирает соответствующие гипотезы и проверяемую ревизию. Затем процесс выполняет запросы к CPG в заданной области. Инженер сопоставляет найденные места с исходниками и проверяет, есть ли параметризация, преобразование данных или другое условие, меняющее риск.

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

Когда этот анализ полезен

• При ревью чувствительного изменения: исследовать выбранные гипотезы для нужной ревизии.
• При разборе известной слабости: сузить область по поддерживаемой категории или CVE.
• При подготовке проверки на исполнении: экспортировать поддерживаемые fuzz- или DAST-цели.
• При передаче результата AppSec: сохранить отчёт, область, исключения и исходные позиции.

Связь гипотез с графом помогает перейти от общего предупреждения к проверяемому вопросу о коде. Для выбора проверок по языку и фреймворку используйте карту анализа. Она помогает выбрать соседнюю проверку: гипотезы исследуют слабости кода, модель угроз — границы системы, а SCA/SBOM — состав и риски зависимостей.

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

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

Параметры команд описаны в справочнике CLI, а подключение агентской сессии — в руководстве оператора MCP. Через MCP вызывайте codegraph_security_hypothesis_run. Для автоматизации используйте --help выбранной команды или схему MCP-инструмента в установленной версии.

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

Установите CLI по руководству. Команды ниже предназначены для Bash в корне репозитория CodeGraph. Нужен доступный сервис GoCPG: текущий исполнитель отправляет запросы через gRPC. Значение --db выбирает CPG и не включает прямое чтение DuckDB.

export CODEGRAPH_ALLOW_LOCAL_PYTHON_CLI=1
python -m src.cli hypothesis run --db "<cpg-path>" --human-language ru

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

python -m src.cli hypothesis run \
  --db "<cpg-path>" \
  --language C \
  --max 50 \
  --min-priority 0.5 \
  --format json \
  --output "hypothesis-report.json" \
  --human-language ru

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

Параметры обычного run определяют предмет проверки и размер результата:

Для сравнения двух ревизий сохраните одинаковые фильтры и порог. Тогда изменение числа подтверждённых гипотез можно сопоставить с изменением кода, показанным ниже.

Проверьте изменение на учебном примере

В этом примере функция получает текст из переменной окружения через getenv и передаёт его в system. Гипотеза командной инъекции проверяет сочетание источника ввода и выполнения команд в этой функции. Затем мы заменим выполнение команды выводом текста через puts, обновим граф и сравним результаты.

Выполняйте команды в Bash из корня CodeGraph. В GOCPG_BIN укажите абсолютный путь к установленному исполняемому файлу GoCPG вместо <path-to-gocpg>; на Windows это файл gocpg.exe. Нужен доступный GoCPG gRPC-сервис, как для предыдущих команд. Вместо <new-demo-dir> укажите новый каталог для исходников, графов и отчётов примера. Учебный исходник разбирайте анализатором; компилировать и запускать его для проверки гипотезы не требуется.

Создайте исходник, постройте CPG и сохраните отчёт:

GOCPG_BIN="<path-to-gocpg>"
DEMO_DIR="<new-demo-dir>"
mkdir -p "$DEMO_DIR/before"
cat > "$DEMO_DIR/before/example.c" <<'C'
#include <stdio.h>
#include <stdlib.h>

void run_action(void) {
    char *command = getenv("CODEGRAPH_DEMO_COMMAND");
    if (command != NULL) {
        system(command);
    }
}
C

"$GOCPG_BIN" parse --input "$DEMO_DIR/before" \
  --output "$DEMO_DIR/before.duckdb" --lang c
export CODEGRAPH_ALLOW_LOCAL_PYTHON_CLI=1
python -m src.cli hypothesis run \
  --db "$DEMO_DIR/before.duckdb" \
  --language C --category command_injection \
  --max 50 --min-priority 0.5 --format json \
  --output "$DEMO_DIR/before.json" --human-language ru

Откройте <new-demo-dir>/before.json. Для этого исходника ожидается одна выполненная проверка (executed_queries: 1) и одна подтверждённая гипотеза (confirmed_hypotheses: 1) категории command_injection. В её cwe_ids входит CWE-78. В исходнике проследите передачу command от getenv в system: именно этот участок команда получает для ревью.

Замените system(command) на puts(command), сохранив новую версию отдельно. Перестройте CPG и повторите ту же проверку:

mkdir -p "$DEMO_DIR/after"
sed 's/system(command);/puts(command);/' \
  "$DEMO_DIR/before/example.c" > "$DEMO_DIR/after/example.c"
"$GOCPG_BIN" parse --input "$DEMO_DIR/after" \
  --output "$DEMO_DIR/after.duckdb" --lang c
python -m src.cli hypothesis run \
  --db "$DEMO_DIR/after.duckdb" \
  --language C --category command_injection \
  --max 50 --min-priority 0.5 --format json \
  --output "$DEMO_DIR/after.json" --human-language ru

В <new-demo-dir>/after.json ожидаются executed_queries: 1, confirmed_hypotheses: 0 и rejected_hypotheses: 1. Число проверок сохранилось, а гипотеза командной инъекции стала отклонённой: новая версия выводит значение как текст через puts. Два исходника, два графа и два отчёта позволяют показать ревьюеру само изменение и результат повторной проверки.

Ограничение области проверки

Обычный run применяет повторяемый --category и список --cve через запятую. Аргумент run --cwe принимается парсером, но текущий обработчик его не использует. В export фильтр --cwe отбирает уже проверенные гипотезы для экспорта; он не ограничивает запросы.

--incremental --base-ref "<git-ref>" сравнивает указанную ревизию с HEAD в текущем рабочем каталоге. Незакоммиченные изменения в сравнение не входят. Этот режим игнорирует --category, --cwe, --cve и все аргументы исключения. Если список изменений пуст, выполняется полная проверка. Ошибка получения Git diff также может привести к пустому списку. Перед таким запуском отдельно проверьте базовую ревизию и список изменённых файлов.

В обычном run и в export применяйте --exclude-fixtures, --exclude-mocks, --exclude-generated или повторяемый --exclude-category. Сохраняйте исключения вместе с отчётом: они задают область проверки.

Перед анализом обновите CPG для проверяемой ревизии репозитория и передайте его путь в --db.

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

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

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

Провайдер объединяет шаблоны анализа для языка или фреймворка, источники данных и опасные операции. Команда providers показывает его состав: Patterns — количество шаблонов, Sources — источников данных, Sinks — опасных операций. По этому списку выберите провайдера для своего проекта. Команда list-cwes показывает категории слабостей в базе знаний и помогает выбрать предмет проверки.

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

python -m src.cli hypothesis export \
  --db "<cpg-path>" \
  --format generic \
  --output "fuzz_targets" \
  --human-language ru

Команда экспорта запускает проверку, выбирает гипотезы по приоритету и заданному фильтру CWE, затем записывает targets.json и файлы отдельных целей. Манифест содержит входную и опасную функции, подсказки для входных данных, идентификаторы CWE, приоритет и текст гипотезы. Позиции в исходном коде берутся из собранных доказательств; имена функций также могут браться из шаблонов источников и опасных операций гипотезы.

Формат generic создаёт JSON-описание каждой цели. Форматы afl и libfuzzer создают начальные входные данные и заготовки тестовой обвязки. Для гипотез о поддерживаемых веб-слабостях также создаются шаблоны Nuclei. Подключите обвязку к точке входа приложения, настройте сборку и входные данные, затем запустите её в песочнице. По отчёту проверки выберите гипотезы для первоочередного исследования.

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

Используйте подключение AppSec для чтения с профилем codex:role:codegraph_appsec:read, затем выберите codegraph_security_hypothesis_run в клиенте. Инструмент принимает action со значением run, list_cwes или list_providers, а также поддерживаемые поля языка, объёма, приоритета, категории и языка отчёта.

Чтобы получить имена провайдеров и поддерживаемые ими языки, передайте инструменту этот объект:

{"action": "list_providers"}

При run MCP выбирает CPG из контекста авторизованного проекта в работающем сервисе. Перед анализом выберите проект в клиенте.

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

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

Текущий расчёт метрик считает каждую подтверждённую гипотезу истинным срабатыванием (true_positives). Пропущенные явно заданные CVE увеличивают false_negatives; false_positives сохраняет начальное значение 0. Значения precision, recall и f1_score рассчитываются по этим счётчикам и описывают результаты текущего запуска. При разборе находки откройте исходные позиции, доказательства запроса, категорию и привязку CWE. Чтобы оценить возможность эксплуатации, проследите путь данных и условия выполнения, затем воспроизведите поведение подходящим тестом безопасности.

Работа с находками

Языковые шаблоны задают проверяемые конструкции, а CPG предоставляет связи между элементами кода. Инженер использует доказательства гипотезы, чтобы выбрать участок для проверки и подготовить тест. После исправления обновите граф и повторите проверку той же гипотезы.

Сгенерированные fuzz-цели запускайте в песочнице после просмотра кода и настроек сборки. Храните отчёты в принятом командой хранилище с доступом для участников проверки: они содержат структуру репозитория и сведения о найденных слабостях.

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