Введение

Detect — статический анализатор исходного кода. Он разбирает код, не запуская программу, и ищет места, где данные из внешнего источника доходят до опасной операции без проверки.

Собственного веб-интерфейса управления у Detect нет. Работа идёт из командной строки, через программный интерфейс по сети или со страницы сервиса, которую поднимает администратор.

Установку, настройку и доступ к серверу модели описывает руководство администратора.

Основные возможности

• Проверка проекта. Каталог с кодом, репозиторий по ссылке или архив .zip; отчёт по найденным уязвимостям на русском языке.
• Прослеживание путей данных между файлами. Источник в одном файле и опасная операция в другом связываются в одну цепочку.
• Режимы находок. Результаты разделяются по степени определённости, чтобы было проще выбрать порядок проверки.
• Несколько проектов. Каждый проект проверяется своим запуском, проход по каталогам задаётся циклом.
• Повторный анализ по изменениям. Поддерживается проверка изменений после предыдущего анализа.
• Сравнение двух проверок. Видно, что появилось, что исправлено и что сместилось по строкам.
• Отчёты для смежных систем. SARIF 2.1.0 для системы сборки и отдельный отчёт для сервиса триажа Accent.
• Маскирование секретов. В некоторых полях отчёта обнаруженные секреты заменяются специальной меткой. Перед передачей результатов проверьте их на наличие конфиденциальной информации.

Подготовка к работе

Команды выполняются из каталога Detect, в окружении Python, которое готовит установщик: source .venv/bin/activate. Если Detect развёрнут сервисом, адрес сервера сообщает администратор. По умолчанию сервис слушает порт 8001.

Проверьте, что сервис готов принимать проверки:

curl -sS "http://127.0.0.1:8001/ready"

Неготовность возвращает код 503 с разбором того, чего не хватает. Страница с описанием интерфейса и формами — http://127.0.0.1:8001/docs.

Для работы с программным интерфейсом v1 используйте токен, выданный администратором. Другие способы доступа разрешены только в контролируемом контуре по правилам организации.

Описание операций

Первая проверка

Каталог на диске

python ai_ast.py --code-dir "/srv/projects/checkout" --job-id "checkout-2026-10-07"

Репозиторий по ссылке

python ai_ast.py --code-dir "https://git.example.com/team/checkout.git" --job-id "checkout-git"

Несколько проектов. Каждый проект проверяется своим запуском. Распакуйте архивы и пройдите по ним циклом:

for dir in /srv/projects/*/; do
  name=$(basename "$dir")
  python ai_ast.py --code-dir "$dir" --job-id "$name"
done

Рабочий каталог каждого проекта окажется в runtime_runs/<имя>/.

Без языковой модели. Программа выполняет анализ без обращения к серверу модели. Такой режим удобно использовать для сопоставимых повторных проверок.

python ai_ast.py --code-dir "/srv/projects/checkout" --job-id "checkout-fast" --analysis-profile no_llm --no-use-llm

Нужны оба параметра. Один --analysis-profile no_llm модель не выключает.

Контрольный запуск с моделью. Для более сопоставимых результатов можно использовать параметр --workers 1. Он может увеличить время проверки, но не гарантирует полной идентичности ответов модели.

Убедиться, что результат целый. Согласованность файлов результата проверяется так:

python -c "import json;d=json.load(open('runtime_runs/checkout-2026-10-07/verdicts_sast_artifact_consistency.json',encoding='utf-8'));print(d['status'],d['errors'])"

Ответ pass и пустой список означают, что файлы результата сходятся между собой. Отсутствие файла означает, что проверка не дошла до конца.

Компактная выдача

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

python ai_ast.py --code-dir "/srv/projects/checkout" --job-id "checkout" --artifact-mode compact

В каталоге results/checkout/ окажется три файла.

Файл	Содержимое
findings.json	Находки на русском языке, 16 полей на каждую
verdicts.csv	Строка на каждый файл проекта
results.sarif	Стандартный отчёт для систем сборки и сред разработки

Рабочие материалы при этом остаются в runtime_runs/<имя>/, они нужны повторному анализу по изменениям. Если их удалить, следующая проверка будет полной. Там же лежит triage-input.sarif, когда он создавался: в компактную выдачу он не входит.

Каталог выдачи меняется параметром --compact-output-dir.

Чтение отчёта

Какой файл открыть

Файл	Кому
findings.json или verdicts_sast_ru.json	Человеку: находки на русском языке
verdicts.csv	Для таблиц и скриптов
results.sarif	Для систем сборки и сред разработки
triage-input.sarif	Для Accent, когда решение принимает он
report.sarif	Итоговый отчёт для Accent через интерфейс v1
verdicts_sast.json	При спорах: полная доказательная база

Режим находки говорит, с чего начинать

Режим	Что значит	Что делать
confirmed	Найдены достаточные признаки уязвимости	Проверить и устранить проблему
manual_review	Признаки есть, доказательство неполное	Прочитать код
advisory	Справочное наблюдение	Учесть при доработке

Чем различаются severity, impact, likelihood и confidence

severity говорит, насколько опасен вид уязвимости вообще. impact и likelihood относятся к конкретной находке в конкретном месте. confidence показывает, насколько анализатор уверен в самой находке. Разбор начинайте с находок, где высок confidence: высокая критичность вида сама по себе не говорит, что находка верна.

Разбор находки

Шаг 1. Открыть место

Файл берётся из поля path, строка из start_line. Сверьте с code_snippet.

Шаг 2. Понять утверждение

short_description называет проблему, cwes даёт точный вид. Описание вида по номеру есть на cwe.mitre.org.

Шаг 3. Проверить, доходят ли данные извне

Уточните, может ли внешний ввод влиять на отмеченную операцию и действительно ли соответствующее место выполняется. Автоматический анализ может не учитывать некоторые особенности построения и использования программы, поэтому при сомнениях нужна проверка специалистом.

Шаг 4. Проверить защиту

Нестандартную защиту, свою функцию проверки или декоратор из внутренней библиотеки анализатор может не узнать.

Шаг 5. Решить

Вывод	Действие
Уязвимость настоящая	Исправить
Защита есть, анализатор её не узнал	Ложное срабатывание
Место недостижимо извне	Ложное срабатывание
Решить не удаётся	Передать специалисту вместе с verdicts_sast.json

Ложные срабатывания

Частые причины

Ложные срабатывания возможны, когда анализатор недостаточно полно учитывает особенности приложения, специальные функции проверки данных или нестандартные правила безопасности.

Что делать. Сообщите команде сопровождения путь к файлу, строку, номер CWE и основание, по которому находка кажется ошибочной. Перед отправкой фрагментов исходного кода и диагностических файлов удалите из них секреты и согласуйте передачу по правилам организации. Рабочий код, содержащий корректную защиту, не требуется менять только ради подавления предупреждения.

Повторный анализ по изменениям

Первая проверка становится базой:

python ai_ast.py --code-dir "/srv/projects/checkout" --job-id "checkout-base"

Следующие пересчитывают только изменённое:

python ai_ast.py --code-dir "/srv/projects/checkout" --job-id "checkout-2" --incremental --incremental-baseline "checkout-base"

Что учитывается: изменения проекта и сведения предыдущей завершённой проверки. Объём повторной работы зависит от характера изменений.

Когда проверка окажется полной, хотя просили повторную

Причина	Что произошло
Обновилась версия анализатора	Правила изменились, старые результаты не годятся
Изменились настройки, правила, модель или профиль анализа	То же
Базы нет	Неверное имя или путь
База повреждена или неполна	Прошлая проверка завершилась с ошибкой

Анализатор в этих случаях выполняет полную проверку и записывает причину в run_summary.json, поле stage2.incremental.refusal_reason.

Нужен постоянный каталог. Если расположение проекта меняется между проверками, ускорение может быть меньше ожидаемого. Каталог runtime_runs/checkout-base/ и есть база, удалять его не нужно. Компактная выдача его не изменяет.

Сравнение двух проверок

Сравнение выполняет сервис, и обе проверки должны быть запущены через него:

curl -sS "http://127.0.0.1:8001/sessions/BASE_ID/diff/NEW_ID"

Ответ показывает, какие находки появились, какие исправлены, какие остались и какие сместились по строкам.

Список файлов, изменившихся между версиями, возвращает GET /v1/analyses/{id}/versions, когда новая версия отправлена с номером прошлого анализа.

Передача результатов в Accent

Какой файл передавать

Как работаете с Accent	Файл	Где взять
Решение по находкам принимает Accent	triage-input.sarif	Командная строка или интерфейс v1
Detect проверяет находки своей моделью	report.sarif, при необходимости ответ /key	Интерфейс v1, POST /v1/analyses

Файл results.sarif для Accent не предназначен. Это отчёт для систем сборки, и по умолчанию в нём только подтверждённые находки.

Как получить triage-input.sarif для одной проверки

python ai_ast.py --code-dir "/srv/projects/checkout" --job-id "checkout-triage" --analysis-profile no_llm --no-use-llm --triage-sarif

Файл окажется в runtime_runs/checkout-triage/triage-input.sarif. Нужны --analysis-profile no_llm и --no-use-llm: без них проверка пройдёт целиком и завершится ошибкой triage_sarif_requires_no_llm_profile.

Для нескольких проектов

for dir in /srv/projects/*/; do
  name=$(basename "$dir")
  python ai_ast.py --code-dir "$dir" --job-id "$name-triage" \
    --analysis-profile no_llm --no-use-llm --triage-sarif
done

Отчёт каждого проекта окажется в runtime_runs/<имя>-triage/triage-input.sarif.

Через интерфейс v1. Нужен токен.

curl -sS -X POST "http://127.0.0.1:8001/v1/triage/analyses" -H "Authorization: Bearer $DETECT_API_TOKEN" -H "Content-Type: application/zip" --data-binary @project.zip
curl -sS "http://127.0.0.1:8001/v1/analyses/$ID" -H "Authorization: Bearer $DETECT_API_TOKEN"
curl -sS "http://127.0.0.1:8001/v1/analyses/$ID/triage-input.sarif" -H "Authorization: Bearer $DETECT_API_TOKEN" -o triage-input.sarif

Указанные способы предназначены для подготовки отчёта для Accent в режиме без языковой модели.

Что внутри triage-input.sarif. В файл включаются находки, предназначенные для дальнейшего рассмотрения Accent. Состав определяется форматом обмена используемой версии.

Поле находки	Что означает
ruleId	Идентификатор применённого правила
properties.cwes	Номер вида уязвимости
properties.severity	Критичность
properties.findingMode	Режим находки по правилам Detect, без участия модели
properties.confidence, impact, likelihood	Уверенность, влияние, вероятность
properties.finding_key	Устойчивый ключ находки
properties.verified_by_detect	Всегда false: модель Detect находку не проверяла
properties.pre_llm_candidate	Всегда true: кандидат до проверки моделью

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

Этот файл предназначен для обработки находок сервисом Accent. Поле findingMode может использоваться как служебный признак типа результата.

Итоговый отчёт через интерфейс v1. Когда Detect работает со своей моделью, Accent получает проект через POST /v1/analyses и запрашивает GET /v1/analyses/{id}/report.sarif. У каждой находки там есть detect_verdict со значением confirmed или needs_review, признак verified_by_detect, ключ finding_key, объяснение и рекомендация на русском языке. Поле verified_by_detect показывает, выполнялась ли дополнительная проверка на стороне Detect.

Те же три поля одним списком возвращает GET /v1/analyses/{id}/key. Фактический профиль анализа и версии показывает GET /v1/analyses/{id}/versions. Если сервер модели был недоступен, там будет no_llm.

Проверка перед передачей

python -c "import json;s=json.load(open('runtime_runs/checkout-triage/triage-input.sarif',encoding='utf-8'));r=s['runs'][0];res=r.get('results',[]);p=r['properties'];print('findings:',len(res),'| preLlm:',p.get('preLlm'),'| llmStage3:',p.get('llmStage3'),'| all unverified:',all(not x['properties'].get('verified_by_detect') for x in res))"

Ожидаются preLlm: True, llmStage3: False и all unverified: True.

Работа через страницу сервиса

Страница http://127.0.0.1:8001/docs содержит описание интерфейса и формы. В карточке «Detect v1 — загрузка ZIP через проводник» выберите архив проекта, введите токен, при повторной проверке укажите номер прошлого анализа в поле base_analysis_id и отправьте архив. Кнопки запрашивают статус, SARIF, служебные файлы, ключ и версии.

Кнопка отправляет архив на итоговый анализ через POST /v1/analyses. Файл triage-input.sarif так не получить, для него нужны команды из раздела о передаче результатов в Accent.

Запуск проверки по сети. Для интеграции с внешними системами используйте интерфейс v1 и токен доступа. Служебные способы запуска предназначены только для закрытой административной сети и требуют согласованных средств контроля доступа.

Работа с проверками

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

Повторная проверка может использовать предыдущий завершённый анализ. Если исходная проверка не завершена, сервис может вернуть ошибку 409; повторите действие после завершения исходной проверки либо задайте полную проверку по инструкции администратора.

Встраивание в сборку

python ai_ast.py --code-dir "." --job-id "$BUILD_ID" --artifact-mode compact

Опубликуйте results/<имя>/results.sarif, и GitHub, GitLab и Azure DevOps покажут находки прямо в запросе на слияние. По умолчанию в SARIF попадают только подтверждённые находки; параметр --sarif-include-nonconfirmed добавляет остальные.

Если сборка передаёт результаты в Accent, публикуйте для него triage-input.sarif.

Политика для начала. Порог остановки сборки должен устанавливать ответственный за безопасность в соответствии с требованиями проекта и организационной политикой.

Раз в неделю имеет смысл запускать полную проверку. Повторные хороши для скорости, полная служит контрольной точкой.

Аварийные ситуации

1. Команда завершилась, а verdicts_sast_artifact_consistency.json отсутствует. Проверка не дошла до конца. Причину смотрите в run_summary.json, поля stage2.status и stage3.status.
2. Повторный анализ выполнился полной проверкой. Отпечаток настроек изменился либо база повреждена. Причина записана в run_summary.json, поле stage2.incremental.refusal_reason.
3. 409 triage_input_requires_pre_llm_analysis. Проект отправлен в POST /v1/analyses. Для отчёта до проверки моделью нужен POST /v1/triage/analyses.
4. 409 на повторе проверки. Прошлая проверка не завершилась, базы у неё нет. Передайте в теле запроса {"incremental": false}.
5. 401 на любом запросе к /v1. Токен не передан или неверен. Получите токен у администратора.
6. Сервис отвечает 503 на GET /ready. Сервис не готов принимать проверки, и в ответе перечислено, чего не хватает. Обратитесь к администратору.

Памятка

Задача	Команда
Проверить проект	python ai_ast.py --code-dir "/srv/projects/checkout" --job-id "имя"
Только три файла результата	Добавить --artifact-mode compact
Повторный анализ по изменениям	Добавить --incremental --incremental-baseline "прошлое_имя"
Повторяемый результат с моделью	Добавить --workers 1
Без языковой модели	Добавить --analysis-profile no_llm --no-use-llm
SARIF для Accent	Добавить --analysis-profile no_llm --no-use-llm --triage-sarif
Несколько проектов	Цикл по каталогам с вызовом ai_ast.py на каждый
Сравнить две проверки	GET /sessions/{база}/diff/{новая}

Вопрос	Где ответ
Что нашли	findings.json или verdicts_sast_ru.json
Какие файлы затронуты	verdicts.csv
Почему система решила именно так	verdicts_sast.json
Как прошла проверка	run_summary.json
Почему повторный анализ стал полной проверкой	run_summary.json, поле stage2.incremental.refusal_reason
Сходятся ли файлы между собой	verdicts_sast_artifact_consistency.json
Что передать в Accent	triage-input.sarif или report.sarif
С моделью ли выполнен анализ	/v1/analyses/{id}/versions, поле analysis_profile

Поля каждого файла разбирает руководство по файлам результатов.

Часто задаваемые вопросы (FAQ)

results.sarif предназначен для систем сборки, а triage-input.sarif — для обработки находок в Accent; количество записей и состав результатов могут различаться.

Объяснение и рекомендацию пишет модель Detect, а в профиле no_llm она не вызывается.

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

Если в анализе используется языковая модель, некоторые результаты могут отличаться при повторном запуске. Для сопоставления результатов используйте одинаковые настройки, а при необходимости — режим no_llm или параметр --workers 1.

Техническая поддержка

Если возникли вопросы по работе Detect, обратитесь к администратору системы или в службу поддержки: support@cybear.ru. Приложите run_summary.json проблемной проверки, вывод GET /v1/analyses/{id}/versions и её номер.