Detect / Руководство по файлам результатов
Руководство по файлам результатов
Состав рабочего каталога, поля отчётов, колонки сводки, SARIF для сборки и для Accent.
Detect
Версия Next
Введение
Руководство описывает, что Detect записывает после проверки, что лежит в каждом файле и как этими файлами пользоваться.
Документ нужен, когда отчёт уже получен и требуется понять поле, колонку или причину решения. Запуск проверки описан в руководстве пользователя, настройка и развёртывание — в руководстве администратора.
Какой файл для чего
| Вопрос | Файл |
|---|---|
| Что нашли | findings.json или verdicts_sast_ru.json |
| Какие файлы затронуты | verdicts.csv |
| Показать находки в запросе на слияние | results.sarif |
| Передать находки в Accent до проверки моделью | triage-input.sarif |
| Передать итог Detect в Accent | report.sarif |
| Почему система решила именно так | verdicts_sast.json |
| Как прошла проверка | run_summary.json |
| Почему повторный анализ стал полной проверкой | run_summary.json, поле stage2.incremental.refusal_reason |
| С моделью ли выполнен анализ | GET /v1/analyses/{id}/versions, поле analysis_profile |
| Сходятся ли файлы между собой | verdicts_sast_artifact_consistency.json |
| База для повторного анализа | baseline_manifest.json |
Где лежат результаты
Полный набор файлов лежит в рабочем каталоге проверки runtime_runs/<имя>/.
Компактная выдача (--artifact-mode compact). Дополнительно появляется каталог results/<имя>/ ровно с тремя файлами: findings.json, verdicts.csv и results.sarif. Рабочий каталог при этом сохраняется целиком, потому что он служит базой следующей проверке. Файл triage-input.sarif в компактную выдачу не входит.
Через веб-сервис. Файлы скачиваются запросом GET /sessions/{номер}/artifacts/{имя}, компактная тройка — одним архивом по GET /sessions/{номер}/compact.
Через интерфейс v1. Анализы хранятся в runtime_runs/<analysis_id>/, и к ним добавляются report.sarif и detect_v1_report.json. Для анализов через POST /v1/triage/analyses там же лежит triage-input.sarif.
findings.json и verdicts_sast_ru.json
Главный файл. Все находки на русском языке.
Устройство
| Раздел | Содержимое |
|---|---|
scan_id | Имя проверки |
project_root | Какой каталог проверялся |
summary | Сводные числа; главные перечислены ниже |
findings | Список находок |
errors | Ошибки проверки; пустой список означает, что ошибок не было |
Поля находки
| Поле | Тип | Что значит | Как использовать |
|---|---|---|---|
short_description | Текст | Краткое название проблемы | Заголовок в списке |
description | Текст | Подробное описание механизма | Понять, в чём опасность |
severity | critical, high, medium, low, info | Насколько опасен вид уязвимости | Сортировка по важности |
rule_name | Текст | Правило, которое сработало | При обращении в поддержку |
path | Путь | Файл относительно корня проекта | Открыть файл |
start_line, end_line | Числа | Строки | Перейти к месту |
start_column, end_column | Числа | Колонки | Точное место в строке |
code_snippet | Текст | Фрагмент кода, секреты вырезаны | Убедиться, что место то |
cwes | Список | Номер вида уязвимости | Описание на cwe.mitre.org |
owasp | Список | Категория OWASP Top 10 2021 | Для отчётности; пусто у видов, которых нет в OWASP Top 10 |
impact | high, medium, low | Опасность этой находки | Приоритет исправления |
likelihood | high, medium, low | Вероятность атаки | Приоритет исправления |
confidence | high, medium, low | Уверенность анализатора | С чего начать разбор |
finding_mode | confirmed, manual_review, advisory | Режим находки | Главное поле, см. ниже |
Режим находки
| Значение | Что значит | Что делать |
|---|---|---|
confirmed | Найдены достаточные признаки уязвимости | Проверить и устранить проблему |
manual_review | Признаки есть, доказательство неполное | Прочитать код |
advisory | Справочное наблюдение | Учесть при доработке |
Отсеянные правилами кандидаты в режиме suppressed в этот файл не попадают.
Секреты и фрагменты кода
В отдельных полях отчёта обнаруженные пароли, токены и другие чувствительные значения могут заменяться меткой <REDACTED_SECRET>. Не следует считать любой файл результата автоматически безопасным для пересылки: исходный код, внутренние пути, сведения о проекте и журналы могут содержать конфиденциальные данные.
Фрагмент, составленный из нескольких участков программы, может отличаться от исходного файла по оформлению. В спорной ситуации сверяйте находку с оригиналом кода в разрешённой среде.
Раздел summary
| Показатель | Смысл |
|---|---|
files_scanned | Сколько файлов проверено |
findings_count | Сколько находок в отчёте |
confirmed_findings_count | Подтверждённых |
manual_review_findings_count | На проверку |
advisory_findings_count | Справочных |
suppressed_findings_count | Отсеяно правилами |
core_sast_findings_count | Находок в коде |
project_security_findings_count | Находок уровня проекта: настройки и конфигурация |
verdicts.csv
Одна строка на каждый файл проекта, в том числе на файл без находок.
Все 18 колонок
| Колонка | Что значит |
|---|---|
scan_id | Имя проверки |
signal_identity | Внутренний идентификатор данных файла |
file | Путь к файлу |
language | Язык |
status | ok означает, что файл обработан; иначе указана причина |
present | Есть ли находка любого режима |
confirmed_present | Есть ли подтверждённая |
advisory_present | Есть ли справочная |
review_required | Нужна ли проверка человеком |
any_active_result | Есть ли хотя бы одна активная находка |
final_mode | Режим главной находки |
best_cwe_id | Номер главной находки файла |
best_score | Её оценка, от 0 до 1 |
confidence | Уверенность |
reason | Почему принято такое решение |
error | Ошибка обработки файла, если она была |
active_cwe_ids | Все найденные виды через точку с запятой |
confirmed_cwe_ids | Только подтверждённые виды через точку с запятой |
best_cwe_id и active_cwe_ids
Колонка best_cwe_id содержит одну главную находку файла: если в файле найдено три вида уязвимостей, здесь окажется один. Колонка active_cwe_ids содержит все найденные виды, например 306;307;862.
На вопрос «нашёл ли анализатор CWE-89 в этом файле» отвечает active_cwe_ids. По best_cwe_id можно ошибиться, когда находка отнесена к близкому виду.
Работа в табличном редакторе
В Excel файл открывается через «Данные» → «Из текста/CSV» с кодировкой UTF-8. Фильтр по confirmed_present = True даёт файлы с подтверждёнными находками.
results.sarif
Стандартный формат SARIF 2.1.0. Его понимают GitHub, GitLab, Azure DevOps, Visual Studio Code, среды JetBrains и большинство систем контроля качества.
Одна находка
| Поле | Содержимое |
|---|---|
ruleId, ruleIndex | Правило и его номер в списке rules |
level | error, warning или note |
message | Текст находки |
locations | Файл, строки, колонки, фрагмент кода с контекстом |
partialFingerprints | Отпечаток для отслеживания находки между проверками |
properties | Дополнительные сведения |
В разделе properties лежат поля, которых нет в стандарте.
| Поле | Смысл |
|---|---|
cwes | Номер вида |
ruleName | Правило |
findingMode | Режим находки |
resultSpace | Код или уровень проекта |
severity | Критичность |
confidence | Уверенность |
evidenceStrength | Сила доказательства |
detectionClass | Как обнаружено: по потоку данных, по состоянию или по настройке |
manualReviewRequired | Нужна ли проверка человеком |
Что попадает в SARIF
По умолчанию только подтверждённые находки. Параметр --sarif-include-nonconfirmed добавляет остальные.
Строк кода вокруг находки по умолчанию 2. Параметр --sarif-context-lines 0 уменьшает файл, но некоторые среды разработки используют контекст для подсветки.
triage-input.sarif
Отчёт для Accent, когда решение по находкам принимает он. Создаётся с параметром --triage-sarif в профиле без модели либо запросом POST /v1/triage/analyses.
В файл включаются находки для обработки сервисом Accent в соответствии с форматом обмена выбранной версии.
| Поле находки | Что означает |
|---|---|
properties.verified_by_detect | Всегда false: модель Detect находку не проверяла |
properties.pre_llm_candidate | Всегда true: кандидат до проверки моделью |
properties.findingMode | Полнота доказательства Detect без модели |
properties.finding_key | Устойчивый ключ находки |
Файл может содержать фрагменты исходного кода, сведения о найденных проблемах и ссылки на связанные участки. Проверьте допустимость передачи получателю и соблюдайте правила обращения с конфиденциальными материалами.
report.sarif
Итоговый отчёт Detect для Accent. Появляется только у анализов интерфейса v1 и скачивается запросом GET /v1/analyses/{id}/report.sarif. Формат — SARIF 2.1.0, как у results.sarif, но у каждой находки добавлены решение модели Detect и текст на русском языке.
| Поле находки | Что означает |
|---|---|
detect_verdict | Решение Detect: confirmed или needs_review |
verified_by_detect | Проверила ли находку модель Detect |
finding_key | Устойчивый ключ находки |
| Объяснение и рекомендация | Текст на русском языке, написанный моделью Detect |
codeFlows | Путь данных, когда он доказан |
relatedLocations | Найденные на пути защиты и очистка данных |
Отсеянные правилами кандидаты в файл не попадают. Повторы одной и той же находки объединяются в одну.
Те же решения одним списком, без SARIF, возвращает GET /v1/analyses/{id}/key.
verdicts_sast.json
Расширенный диагностический файл, который может содержать описание находок и служебные данные анализа. Его содержимое предназначено для эксплуатации и технической поддержки в контролируемой среде.
Наружу файл не передают без проверки содержимого. При необходимости выгрузки согласуйте получателя, проверьте содержащийся исходный код и секреты, ограничьте объём передаваемой информации. Для обычного просмотра находок используйте findings.json, verdicts_sast_ru.json или results.sarif.
run_summary.json
Сводный технический отчёт о ходе проверки. Содержит состояние запуска, сведения об ошибках и результаты обработки, необходимые для диагностики.
В первую очередь проверьте поле status, затем идентификатор проверки job_id и сведения об ошибке. В зависимости от версии дополнительные данные могут содержаться в разделах stage2 и stage3.
При обращении в поддержку передавайте только информацию, необходимую для диагностики; предварительно проверьте, нет ли в файле конфиденциальных путей и сведений о проекте.
baseline_manifest.json
Служебный файл для повторной проверки проекта. Предназначен для автоматической работы программы; при обычном использовании открывать и передавать его не требуется. Удаление соответствующих рабочих данных может привести к необходимости полной проверки проекта.
Служебные файлы
Во время проверки могут создаваться дополнительные диагностические данные и журналы. Их состав зависит от режима работы и версии Detect.
Служебные файлы не предназначены для свободного распространения. В них могут содержаться исходные тексты, внутренние пути, сведения о правилах анализа, запросы к языковой модели и другая конфиденциальная информация. Перед передачей в службу поддержки подготовьте минимальный набор сведений по согласованной процедуре.
Техническая поддержка
Если возникли вопросы по работе Detect, обратитесь к администратору системы или в службу поддержки: support@cybear.ru.