Введение

Руководство предназначено тем, кто разворачивает Detect, настраивает его и готовит результаты для сервиса триажа Accent.

Detect — статический анализатор исходного кода. Точка входа одна: ai_ast.py работает и как команда, и как веб-сервис. Интеграционный интерфейс v1 для смежных систем вынесен в detect_v1_api.py.

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

Путь	Содержимое
ai_ast.py	Точка входа: командная строка и веб-сервис
detect_v1_api.py	Интеграционный интерфейс v1
runtime_specs/	Эксплуатационные настройки (изменять только по утверждённой инструкции)
cwe_signals_v9_multilang_10lang_refactored.db	Служебный компонент поставки; не передавать отдельно
install.sh	Установщик
Dockerfile, docker-compose.yml, .env.example	Запуск в контейнере
requirements.docker.txt	Зависимости Python
docs/detect_v1_openapi.yaml	Спецификация интерфейса v1
prompts/	Служебные настройки обработки моделью; не публиковать
runtime_runs/	Рабочие каталоги проверок, создаётся при работе
results/	Компактная выдача, создаётся при работе

Инструкция по установке

Требования к системе

Анализатор работает на платформах x86-64 и ARM64 в контейнерах, под GNU/Linux и Windows.

Компонент	Требование
Python	3.11
Зависимости	Из requirements.docker.txt
Git	Для анализа репозиториев по ссылке
Docker	С поддержкой docker compose, для запуска в контейнере
Сервер модели	HTTP-доступ к OpenAI-совместимому серверу в контуре организации, для профиля deep_full
Свободное место	От 2 ГиБ; для крупных проектов больше, поскольку рабочий каталог хранит разбор каждого файла

Анализатор может работать без локальной видеокарты; использование языковой модели требует совместимого сервера модели. Для режима no_llm сервер модели не требуется.

Установщик

install.sh — скрипт bash для Linux. На Windows запускается через WSL или Git Bash.

./install.sh
./install.sh --mode docker
./install.sh --mode native

Режим auto выбирает Docker, если он есть, иначе локальное окружение Python.

Параметр	Что делает
--mode со значением auto, docker или native	Способ развёртывания
--llm-base-url URL	Адрес сервера модели
--llm-model ИМЯ	Имя модели
--llm-api-key КЛЮЧ	Ключ, передаётся как Authorization: Bearer
--llm-username, --llm-password	Логин и пароль для HTTP Basic
--port N	Порт сервиса, по умолчанию 8001
--python ПУТЬ	Интерпретатор для режима native
--no-build	Не пересобирать образ Docker
--no-start	Подготовить всё, но не запускать сервис
--skip-checks	Пропустить проверки
--skip-smoke	Пропустить контрольную проверку
--force	Перезаписать существующие .env и файл доступов
--non-interactive	Без вопросов, со значениями по умолчанию

Задавайте адрес и модель только вместе. Доступы записываются в runtime_specs/llm_auth.local.json с правами только для владельца.

Токен интерфейса v1 установщик не задаёт. В режиме docker контейнер без DETECT_API_TOKEN не запустится, поэтому порядок такой:

./install.sh --mode docker --no-start
# задать DETECT_API_TOKEN и LLM_BASE_URL в .env
docker compose up -d

В режиме native штатный способ запуска может открыть сервис на всех сетевых интерфейсах. До ввода в эксплуатацию ограничьте сетевой доступ и при отсутствии внешних клиентов запускайте с --host 127.0.0.1.

Ручная установка

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.docker.txt

Доступ к серверу модели

Модель нужна только в профиле deep_full. Имя модели указывается администратором в настройках сервера. Адрес сервера по умолчанию не задан, и без него проверка с моделью невозможна.

Способ	Что задаётся	Когда использовать
Переменные окружения или .env	LLM_BASE_URL, LLM_MODEL, LLM_API_KEY	Сервис и Docker
Параметры командной строки	--base-url, --model, --api-key	Разовый запуск
Файл доступа runtime_specs/llm_auth.local.json или путь в AI_AST_LLM_AUTH_FILE	base_url, model, api_key, username, password	Чтобы ключи и пароли не попадали в команды

Образец файла доступа — llm_auth.local.example.json.

Приоритет источников доступов

Непустые base_url, model и api_key из файла доступа имеют приоритет над параметрами командной строки и переменными окружения. Логин и пароль для HTTP Basic берутся только из файла доступа: параметры --username, --password и переменные LLM_USERNAME, LLM_PASSWORD в запросы к модели не попадают.

Проверка сервера модели при постановке анализа через v1

При постановке анализа сервис проверяет доступность модели запросом GET <LLM_BASE_URL>/models. Эта проверка читает только переменные окружения LLM_BASE_URL, LLM_API_KEY, LLM_USERNAME и LLM_PASSWORD, но не файл доступа. Если LLM_BASE_URL пуст, каждый анализ через интерфейс v1 пойдёт в профиле no_llm. Поэтому для сервиса задавайте LLM_BASE_URL в .env, даже когда доступы лежат в файле.

Одновременные запросы к модели

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

Профили анализа

Профили описаны в runtime_specs/detect_analysis_profiles.yml.

Профиль	Разбор файлов	Проверка путей данных	Назначение
deep_full	Без модели	С моделью	Профиль по умолчанию
no_llm	Без модели	Без модели	Отчёт для Accent, замеры качества, работа без сервера модели

В профиле deep_full может использоваться языковая модель, а в no_llm анализ выполняется без неё. Поле verified_by_detect в интеграционном формате указывает наличие дополнительной проверки на стороне Detect.

Как профиль выбирается

Командная строка

Модель выключается только параметром --no-use-llm. Параметр --analysis-profile no_llm сам по себе её не выключает, потому что значение use_llm из командной строки имеет приоритет над профилем. Поэтому указывайте оба:

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

Профиль нужен дополнительно: он входит в отпечаток настроек и обязателен для triage-input.sarif.

Служебный интерфейс

Модель выключается полем "use_llm": false в теле запроса. Профиль из поля analysis_profile или переменной DETECT_ANALYSIS_PROFILE решает сам, только когда use_llm не задан ни в теле запроса, ни переменной STAGE3_USE_LLM. В .env.example и в Docker эта переменная равна true, поэтому для проверки без модели передавайте "use_llm": false явно.

Интерфейс v1

Клиент профиль не выбирает, его задаёт переменная DETECT_ANALYSIS_PROFILE на сервере. Если при постановке анализа сервер модели недоступен, анализ выполняется в no_llm. Фактический профиль виден в GET /v1/analyses/{id}/versions, поле analysis_profile. Маршрут POST /v1/triage/analyses всегда работает в no_llm.

Запуск

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

Одна проверка

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

Параметр --code-dir принимает каталог или ссылку на репозиторий Git.

Только три файла результата

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

Копии трёх файлов появятся в results/checkout/. Рабочий каталог runtime_runs/checkout/ сохраняется целиком.

Несколько проектов

Каждый проект проверяется своим запуском. Пройдите по каталогам циклом:

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

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

Веб-сервис

export DETECT_API_TOKEN="<стойкий-токен>"
python ai_ast.py --serve --host 127.0.0.1 --port 8001

Без --host сервис слушает 0.0.0.0, то есть все сетевые интерфейсы. Страница с описанием интерфейса и формами — http://127.0.0.1:8001/docs.

Отчёт для Accent до проверки моделью

В этом сценарии Detect готовит отчёт о находках для последующей обработки сервисом Accent.

исходный проект → Detect (режим без модели) → triage-input.sarif → Accent

Три отчёта SARIF и чем они различаются

Файл	Как получается	Модель Detect	Что внутри
triage-input.sarif	--triage-sarif или POST /v1/triage/analyses	Не вызывается	Находки, подготовленные для передачи Accent
report.sarif	POST /v1/analyses	При соответствующем профиле	Итоговый отчёт анализа Detect
results.sarif	Любая проверка	Как настроено	Отчёт для систем сборки; по умолчанию только confirmed

Для сценария, где решает Accent, передаётся только triage-input.sarif.

Способ 1. Одна проверка

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.
• Параметр --sarif-include-nonconfirmed влияет только на results.sarif. В triage-input.sarif неподтверждённые кандидаты попадают всегда.
• С --artifact-mode compact появятся и три файла в results/checkout-triage/. Файл triage-input.sarif в компактную выдачу не входит и остаётся в рабочем каталоге.

Способ 2. Несколько проектов

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. В Accent передаются эти файлы.

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

Способ 3. Интерфейс v1

Нужен запущенный сервис и токен DETECT_API_TOKEN. Проект отправляется в POST /v1/triage/analyses архивом ZIP либо ссылкой на репозиторий с идентификатором коммита, затем по GET /v1/analyses/{id} отслеживается статус, и готовый отчёт скачивается по GET /v1/analyses/{id}/triage-input.sarif.

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

Параметры и переменные окружения

Потоки

Шаг	Обращается к модели	Потоков по умолчанию	Как изменить
Разбор файлов	Нет	1	AI_AST_STAGE2_WORKERS
Индекс проекта	Нет	8	AI_AST_PROJECT_INDEX_WORKERS
Проверка путей данных	Да, в профиле deep_full	8	--workers, AI_AST_STAGE3_WORKERS; для сервиса — поле workers или STAGE3_WORKERS

Значения по умолчанию записаны в runtime_specs/performance_policy.yml, раздел execution.

Настройка параллельности. Меняйте число рабочих процессов только после измерения нагрузки на целевой системе.

При выборе параллельности учитывайте пропускную способность сервера модели. Слишком большое число одновременных операций увеличивает ожидание.

Объём и скорость

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

Повторяемость

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

Кеш индекса и межфайловый индекс

В версии Detect предусмотрены параметры --index-cache и --project-index. Их значения следует изменять только по рекомендации технической поддержки: изменение параметров может влиять на время работы и полноту анализа. Для стандартной эксплуатации используйте значения по умолчанию.

Развёртывание в Docker

Образ собирается на Python 3.11. Порт публикуется только на 127.0.0.1.

1. Скопировать шаблон настроек: cp .env.example .env
2. Заполнить в .env как минимум DETECT_API_TOKEN, LLM_BASE_URL и LLM_MODEL.
3. Собрать и запустить:

docker compose build
docker compose up -d
docker compose ps
curl -sS http://127.0.0.1:8001/ready

Без DETECT_API_TOKEN контейнер не запустится: docker compose остановится с сообщением Set DETECT_API_TOKEN in .env. Без LLM_BASE_URL анализы через интерфейс v1 пойдут в профиле no_llm.

Остановить сервис — docker compose down. Журнал читается командой docker compose logs --tail 50 stage23-api.

Основные переменные .env

Переменная	По умолчанию	Смысл
DETECT_API_TOKEN	—	Токен интерфейса v1, обязателен
DETECT_ANALYSIS_PROFILE	deep_full	Профиль анализа для интерфейса v1 и служебного интерфейса
LLM_BASE_URL	—	Адрес сервера модели
LLM_MODEL	Определяется конфигурацией поставки	Имя модели
LLM_API_KEY	—	Ключ доступа к серверу модели
AI_AST_PORT	8001	Порт сервиса
AI_AST_STAGE2_WORKERS	1	Потоки разбора файлов
AI_AST_PROJECT_INDEX_WORKERS	8	Потоки индекса проекта
AI_AST_STAGE3_WORKERS, STAGE3_WORKERS	8	Потоки проверки путей данных, одно значение на обе переменные
STAGE3_USE_LLM	true	Модель на проверке путей данных для служебного интерфейса; пока значение true, профиль no_llm в теле запроса модель не выключает
STAGE3_LLM_TIMEOUT	220	Предел ожидания ответа модели, секунд
STAGE23_RUNS_DIR	runtime_runs	Каталог проверок

Каталоги

В контейнер монтируются ./input, ./runtime_runs и ./llm_logs. История проверок и основы для повторного анализа хранятся в runtime_runs и сохраняются при пересоздании контейнера.

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

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

Что остаётся после проверки

Рабочий каталог runtime_runs/<имя>/

Файл	Назначение
verdicts_sast.json	Полный внутренний отчёт с доказательствами
verdicts_sast_ru.json	Русский отчёт, 16 полей на находку
verdicts.csv	Строка на файл, 18 колонок
verdicts.jsonl	То же, что verdicts.csv, построчно в JSON
verdicts_topk.csv	Все рассмотренные виды уязвимостей по файлу, с оценками
results.sarif	SARIF для систем сборки
triage-input.sarif	SARIF для Accent, с --triage-sarif или через POST /v1/triage/analyses
run_summary.json	Ход проверки
baseline_manifest.json	База для повторного анализа по изменениям
verdicts_sast_artifact_consistency.json	Результат сверки файлов между собой
llm_context_budget_report.json	Служебные сведения; ограничить распространение
calibration_bundle.zip	Материалы для разбора спорной находки
llm_logs/	Журналы обращений к модели, могут содержать исходные тексты
signals/	Служебные данные анализа; ограничить доступ

Каталог signals/ содержит служебные данные анализа. Доступ к нему должен быть ограничен: эти сведения не предназначены для публичного распространения или передачи в поддержку без проверки содержимого.

Компактная выдача results/<имя>/

Ровно три файла: findings.json с копией русского отчёта, verdicts.csv с копией сводки и results.sarif. Рабочий каталог при этом сохраняется целиком, потому что он служит базой следующей проверке. Файл triage-input.sarif в компактную выдачу не входит.

Анализы интерфейса v1

Хранятся в каталоге проверок сервиса runtime_runs/<analysis_id>/. Помимо файлов выше, там лежат report.sarif и detect_v1_report.json, а для анализов через POST /v1/triage/analyses ещё и triage-input.sarif. Служебное состояние анализов лежит в runtime_runs/_v1/, временные файлы исходного кода — в runtime_runs/_v1_sources/ и удаляются после анализа.

Колонки verdicts.csv

Колонка	Смысл
best_cwe_id	Главная находка файла
active_cwe_ids	Все найденные виды через точку с запятой
confirmed_cwe_ids	Только подтверждённые

При подсчёте полноты используйте active_cwe_ids: по нему видно, найден ли нужный вид. Колонка best_cwe_id даёт долю файлов, где этот вид стал главным.

Резервное копирование и восстановление

Что копировать

Путь	Содержимое	Чем грозит потеря
.env	Токен интерфейса v1, адрес и имя модели, порт, число потоков	Сервис не запустится, настройки восстанавливаются вручную
runtime_specs/llm_auth.local.json	Доступы к серверу модели	Профиль deep_full недоступен до повторного ввода доступов
runtime_specs/	Служебные настройки поставки	Потеря утверждённых изменений конфигурации
runtime_runs/	История проверок и базы для повторного анализа	Следующая проверка каждого проекта будет полной
results/	Компактная выдача, если она используется	Потеря переданных заказчику отчётов

Служебные компоненты поставки восстанавливаются из доверенного установочного комплекта.

Восстановление

Разверните Detect заново, верните сохранённые файлы на прежние места и запустите сервис. Рабочие каталоги в runtime_runs/ опознаются по именам: если каталог проверки на месте и отпечаток настроек не изменился, повторный анализ по изменениям продолжит работать.

Обновление

Обновление заменяет программные компоненты и образы Detect. Настройки лежат отдельно и сохраняются при обновлении: install.sh перезаписывает .env и файл доступов только с параметром --force.

Порядок:

1. Остановите сервис: docker compose down.
2. Сохраните .env, runtime_specs/llm_auth.local.json и runtime_runs/.
3. Разверните новую версию поставки.
4. Запустите установщик без перезаписи настроек: ./install.sh --mode docker.
5. Проверьте готовность: curl -sS http://127.0.0.1:8001/ready.
6. Сверьте версию: curl -sS http://127.0.0.1:8001/runtime/version.

После обновления первая проверка каждого проекта будет полной. Новая версия меняет отпечаток настроек, и базы прошлых проверок для повторного анализа не годятся. Удалять runtime_runs/ не нужно, базы перезапишутся после первой полной проверки.

Измеренное качество

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

Безопасность

Обязательные условия безопасного развёртывания.

1. Токен DETECT_API_TOKEN проверяется на маршрутах /v1. Служебные маршруты /pipeline/*, /sessions/* и /artifacts/* не имеют такой же проверки токена. Изолируйте их на уровне сети.
2. По умолчанию предоставляйте доступ только через 127.0.0.1 или ограниченный административный сегмент. При доступе с других машин используйте межсетевой экран и защищённый шлюз с аутентификацией для всех маршрутов; для передачи данных по сети используйте TLS.
3. Не размещайте Detect напрямую в интернете. Отдельно ограничьте доступ к /docs, диагностике и операциям скачивания результатов.
4. DETECT_API_TOKEN, ключи доступа к модели и другие учётные данные храните вне репозитория, в файлах с ограниченными правами либо в специализированном хранилище секретов; не передавайте их в отчётах и заявках поддержки.
5. Рабочие каталоги, архивы проектов, журналы, временные файлы и отчёты содержат или могут содержать исходный код, пути, фрагменты конфигурации и чувствительные данные. Ограничьте доступ, установите сроки хранения, резервное копирование и порядок безопасного удаления.
6. Перед передачей результатов, диагностических архивов или журналов сторонней организации проверяйте их на секреты и сведения, относящиеся к коммерческой тайне. Не отправляйте полный проект или полную внутреннюю базу правил без отдельного разрешения.

Ограничения архивов

Настройки приёма ZIP задаются эксплуатационной конфигурацией. Приём архивов следует выполнять только через предусмотренные интерфейсы, с сохранением штатных проверок путей распаковки, объёма и типов файлов. Не отключайте такие проверки ради ускорения установки или тестов.

Исходный код, полученный через интерфейс v1, удаляется после анализа согласно действующей настройке cleanup_source_after_analysis: true. Это не означает автоматического удаления всех журналов и рабочих результатов; сроки их хранения задаются отдельно.

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

Доступы к модели храните с минимально необходимыми правами. Дополнительные меры сетевой безопасности применяются в соответствии с политиками заказчика.

Диагностика

Проверка завершилась ошибкой. Сообщение об ошибке называет этап и файл. Дальше смотрите run_summary.json, поля stage2.status и stage3.status.

Повторный анализ выполнился полной проверкой. Причина записана в run_summary.json, поле stage2.incremental.refusal_reason.

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

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

Интерфейс v1 ведёт анализ без модели. Проверьте поле analysis_profile в GET /v1/analyses/{id}/versions. Значение no_llm означает, что в момент отправки сервер модели не ответил по адресу LLM_BASE_URL или переменная не задана.

Все запросы к /v1 получают 401. На сервере не задан DETECT_API_TOKEN или клиент передаёт другой.

Контейнер не запускается. Сообщение Set DETECT_API_TOKEN in .env означает, что токен в .env не задан.

Расширенная диагностика правил. Выполняется по отдельному запросу службы поддержки в контролируемой среде. Такие материалы содержат сведения о внутренней логике анализа и фрагменты исходного кода: наружу их не передают.

Сервис не готов. Ответ 503 на GET /ready перечислит, что именно не готово.

Журналы

Где	Что внутри
docker compose logs --tail 50 stage23-api	Журнал сервиса в контейнере: приём запросов, ошибки этапов
runtime_runs/<имя>/run_summary.json	Ход проверки по этапам, статусы, причина отказа повторного анализа
runtime_runs/<имя>/llm_logs/	Журналы взаимодействия с моделью; могут содержать конфиденциальные данные
runtime_runs/<имя>/signals/project_index_timings.json	Служебные данные диагностики; передавать по согласованию

В обращение к поддержке приложите журнал контейнера и run_summary.json проблемной проверки.

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

Профиль сам по себе модель не выключает: значение use_llm из командной строки имеет приоритет над профилем. В командной строке добавьте --no-use-llm, в теле запроса к служебному интерфейсу — "use_llm": false. Для интерфейса v1 профиль задаётся только переменной DETECT_ANALYSIS_PROFILE на сервере.

Каталог runtime_runs/<имя>/ и есть база для повторного анализа. После удаления следующая проверка этого проекта будет полной. Компактная выдача рабочий каталог не изменяет.

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

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

Если возникли вопросы по работе Detect, обратитесь в службу поддержки: support@cybear.ru. Приложите вывод GET /runtime/version, вывод GET /ready, файл run_summary.json проблемной проверки и журнал контейнера stage23-api.