1. Введение

1.1 Назначение платформы

Accent — отечественный on-prem сервис интеллектуального триажа уязвимостей. Сервис принимает находку статического анализа (одна запись или страница SARIF 2.1.0) и возвращает вердикт: реальная уязвимость или ложное срабатывание, текстовый анализ на русском языке и рекомендацию по устранению.

Accent разворачивается внутри контура организации и работает без обращения к внешним облачным LLM. Модель поставляется вместе с сервисом. Accent используется самостоятельно через HTTP API либо как AI-интеграция платформы безопасной разработки Monolit.

1.2 Область применения

Сервис предназначен для команд безопасной разработки, которые получают большой поток срабатываний SAST и Secret-сканеров и хотят автоматически отсеять заведомо ложные находки до ручной проверки аналитиком.

Типовые сценарии: разбор результатов сканирования в Monolit, пакетный триаж выгрузки SARIF из внешнего сканера, встраивание оценки достоверности в CI/CD.

1.3 Терминология и сокращения

Термин	Определение
Триаж	Оценка достоверности находки сканера: подтвердить или отклонить как ложное срабатывание
TP	True Positive — реальная уязвимость (label=vulnerable)
FP	False Positive — ложное срабатывание (label=safe)
SARIF	Static Analysis Results Interchange Format, версия 2.1.0
Job	Асинхронная задача триажа: принята сразу, вердикт забирается отдельным запросом
GGUF	Формат весов языковой модели для локального инференса
SAST	Static Application Security Testing — статический анализ безопасности
CWE	Common Weakness Enumeration — общий перечень типов слабостей
OWASP	Open Web Application Security Project
CI/CD	Continuous Integration / Continuous Delivery

---

2. Функциональные возможности

2.1 Триаж одиночной находки

Основная операция сервиса — оценка одной находки сканера. Клиент передаёт фрагмент кода вокруг места срабатывания, правило, путь к файлу, идентификатор CWE и описание. Сервис возвращает:

• вердикт — vulnerable (TP), safe (FP) или error (не удалось разобрать ответ модели);
• анализ — обоснование на русском языке;
• рекомендации — что изменить в коде или почему находку можно отклонить;
• ml_confidence — 1.0 для подтверждённой уязвимости, 0.0 для ложного срабатывания и ошибки.

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

2.2 Триаж страницы SARIF

Accent принимает документ SARIF 2.1.0 целиком или в обёртке с полями offset и limit. Один запрос обрабатывает одну страницу находок (по умолчанию до 20). Для большого отчёта клиент повторяет запросы со сдвигом offset, пока не разберёт весь документ.

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

2.3 Асинхронный контракт

На CPU один запрос к модели занимает от десятков секунд до нескольких минут. Чтобы не держать HTTP-соединение клиента, продакшен-контракт разделён на два коротких вызова:

1. Принять работу — POST /analyze/async или POST /analyze/sarif/async → сразу 202 и идентификатор задачи.
2. Забрать результат — GET /jobs/{id} до статусов done или failed.

Синхронные POST /analyze и POST /analyze/sarif в поставке отключены и отвечают 403. Их можно включить только для локальной отладки.

2.4 Очередь и защита от перегрузки

Сервис ограничивает число одновременных обращений к модели. Пока слот занят, новые задачи ждут в очереди. Если очередь заполнена, принятие работы отклоняется кодом 503 и заголовком Retry-After — запрос в модель не уходит, повтор того же тела безопасен.

Проверка живости GET /health всегда возвращает 200, пока процесс API жив. Состояние очереди, модели и задач передаётся во вложенных полях и не валит пробы балансировщика.

2.5 Язык и формат ответа

Модель обязана отвечать по-русски строгим блоком VERDICT / REASONING / RECOMMENDATIONS. Если доля латиницы в тексте превышает порог, сервис может повторить запрос с требованием переписать ответ на русском, сохранив тот же вердикт. На CPU-профилях повтор по языку по умолчанию выключен, чтобы не удваивать время инференса.

2.6 Режимы CPU и GPU

Режим	Модель	Промпт	Назначение
CPU	компактная Q4_K_M	короткий, без few-shot	типовая on-prem виртуальная машина
GPU	полная Q8_0	расширенный, с few-shot	выше качество и ниже задержка

Режимы не смешиваются на одном хосте без отдельной настройки. Скрипт установки заказчика раскатывает CPU-профили cpu4, cpu8 и cpu16. GPU подключается отдельным составом compose.

2.7 Интеграция с Monolit

Accent реализует HTTP-контракт AI-сервиса платформы Monolit: оценка находки и проверка доступности. В Monolit сервис подключается в разделе «Инструменты» → «Интеграция AI» и привязывается к приложениям. Рекомендуемый канал для большого потока находок — постраничный SARIF через асинхронные задачи. Синхронный запрос на каждую уязвимость для такого потока не подходит.

---

3. Программный интерфейс

3.1 Эндпоинты

Метод и путь	Назначение	В поставке
POST /analyze/async	Принять одну находку	основной
POST /analyze/sarif/async	Принять страницу SARIF	основной
GET /jobs/{id}	Статус и результат задачи	основной
GET /health	Живость и служебные метрики	основной
POST /analyze	Синхронный триаж одной находки	отключён (403)
POST /analyze/sarif	Синхронный триаж страницы SARIF	отключён (403)

Интерактивная схема доступна на стенде в OpenAPI UI по адресу /docs.

3.2 Вердикты

label	Смысл для аналитика
vulnerable	Находка подтверждена (TP)
safe	Ложное срабатывание (FP)
error	Ответ модели не разобран или сбой инференса

3.3 Статусы задачи

Статус	Что делать клиенту
queued	Ждать, смотреть позицию в очереди
running	Ждать; для SARIF доступен счётчик обработанных находок
done	Забрать result
failed	Смотреть error; при retryable=true повторить submit

---

4. Состав поставки

Сервис поставляется собранными образами Docker и запускается Docker Compose.

Сервис	Назначение
api	HTTP API, очередь задач, разбор ответа модели
llama	Локальный инференс поставляемой модели
redis	Брокер асинхронных задач

Веса модели поставляются в формате GGUF и не требуют отдельной загрузки из публичных каталогов при установке через install.sh.

---

5. Безопасность и доступ

Accent не предоставляет собственный веб-интерфейс и учётные записи. HTTP API в поставке не требует аутентификации и должен быть доступен только из внутренней сети организации (межсетевой экран, закрытый сегмент, обратный прокси с контролем доступа).

Инференс выполняется локально. Исходный код находок не отправляется во внешние облачные сервисы.

Данные задач в Redis по умолчанию не персистятся на диск: очередь нужна, чтобы пережить перезапуск API. Архивом вердиктов она не служит — клиент сохраняет результаты у себя (Monolit, собственная БД, CI).

---

6. Варианты развёртывания

6.1 Docker Compose

Основной способ. Установку и обновление выполняет скрипт install.sh: проверка Docker, вход в registry, проверка хоста, загрузка compose и образов, запуск проекта.

6.2 Изолированные среды

Образы и модель поставляются из registry поставщика. После загрузки образов сервис работает без доступа в интернет. Для анализа не нужны внешние базы уязвимостей.

6.3 Совместная установка с Monolit

Скрипт установки платформы Monolit предлагает выбрать Accent вместе с платформой. Accent при этом поднимается отдельным составом контейнеров и подключается к Monolit по URL API.

---

7. Технические характеристики

7.1 Требования к системе (CPU)

Режим	Процессор	Память	Диск	Ориентир времени на одну находку
Минимум	4 vCPU	16 ГиБ	40 ГиБ	2–4 мин и дольше
Практический	8 vCPU	16 ГиБ	40 ГиБ	1–2 мин
Рекомендуемый	12–16 vCPU	16–32 ГиБ	60 ГиБ	45–60 с

7.2 Требования к системе (GPU)

Режим	Видеопамять	Хост	Ориентир времени на одну находку
Минимум	≥ 16 ГиБ свободно	4 vCPU / 16 ГиБ	15–40 с
Практический	≥ 24 ГиБ	8 vCPU / 32 ГиБ	8–25 с

Цифры — ориентир на типичной находке без очереди, не гарантия SLA. При повторном запросе из‑за языка время может удвоиться.

7.3 Масштабирование

На CPU одновременно обрабатывается одна находка. Пропускная способность растёт за счёт очереди принятых задач и более мощного хоста: параллельных инференсов на CPU нет. На GPU допускается несколько параллельных слотов, если хватает видеопамяти.