Detect / Возможности
Описание функциональных возможностей
Поиск по пути данных, режимы находок и анализа, поддерживаемые языки, программный интерфейс, требования.
Detect
Версия Next
1. Введение
1.1 Назначение продукта
Detect — статический анализатор безопасности исходного кода. Он исследует код программы без её запуска и помогает обнаруживать потенциально опасные способы обработки данных, в том числе связанные с запросами к базе данных, выполнением команд и работой с файлами.
Detect учитывает связи между частями программы и формирует сведения, необходимые для проверки обнаруженных проблем. В зависимости от выбранного режима может использоваться языковая модель. Результаты доступны в отчётах и в формате SARIF 2.1.0 для взаимодействия с Accent и другими системами.
При размещении всех компонентов в инфраструктуре организации проверка выполняется в контролируемом контуре. Порядок подключения к серверу языковой модели определяется настройками заказчика.
1.2 Область применения
Detect предназначен для команд безопасной разработки, которым нужен поиск уязвимостей в коде на десяти языках программирования с прослеживанием путей данных между файлами.
Типовые сценарии: проверка каталога с кодом или репозитория по ссылке, последовательная проверка нескольких проектов, подготовка отчёта для Accent, публикация находок в запросе на слияние через SARIF.
1.3 Терминология и сокращения
| Термин | Определение |
|---|---|
| Находка | Место в коде, где анализатор подозревает уязвимость |
| Режим находки | Степень доказанности: confirmed, manual_review, advisory, suppressed |
| Источник | Точка, откуда в программу приходят внешние данные: запрос пользователя, файл, сетевой вызов |
| Опасная операция | Действие, которое внешние данные могут обратить во вред: запрос к базе, команда системы, запись в файл |
| Защита | Проверка, экранирование или очистка данных между источником и опасной операцией |
| Проверка | Один запуск анализатора по проекту |
| Базовая проверка | Завершённая проверка, от которой отсчитывается повторный анализ по изменениям |
| Профиль анализа | Настройка участия языковой модели: deep_full или no_llm |
| Индекс проекта | Карта связей между файлами, которую анализатор строит перед проверкой |
| CWE | Common Weakness Enumeration, международный перечень видов уязвимостей |
| SARIF | Static Analysis Results Interchange Format, версия 2.1.0 |
| SAST | Static Application Security Testing, статический анализ безопасности |
finding_key | Устойчивый ключ находки, по которому одну и ту же находку узнают в отчётах разных проверок и версий продукта |
analysis_id | Номер анализа, выданный программным интерфейсом v1 |
verified_by_detect | Признак находки, уже проверенной моделью Detect |
В меню поставки и в служебных файлах сервис триажа может называться AI-TRIAGE. Это то же изделие, что Accent.
2. Функциональные возможности
2.1 Поиск уязвимостей по пути данных
Detect анализирует использование внешних данных в программе, в том числе при передаче информации между файлами и функциями. Он проверяет, могут ли такие данные попасть в потенциально опасные операции и какие меры защиты предусмотрены.
Результаты сопровождаются указанием места в коде и сведениями, полезными при проверке находки. Если имеющейся информации недостаточно для однозначного вывода, находка может быть направлена на дополнительную проверку специалистом.
2.2 Режимы находок
| Режим | Когда присваивается |
|---|---|
confirmed | Найдены достаточные признаки уязвимости для данного вида проверки |
manual_review | Признаки уязвимости есть, доказательство неполное |
advisory | Справочное наблюдение |
suppressed | Служебный статус результата, не предназначенного для основного отчёта |
Режим определяет, что аналитик делает с находкой. Находки в режиме confirmed разбираются первыми, manual_review требует чтения кода, advisory читается при разборе соседних находок.
2.3 Профили анализа
| Профиль | Назначение |
|---|---|
deep_full | Анализ с дополнительным использованием языковой модели при доступном сервере модели |
no_llm | Анализ без обращения к языковой модели; может использоваться для подготовки отчёта Accent |
Выбор профиля определяет участие языковой модели и состав передаваемых результатов. Подробный порядок работы с профилями и параметры запуска приведены в руководстве администратора.
2.4 Способы подачи кода
| Способ | Что принимает |
|---|---|
| Каталог на сервере | Путь к распакованному проекту |
| Репозиторий по ссылке | Адрес репозитория и идентификатор коммита |
| Архив через программный интерфейс | Файл .zip |
| Несколько проектов | Каждый проект проверяется своим запуском |
2.5 Состав результата
Detect формирует отчёт о находках и их расположении в коде, сводные результаты проверки и машиночитаемые данные для других систем. Поддерживаются JSON, CSV и SARIF.
В процессе работы могут создаваться дополнительные служебные файлы. Они нужны для эксплуатации и диагностики, и наружу их не передают без проверки содержимого. Назначение основных отчётов описано в руководстве по файлам результатов.
2.6 Маскирование секретов
При подготовке отдельных полей отчётов Detect предусматривает маскирование обнаруженных чувствительных значений. Автоматическое маскирование не гарантирует удаление всех секретов из любых служебных файлов. Перед передачей отчётов за пределы защищённой среды необходимо проверить их содержимое и соблюдать правила обращения с конфиденциальными данными.
2.7 Повторный анализ по изменениям
Detect поддерживает повторную проверку проекта с учётом изменений после предыдущего завершённого анализа. Первая проверка проекта всегда полная. Фактическое время зависит от объёма и характера изменений и доступных вычислительных ресурсов.
2.8 Сравнение двух проверок
Результаты двух проверок можно сопоставить, чтобы увидеть новые, сохраняющиеся и устранённые находки. Сопоставление выполняет запрос GET /sessions/{база}/diff/{новая}.
2.9 Передача результатов в Accent
Detect поддерживает два способа интеграции с Accent:
| Сценарий | Что передаётся | Назначение |
|---|---|---|
| Передача отчёта до дополнительной проверки | triage-input.sarif | Accent получает находки для собственной обработки |
| Передача итогового отчёта Detect | report.sarif | Accent получает результаты анализа Detect |
Передаваемые документы используют формат SARIF 2.1.0. Состав доступных полей и условия обмена определяются интерфейсом выбранной версии. Фрагменты кода и сведения о находках следует считать конфиденциальной информацией.
3. Поддерживаемые языки программирования
Detect предназначен для анализа исходного кода на следующих языках: Python, Java, Kotlin, JavaScript, TypeScript, C#, C/C++, Go, Ruby и PHP. Также предусмотрена обработка отдельных файлов конфигурации.
Поддерживаемые виды уязвимостей и глубина анализа различаются по языкам и зависят от версии поставки. Актуальный перечень передаётся вместе с комплектом поставки. Языки 1С (BSL) и ABAP данной версией не поддерживаются.
4. Программный интерфейс
4.1 Интерфейс v1 для интеграции
Основной интерфейс для смежных систем. Все запросы идут с заголовком Authorization: Bearer <токен>.
| Запрос | Назначение |
|---|---|
POST /v1/analyses | Отправить проект архивом или ссылкой на репозиторий |
POST /v1/triage/analyses | То же без участия модели, с подготовкой triage-input.sarif |
GET /v1/analyses/{id} | Статус, прогресс, ошибка, ссылки на результаты |
GET /v1/analyses/{id}/report.sarif | Итоговый отчёт SARIF |
GET /v1/analyses/{id}/triage-input.sarif | Отчёт до проверки моделью |
GET /v1/analyses/{id}/key | Ключи находок, признак проверки и вердикт Detect |
GET /v1/analyses/{id}/artifacts | Архив служебных файлов для диагностики |
GET /v1/analyses/{id}/versions | Версия и служебная информация об анализе |
GET /v1/openapi.json | Спецификация интерфейса |
Статусы анализа: queued, running, succeeded, failed. Незавершённые после перезапуска сервиса анализы получают interrupted.
При определённых условиях уже выполненный анализ может использоваться повторно. Доступные признаки результата описаны в спецификации интерфейса.
| Код | Причина |
|---|---|
400 | Некорректный архив или запрос репозитория |
401 | Токен отсутствует или неверен |
404 | Анализ не найден |
409 | Анализ или базовая проверка ещё не готовы, либо triage-input.sarif запрошен у анализа, созданного через POST /v1/analyses |
413 | Превышены ограничения архива |
500 | Внутренняя ошибка |
4.2 Служебный интерфейс
Служебный интерфейс даёт операции управления проверками, их историей и результатами. Публикуйте его только в закрытом сегменте сети: токеном он не защищён, подробности в руководстве администратора.
4.3 Веб-страница сервиса
По адресу /docs сервис возвращает страницу с описанием интерфейса и тремя формами — загрузка архива, история проверок, скачивание результатов. Отдельного веб-интерфейса управления у Detect нет.
5. Состав поставки
Detect поставляется исходными текстами и собранными образами Docker. Запуск — Docker Compose либо локальное окружение Python.
| Составная часть | Назначение |
|---|---|
| Анализатор | Командная строка и веб-сервис в одной точке входа |
| Интеграционный интерфейс v1 | Приём проектов и выдача отчётов смежным системам |
| Каталог настроек | Эксплуатационные настройки анализа |
| База профилей CWE | Служебный компонент поставки |
| Установщик | Развёртывание в Docker или в локальном окружении Python |
Сервер языковой модели в поставку не входит. Detect обращается к OpenAI-совместимому серверу, развёрнутому в контуре организации.
6. Безопасность и доступ
Detect рекомендуется развёртывать в выделенном сегменте сети организации. Доступ к интерфейсам и результатам проверки открывайте только тем, кому он нужен по работе.
При подключении из других сетей обязательны дополнительные средства защиты (например, шлюз с аутентификацией, TLS и ограничения сетевого доступа). Служебные интерфейсы не следует публиковать напрямую в интернете. Подробные обязательные настройки приведены в руководстве администратора.
Исходный код проверяемых проектов, журналы, отчёты и временные файлы могут содержать конфиденциальные сведения; для них необходимы ограничения доступа, сроки хранения и безопасное удаление.
7. Варианты развёртывания
7.1 Docker Compose
Поставляемая версия может развёртываться в контейнерной среде с использованием Docker Compose. При настройке администратор задаёт сетевые ограничения, учётные данные и при необходимости адрес сервера модели. Рабочие данные должны сохраняться только в каталогах с ограниченным доступом.
7.2 Локальная установка
При наличии соответствующих компонентов поставки поддерживается локальная установка в среде Python. Вариант установки, параметры сети и правила хранения данных определяет администратор.
7.3 Изолированные среды
Detect может развёртываться в изолированной инфраструктуре при наличии необходимых компонентов и заранее подготовленных зависимостей. Доступ к внешним сервисам определяется выбранной схемой развёртывания.
8. Технические характеристики
8.1 Требования к системе
Анализатор работает на платформах x86-64 и ARM64 в контейнерах, под GNU/Linux и Windows.
| Компонент | Требование |
|---|---|
| Python | 3.11 |
| Docker | С поддержкой docker compose, для контейнерного развёртывания |
| Git | Для анализа репозиториев по ссылке |
| Свободное место | От 2 ГиБ; для крупных проектов больше, поскольку рабочий каталог хранит разбор каждого файла |
| Сервер модели | Доступ к совместимому серверу языковой модели в контролируемом контуре, если выбран режим с моделью |
| Порт | 8001 по умолчанию |
Все этапы анализа считает процессор. Видеокарта нужна серверу языковой модели, который в поставку Detect не входит и разворачивается в контуре организации отдельно. Профилю no_llm видеокарта не нужна.
8.2 Повторяемость результата
Параллельность обработки настраивается в зависимости от доступных вычислительных ресурсов и выбранного режима анализа. Использование языковой модели может влиять на время и воспроизводимость результата. Для контрольных проверок следует применять единообразные настройки.
8.3 Объём и скорость
Допустимые объёмы проектов и фактическая скорость проверки зависят от оборудования, состава исходного кода и настроек анализа. Согласованные эксплуатационные ограничения определяются документацией конкретной поставки или проверяются при внедрении.
8.4 Качество анализа
Показатели качества зависят от языка программирования, состава проверяемых уязвимостей, применяемого набора проектов и конфигурации проверки. Подтверждённые измерения предоставляются отдельно с указанием версии, методики и условий получения результатов.
9. Сопутствующая документация
| Документ | Содержание |
|---|---|
| Руководство пользователя | Запуск проверки, чтение отчёта, разбор находки, сравнение версий, встраивание в сборку |
| Руководство администратора | Установка, доступ к серверу модели, параметры, развёртывание в Docker, диагностика |
| Руководство по файлам результатов | Состав рабочего каталога, поля отчётов, колонки сводки |
Вместе с продуктом поставляются дополнительные технические инструкции и спецификация программного интерфейса.