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

Безопасность — ключевая ценность Synth. Модель по определению ненадёжна, поэтому надёжность обеспечивает платформа: единый слой для LLM-вызовов, гранулярные права, роли, подтверждение опасных действий и журнал аудита.

LLM Gateway¶

LLM Gateway — единый слой безопасности для всех LLM-вызовов (включая саб-агентов, суммаризацию и служебные запросы). Он перехватывает трафик «запрос → провайдер → ответ → потребление» и не допускает утечки секретов.

Выключен по умолчанию

Пока шлюз не включён, трафик идёт напрямую. Включается администратором в разделе «Шлюз безопасности»; настройка глобальная.

Обфускация секретов¶

При включении шлюз по умолчанию обфусцирует, а не блокирует: найденный секрет (API-ключ, токен, пароль, данные карты) заменяется плейсхолдером ⟦SYNTH_SECRET_N⟧, а соответствие сохраняется в карте обфускации сессии.

Вход:  "мой ключ sk-abc123 используй для подключения"
          ↓ обфускация (карта: ⟦SYNTH_SECRET_1⟧ → sk-abc123)
          "мой ключ ⟦SYNTH_SECRET_1⟧ используй для подключения"
          ↓ LLM
Ответ: "Подключение с ⟦SYNTH_SECRET_1⟧ установлено"

Реальные значения подставляются обратно не в поток ответа, а в точках потребления: при записи файла, выполнении shell-команды, веб-запросе, git-операции, поиске и вызове MCP-инструмента.

Два режима обработки входа:

Режим	Поведение
`obfuscate` (по умолчанию)	Секрет заменяется плейсхолдером, запрос уходит в LLM
`block`	При обнаружении секрета запрос блокируется, в LLM ничего не уходит

Карта обфускации — тоже секрет

Доступ к словарю есть только у ADMIN и AUDITOR (вкладка «Словарь обфускации» в правой панели). Раскрытие плейсхолдера пользователем логируется как событие аудита. Сгенерированные моделью плейсхолдеры, которых нет в карте, не восстанавливаются.

Rate limit¶

Ограничивается частота LLM-запросов:

на пользователя — llmGateway.rateLimit.userPerMinute;
на провайдера — llmGateway.rateLimit.providerPerMinute, защита от исчерпания квоты.

Ограничение действует и на внутренние вызовы (суммаризация, авто-заголовки, саб-агенты), а не только на запросы пользователя.

Output Guard¶

Ответы модели тоже проверяются: детектируются подозрительные секреты, URL и команды. События пишутся в аудит (output_guard).

Конфигурация шлюза:

llmGateway:
  enabled: false          # выключен по умолчанию
  inputMode: "obfuscate"  # obfuscate | block
  rateLimit:
    userPerMinute: 60
    providerPerMinute: 120
  audit:
    enabled: true
    logPath: ""           # пусто → {dataDir}/audit/llm-gateway.jsonl

Гранулярные права¶

Поверх ролей работает тонкая настройка доступа к инструментам. Правила задают для каждого инструмента одно из действий:

Действие	Смысл
`allow`	Выполнять без подтверждения
`ask`	Спросить подтверждение у пользователя
`deny`	Запретить

Правила описываются в секции permission.rules и могут учитывать паттерны команд и файлов. Опасные действия по умолчанию требуют подтверждения; таймаут ожидания ответа — permission.askTimeoutMs. Настройки наследуются саб-агентами: дочерний агент не может получить прав больше, чем родительская сессия.

Режимы Plan / Act / YOLO¶

Режим сессии — глобальный переключатель, задающий, насколько свободно агент действует:

Режим	Поведение
`plan`	Только планирование и чтение; изменения запрещены
`act`	Действия разрешены в рамках правил прав, опасные — с подтверждением
`yolo`	Максимальная автономность: подтверждения не запрашиваются

Помимо режима настраивается строгость цикла «план → реализация» (session.planMode: auto, strict, off). Подробнее — в разделе Режимы и права.

Аутентификация: OIDC и API-ключи¶

OIDC (Keycloak) — продакшен-вход: JWT, проверка подписи и извлечение ролей. Настройка — в разделе SSO / Keycloak.
API-ключи — для развёртываний без OIDC и для локального режима. Предъявляются в заголовке Authorization: Bearer <api-key>.

Роли ADMIN, USER, LEAD, AUDITOR определяют доступ к разделам и админским операциям. Подробнее — в разделе Аутентификация и роли.

Аудит-журнал¶

Каждый LLM-запрос логируется в append-only JSONL-файл {dataDir}/audit/llm-gateway.jsonl (одна строка — одна запись). Фиксируются: время, тип события, пользователь, сессия, провайдер и модель, найденные секреты и плейсхолдеры, расход токенов и стоимость, причина.

Типы событий: obfuscated, blocked, revealed, rate_limited, output_guard. Секреты в журнале хранятся только как плейсхолдеры.

Просмотр доступен администраторам и аудиторам: через API (GET /api/v2/audit с фильтрами по пользователю, сессии и периоду) и командой synth audit.

Защищённые пути: 403 «Permission denied»¶

Часть путей защищена от чтения и изменения агентом. Проверка применяется ко всем файловым инструментам и shell-командам, и её запрет приоритетнее обычных правил прав.

Симптом: агент не может прочитать или изменить файл; в ответе Permission denied.

Решение — настроить политику защищённых путей одним из способов:

Через APIФайломОтключить защиту

GET/PUT/DELETE /api/v2/settings/protected-paths с телом вида {version: 1, add: [...], remove: [...]} — добавить или убрать пути относительно системного списка.

{dataDir}/security/protected-paths.json в том же формате add/remove (version: 1).

Тумблер security.protectedPaths.enabled в секции «Безопасность» интерфейса или false в config.yaml. Отключайте осознанно: защита включена по умолчанию.