Руководство администратора Mockarty

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

URL-адреса в примерах: Во всех примерах используется localhost:5770 как адрес Mockarty по умолчанию. Если ваш экземпляр работает на удалённом сервере, замените localhost:5770 на реальный адрес (например, https://mockarty.company.com или http://192.168.1.50:5770). Подробнее — в разделе Полезные функции и советы.

Содержание

1. Первый запуск
2. Публичный URL для внешних ссылок
3. Настройка аутентификации
4. Управление пользователями
5. Системные роли
6. Управление пространствами имён
7. Роли в пространстве имён
8. Назначение пользователей в пространства имён
9. Настройка уведомлений по электронной почте
10. Резервное копирование и восстановление
11. Политики очистки
12. Журнал аудита
13. Диагностический пакет
14. Настройка LLM / AI-ассистента
15. Рекомендации по безопасности

Первый запуск

При первом запуске Mockarty автоматически выполняются следующие действия:

• Миграции базы данных — создаются все необходимые таблицы и индексы.
• Создаётся пространство имён по умолчанию с названием sandbox.
• Создаётся встроенная учётная запись администратора со стандартными учётными данными.

Если настройка задана неверно — например, порт вне диапазона 1–65535, DB_USE не pg и не sqlite, CACHE_TYPE=redis без REPO_REDIS_HOST или CLUSTER_MODE=true вместе с SQLite, — Mockarty не запускается. В сообщении при запуске названы переменная и допустимые значения: исправьте эту строку и запустите снова.

Учётные данные по умолчанию

Внимание: Смените пароль по умолчанию сразу после первого входа. Использование стандартных учётных данных в продакшене — критическая угроза безопасности.

Пробная лицензия: При первом запуске Mockarty работает с 7-дневной пробной лицензией. Ограничения пробной версии: небольшой пул мест на каждую функцию (3 места для базовых функций — мокирование и тестирование API, меньше для продвинутых) и доступно только пространство имён sandbox. Для разблокировки полных возможностей примените лицензионный ключ в разделе Администрирование → Лицензия.

Доступ к веб-интерфейсу

Откройте браузер и перейдите по адресу:

http://localhost:5770/ui/

Вы увидите страницу входа. Введите учётные данные по умолчанию для авторизации.

Вход и изменение учётной записи защищены от частых повторных запросов. Если
запрос вернул 429, перед повтором подождите время из заголовка Retry-After.
После входа обычная навигация и проверка сессии не расходуют лимит анонимного
входа. Лимиты API-токенов продолжают действовать.

Смена пароля по умолчанию

1. Войдите с учётными данными admin / admin.
2. Перейдите в Настройки (значок шестерёнки в боковой панели).
3. Откройте раздел Профиль.
4. Нажмите Изменить пароль.
5. Введите новый надёжный пароль (минимум 8 символов).
6. Нажмите Сохранить.

Публичный URL для внешних ссылок (MOCKARTY_PUBLIC_URL)

Mockarty формирует абсолютные ссылки, которые открывает не тот, кто кликает внутри приложения, — и эти ссылки должны вести на host, куда получатель реально может достучаться:

• ссылки в письмах и уведомлениях мессенджера,
• ссылки-инвайты в комнаты агентов, которые вы передаёте коллеге,
• ссылки на встречу в календарном файле (.ics),
• подключение устройств companion (QR / сигнальный релей) для телефонов,
• ссылки на скачивание мобильного приложения и браузерного расширения.

За обратным прокси, Ingress или в Kubernetes собственный request-host сервера — это внутренний адрес (например 127.0.0.1:5770 или IP пода в кластере), и ссылка из него недостижима снаружи. Задайте MOCKARTY_PUBLIC_URL равным URL, который ваши пользователи вводят в браузере, — все ссылки будут использовать его.

MOCKARTY_PUBLIC_URL=https://mockarty.example.com

Примечания:

• Если не задано, Mockarty берёт host входящего запроса и учитывает заголовки обратного прокси X-Forwarded-Host / X-Forwarded-Proto — то есть правильно настроенный прокси, пробрасывающий их, может работать и без этой переменной. В Kubernetes, где request-host — внутрикластерный адрес и forwarded-host отсутствует, задание этой переменной — единственный надёжный способ получить корректные ссылки.
• MOCKARTY_ADVERTISE_URL и PUBLIC_BASE_URL принимаются как псевдонимы (выигрывает первое непустое из трёх).
• На старте Mockarty пишет предупреждение в лог, если публичный базовый URL не настроен, — ссылки в уведомлениях будут недостижимы для получателей.

Настройка аутентификации

Mockarty поддерживает несколько методов аутентификации. Базовые настройки аутентификации задаются переменными окружения, а внешние провайдеры идентификации (OAuth, LDAP) настраиваются через веб-интерфейс панели администратора с поддержкой hot-reload — перезапуск не требуется.

Основные понятия

Если вы не знакомы с терминологией аутентификации, ниже приведены краткие определения:

• OAuth 2.0 — стандартный протокол, позволяющий пользователям входить в Mockarty с использованием существующих аккаунтов внешних сервисов (Google, GitHub и т. д.) вместо создания отдельного пароля. Кнопки «Войти через Google» — это и есть OAuth.
• LDAP / Active Directory — служба каталогов, которая часто применяется в корпоративных средах для централизованного хранения учётных записей. Если в вашей компании используется доменный вход Windows, скорее всего, это Active Directory, работающая по протоколу LDAP.
• SAML — корпоративный протокол Single Sign-On (SSO), используемый сервисами вроде Okta, Azure AD и OneLogin. Позволяет пользователю войти один раз и получить доступ ко множеству приложений без повторного ввода учётных данных.
• RBAC — управление доступом на основе ролей. Вместо назначения прав отдельным пользователям им выдают роли (например, Owner, User, Viewer), и каждая роль имеет заранее определённый набор разрешений.
• 2FA / MFA — двух- или многофакторная аутентификация. После ввода пароля пользователь должен предоставить второе подтверждение — например, код из приложения-аутентификатора или электронной почты.

Режим аутентификации (AUTH_MODE)

Переменная окружения AUTH_MODE управляет общей стратегией аутентификации:

Установите переменную в окружении или .env файле:

AUTH_MODE=full   # по умолчанию, многопользовательский серверный режим
AUTH_MODE=local  # однопользовательский режим (без экрана входа)

Базовый URL для OAuth-редиректов (AUTH_BASE_URL)

При использовании OAuth-провайдеров Mockarty должен знать свой публичный URL, чтобы корректно формировать redirect URI (адрес, на который провайдер возвращает пользователя после входа).

AUTH_BASE_URL=https://mockarty.yourcompany.com

Важно: Если AUTH_BASE_URL не совпадает с redirect URI, зарегистрированным у OAuth-провайдера, авторизация завершится с ошибкой «redirect_uri_mismatch».

Первый администратор

При первом запуске Mockarty создаёт учётную запись администратора с использованием следующих переменных окружения:

Если используются стандартные учётные данные admin/admin, система потребует сменить пароль при первом входе.

Совет: Для автоматизированных развёртываний задайте собственные значения, чтобы избежать запроса смены пароля:

FIRST_ADMIN_LOGIN=myadmin
FIRST_ADMIN_PASSWORD=MyStr0ngP@ssword!
FIRST_ADMIN_EMAIL=admin@yourcompany.com

Время жизни сессии (AUTH_SESSION_EXPIRATION)

Контролирует, как долго длится сессия пользователя до повторной аутентификации:

AUTH_SESSION_EXPIRATION=48          # сессии живут 2 дня
AUTH_SESSION_SLIDING=true           # активные пользователи остаются в системе
AUTH_SESSION_ABSOLUTE_MAX_HOURS=168 # ...но релогин принудительно через 7 дней

Локальная аутентификация (по умолчанию)

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

Требования к паролям:

• Минимум 8 символов

Настройка OAuth 2.0

OAuth 2.0 позволяет пользователям входить с использованием существующих аккаунтов внешних сервисов вместо создания отдельного пароля Mockarty. Mockarty поддерживает следующих OAuth-провайдеров:

• Google
• Yandex
• VK
• GitHub
• GitLab
• Generic / Custom OAuth — любой провайдер, совместимый с OAuth 2.0

Настройка OAuth-провайдеров через панель администратора

Все OAuth-провайдеры настраиваются через веб-интерфейс панели администратора. Переменные окружения для отдельных провайдеров не требуются.

1. Перейдите в Панель администратора > Identity Providers.
2. Нажмите Add Identity Provider.
3. Выберите тип провайдера (например, Google, GitHub, GitLab, Generic).
4. Заполните обязательные поля:
   • Client ID — получен из консоли разработчика провайдера.
   • Client Secret — получен из консоли разработчика провайдера.
   • Для Generic/Custom провайдеров дополнительно нужно указать: Authorization URL, Token URL, UserInfo URL и Scopes.
5. Включите переключатель Enabled для активации провайдера.
6. Нажмите Save.

Hot-reload: Изменения вступают в силу немедленно. После добавления, изменения или удаления провайдера перезапуск Mockarty не требуется.

Redirect URI: При регистрации приложения в консоли разработчика провайдера используйте следующий redirect URI:

{AUTH_BASE_URL}/api/v1/auth/oauth/callback

Например: https://mockarty.yourcompany.com/api/v1/auth/oauth/callback

Когда OAuth-провайдеры включены, на странице входа автоматически появляются кнопки «Войти через…» для каждого активного провайдера.

LDAP / Active Directory

LDAP (Lightweight Directory Access Protocol) позволяет Mockarty аутентифицировать пользователей через существующий каталог пользователей вашей организации, например Microsoft Active Directory. Это значит, что пользователи могут входить с теми же учётными данными, которые используют для корпоративной сети.

Настройка LDAP через панель администратора

LDAP настраивается через веб-интерфейс панели администратора, аналогично OAuth-провайдерам.

1. Перейдите в Панель администратора > Identity Providers.
2. Нажмите Add Identity Provider.
3. Выберите тип LDAP / Active Directory.
4. Заполните параметры подключения:
   • LDAP URL — адрес сервера каталога (например, ldap://ldap.example.com:389 или ldaps://ldap.example.com:636 для TLS).
   • Base DN — отправная точка для поиска пользователей (например, dc=example,dc=com).
   • Bind DN — учётная запись, используемая для подключения и поиска в каталоге (например, cn=admin,dc=example,dc=com).
   • Bind Password — пароль учётной записи bind.
   • User Filter — LDAP-фильтр для поиска пользователей. Используйте %s как плейсхолдер для логина (например, (sAMAccountName=%s) для Active Directory, (uid=%s) для OpenLDAP).
5. Нажмите Test Connection, чтобы проверить, что Mockarty может подключиться к серверу каталога и аутентифицироваться с учётной записью bind.
6. Включите переключатель Enabled и нажмите Save.

Hot-reload: Как и OAuth, изменения настроек LDAP вступают в силу немедленно без перезапуска Mockarty.

Когда LDAP включён, пользователи могут входить с учётными данными каталога. При первом входе автоматически создаётся учётная запись Mockarty с системной ролью User. Затем администратор может назначить роли в пространствах имён по необходимости.

SAML SSO

Mockarty поддерживает SAML 2.0 для интеграции Single Sign-On с корпоративными провайдерами идентификации (Okta, Azure AD, OneLogin и т. д.).

Настройка выполняется через панель администратора:

1. Перейдите в Панель администратора > Authentication > SAML.
2. Загрузите или вставьте XML метаданных провайдера идентификации (IdP).
3. Скопируйте URL метаданных Service Provider (SP) Mockarty и зарегистрируйте его в вашем IdP.
4. Настройте сопоставление атрибутов (email, отображаемое имя, группы).
5. Включите SAML-аутентификацию.

Двухфакторная аутентификация (2FA)

Mockarty поддерживает два типа двухфакторной аутентификации:

TOTP (одноразовые пароли на основе времени):

• Работает с любым приложением-аутентификатором (Google Authenticator, Authy, Microsoft Authenticator и т. д.).
• Пользователи включают её в Settings > Security > Two-Factor Authentication.
• Отображается QR-код для сканирования приложением-аутентификатором.
• Предоставляются коды восстановления для резервного доступа.

Коды по электронной почте:

• Одноразовые коды отправляются на зарегистрированный email пользователя.
• Требуется настроенная отправка email (см. Настройка уведомлений по электронной почте).
• Пользователи включают её в Settings > Security > Two-Factor Authentication.

Управление 2FA для пользователей:

Администраторы могут управлять 2FA для каждого пользователя отдельно:

• Отключить 2FA для пользователя: Перейдите в Панель администратора > Users, выберите пользователя и нажмите Disable 2FA. Это удалит как TOTP, так и email 2FA для данного пользователя.
• Рекомендация: Настоятельно рекомендуется (либо обяжите через организационную политику), чтобы все пользователи с ролями Admin и Support включили 2FA для своих учётных записей.

Примечание: 2FA включается самими пользователями в разделе Settings > Security > Two-Factor Authentication. Глобального переключателя принудительного включения нет — внедрение 2FA управляется через организационную политику.

Управление пользователями

Создание пользователей

1. Перейдите в Панель администратора > Users.
2. Нажмите Create User.
3. Заполните обязательные поля:
   • Username — уникальный логин.
   • Email — адрес электронной почты (используется для уведомлений и сброса пароля).
   • Password — начальный пароль (пользователь сможет изменить его позже).
   • System Role — выберите Admin, Support, Auditor или User (см. Системные роли).
4. Нажмите Create.

Приглашение пользователей

Вместо того чтобы придумывать пароль за человека, пригласите его — он настроит вход сам.

Если сменить язык интерфейса в открытом окне приглашения, подписи обновятся, а email, выбранные роли и пространство имён сохранятся.

1. Откройте Панель администратора > Пользователи и нажмите Пригласить.
2. Укажите email и системную роль. При желании выберите пространство имён и роль в нём — участник, наблюдатель или владелец.
3. Нажмите Отправить приглашение. Если отправка почты настроена, письмо уходит сразу. Окно также показывает ссылку-приглашение — скопируйте её и передайте сами, если установка не отправляет почту.

Человек открывает ссылку, видит, кто и с какими ролями его пригласил, выбирает логин и пароль — и сразу входит в систему. Каждая ссылка срабатывает один раз и действует три дня. В разделе Ожидающие приглашения под таблицей пользователей видны только действующие ссылки, которые ещё не приняты и не отозваны (до 200, сначала новые); кнопка Отозвать отключает ссылку.

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

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

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

Установка паролей и email

• Для сброса пароля пользователя: Панель администратора > Users > (выберите пользователя) > Reset Password.
• Для смены email пользователя: Панель администратора > Users > (выберите пользователя) > Edit > Email.
• Ссылки для сброса пароля могут отправляться по email, если настроены email-уведомления.

Отключение / включение учётных записей

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

1. Перейдите в Панель администратора > Users.
2. Найдите пользователя в списке.
3. Нажмите переключатель рядом с его именем для отключения или включения учётной записи.

Удаление пользователей

1. Перейдите в Панель администратора > Users.
2. Найдите пользователя в списке.
3. Нажмите Delete.
4. Подтвердите удаление.

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

Самостоятельная регистрация пользователей

Когда включены OAuth или LDAP, пользователи могут регистрироваться самостоятельно, входя через внешний провайдер идентификации. Учётная запись Mockarty создаётся автоматически с системной ролью User. Затем администратор может назначить роли в пространствах имён по необходимости.

Системные роли

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

Описание ролей

Admin
Полный доступ к системе. Администраторы могут управлять всеми пользователями, всеми пространствами имён, системными настройками, журналами аудита, резервными копиями, настройками email, профилями LLM, телеметрией и состоянием базы данных. Эта роль должна быть выдана небольшому числу доверенных лиц.

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

Auditor
Доступ только для чтения к журналам аудита и системным метрикам. Аудиторы не могут изменять ресурсы и не могут экспортировать журналы аудита. В боковой панели они видят: Dashboard, Mocks (только просмотр), Test Runs, Recorder (только просмотр), Fuzzing (только просмотр), Utils, Settings (только просмотр) и Admin Panel (только просмотр журналов аудита).

User
Стандартная учётная запись пользователя. Права полностью определяются назначениями ролей в пространствах имён (см. Роли в пространстве имён). Доступа к панели администратора нет.

Матрица разрешений

Управление пространствами имён

Что такое пространство имён

Пространство имён — это изолированная рабочая область внутри Mockarty. Каждое пространство имён содержит собственные:

• Моки и маршруты
• Хранилища Global, Chain и Mock
• Коллекции API-тестов и окружения
• Результаты запусков тестов
• Сессии рекордера
• Конфигурации фаззинга
• API-токены

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

Создание пространств имён

Через панель администратора:

1. Перейдите в Панель администратора > Namespaces.
2. Нажмите Create Namespace.
3. Введите имя и (опционально) описание.
4. Нажмите Create.

Через страницу настроек:

1. Перейдите в Settings > Namespaces (доступно пользователям с ролью Admin).
2. Нажмите Create Namespace.
3. Введите имя и (опционально) описание.
4. Нажмите Create.

Соглашения об именовании и лучшие практики

Выберите соглашение об именовании, подходящее вашей организации:

Советы:

• Используйте имена в нижнем регистре с дефисами (например, user-service).
• Делайте имена короткими, но информативными.
• Избегайте общих имён вроде test или temp для постоянных пространств имён.
• Задокументируйте соглашение об именовании, чтобы все команды следовали ему единообразно.

Пространство имён по умолчанию

Пространство имён sandbox создаётся автоматически при первом запуске. Его нельзя удалить. Все пользователи имеют доступ к пространству имён по умолчанию, если их явно не исключили.

Удаление / восстановление пространств имён

1. Перейдите в Панель администратора > Namespaces.
2. Найдите пространство имён и нажмите Delete.
3. Подтвердите удаление.

Закрытие пространства имён деактивирует его ресурсы. Чтобы открыть его снова, нажмите Restore в списке пространств имён.

Безвозвратное удаление через корзину или API администратора отменить нельзя. Оно также ставит в очередь удаление сохранённых файлов управления тест-кейсами и артефактов тест-планов; при временной недоступности хранилища очистка продолжится после перезапуска сервера. Пространство с файлами под legal hold или с действующим сроком хранения безвозвратно удалить нельзя.

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

API администратора использует DELETE /api/v1/admin/namespaces/{namespace}?hard=true; для роли поддержки доступен соответствующий маршрут /api/v1/support/namespaces/{namespace}. Если удаление запрещено из-за удержания файлов, срока хранения или изменения namespace во время операции, API возвращает 409. Ошибка базы данных возвращает 500. Успешное удаление возвращает 200; очистка сохранённых файлов может продолжаться после ответа.

Роли в пространстве имён

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

Описание ролей

Owner
Полный контроль над пространством имён. Владельцы могут управлять настройками пространства, добавлять и удалять пользователей и выполнять все операции с ресурсами (моки, хранилища, коллекции, тесты). Владельцы пространства имён не могут удалить пространство имён — это доступно только пользователям с системной ролью Admin или Support.

User
Могут создавать, редактировать и удалять моки, хранилища, коллекции и запускать тесты. Не могут управлять настройками пространства или добавлять/удалять пользователей.

Viewer
Доступ только для чтения ко всем ресурсам пространства имён. Наблюдатели могут просматривать моки, результаты тестов и значения хранилищ, но не могут создавать, редактировать или удалять что-либо.

Матрица возможностей в пространстве имён

Назначение пользователей в пространства имён

Добавление пользователя в пространство имён

1. Переключитесь в целевое пространство имён с помощью селектора в боковой панели.
2. Перейдите в Settings > Users.
3. Нажмите Add User.
4. Выберите учётную запись из выпадающего списка.
5. Выберите роль: Owner, User или Viewer.
6. Нажмите Add.

Клиентские пространства имён наследуют роли

Интеграции, которые подключают свои продукты (например, система приёмки), создают по одному пространству имён на продукт с именем c-<client>-p-<project>. Добавлять пользователя в каждое из них не нужно: роль, выданная в родительском клиентском пространстве c-<client>, действует во всех c-<client>-p-* с той же ролью. Если пользователю выдана отдельная роль в продуктовом пространстве, она имеет приоритет.

Пример: выдайте сервисной учётной записи интеграции роль Viewer в c-acme, и она сможет читать c-acme-p-web, c-acme-p-checkout и любое продуктовое пространство, которое интеграция создаст позже, без отдельной выдачи.

Изменение роли пользователя в пространстве имён

1. Перейдите в Settings > Users в целевом пространстве имён.
2. Найдите пользователя в списке.
3. Нажмите выпадающий список роли рядом с его именем.
4. Выберите новую роль.
5. Изменение вступает в силу немедленно.

Удаление пользователя из пространства имён

1. Перейдите в Settings > Users в целевом пространстве имён.
2. Найдите пользователя в списке.
3. Нажмите Remove.
4. Подтвердите действие.

Примечание: Удаление пользователя из пространства имён не удаляет его учётную запись. Он просто теряет доступ к ресурсам этого пространства.

Настройка уведомлений по электронной почте

Email-уведомления используются для сброса паролей, доставки кодов 2FA, пригласительных ссылок и уведомлений о результатах тестов.

Включение email

Настройки email задаются через веб-интерфейс панели администратора (перезапуск не требуется):

1. Перейдите в Панель администратора > Email Settings.
2. Заполните параметры подключения SMTP:
   • SMTP Host — ваш SMTP-сервер (например, smtp.gmail.com)
   • SMTP Port — обычно 587 для STARTTLS или 465 для Implicit TLS
   • Username / Password — учётные данные SMTP-аутентификации
   • From Address — адрес отправителя, отображаемый получателям
   • From Name — имя отправителя (например, Mockarty)
   • Reply-To — необязательный адрес для ответов
3. Включите переключатель Enabled и нажмите Save.

Альтернатива: переменные окружения. Настройки SMTP также можно задать через переменные окружения при запуске (EMAIL_ENABLED, SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, EMAIL_FROM, EMAIL_FROM_NAME, EMAIL_REPLY_TO, SMTP_USE_IMPLICIT_TLS). Полный справочник — в Руководстве по установке и развёртыванию. Настройки в UI имеют приоритет над переменными окружения после первого сохранения.

Проверка настроек email

1. Перейдите в Панель администратора > Email Settings.
2. Нажмите Send Test Email.
3. Введите адрес получателя.
4. Нажмите Send.
5. Убедитесь, что тестовое письмо пришло в почтовый ящик получателя.

Пользовательские шаблоны писем

Mockarty использует встроенные HTML-шаблоны для всех email-уведомлений. Их можно настроить:

1. Перейдите в Панель администратора > Email, затем переключитесь на под-вкладку Templates.
2. Выберите шаблон для настройки (например, «Password Reset», «2FA Code», «Welcome», «Invite», «Email Verify»).
3. Отредактируйте тему, HTML-шаблон и текстовый шаблон. Доступные переменные перечислены на странице.
4. Нажмите Save.
5. Используйте Preview для просмотра внешнего вида письма.
6. Используйте Reset to Default для восстановления встроенного шаблона.

Что отправляется

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

В Mockarty встроена система резервного копирования, использующая pg_dump / pg_restore для PostgreSQL и согласованный снимок базы для SQLite, чтобы создавать и восстанавливать резервные копии БД. Управление выполняется через панель администратора или API. Эти копии содержат базу данных; полное резервное копирование узла для аварийного восстановления описано в разделе Резервное копирование и восстановление.

Опциональный режим PostgreSQL с минимальными привилегиями

По умолчанию Mockarty сохраняет обратно совместимое поведение запуска и применяет ожидающие миграции через DB_DSN. Для усиленной установки нужны выделенная база Mockarty, maintenance credential владельца схемы, serving-роль и, если включается управление delivery policy, отдельная non-owner authority-роль. Выполните переход в таком порядке:

1. Задайте стабильный CHAOS_ENCRYPTION_KEY до смены учётных данных БД. Так ранее сохранённые chaos-credentials останутся читаемыми после смены DSN.
2. Создайте runtime- и authority-роли с атрибутами NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE NOINHERIT NOREPLICATION, без memberships и принадлежащих им объектов БД. Не выдавайте им управление параметрами, replication, DDL или default privileges.
3. В первом одноразовом maintenance-проходе оставьте DB_AUTHORITY_ROLE пустым, задайте DB_DSN будущего runtime-подключения, DB_RUNTIME_ROLE с именем serving-роли и DB_MIGRATION_DSN с DSN владельца схемы. Запустите ./mockarty --migrate up без --migrate-steps.
4. От имени администратора БД удалите эффективный доступ PUBLIC к выделенной базе и всем non-system application schemas и objects: database CONNECT/TEMP, создание схем, tables, sequences, functions, types, procedural languages, parameters, foreign-data objects, tablespaces и large objects. Для схемы public оставьте только USAGE. Настройте database-wide default privileges владельца миграций так, чтобы будущие functions не давали EXECUTE, а будущие types — USAGE роли PUBLIC. Явно выдайте database CONNECT runtime- и authority-ролям. Не применяйте этот strict-профиль в БД, совместно используемой другим приложением.
5. Повторите ./mockarty --migrate up с тем же owner credential и добавьте DB_AUTHORITY_ROLE. Даже если ожидающих миграций нет, maintenance-команда вызывает оба owner-only grant binder и завершится с ошибкой, если dedicated-database posture подготовлен не полностью.
6. Полностью удалите DB_MIGRATION_DSN из serving-окружения. Запустите serving-процесс с runtime DB_DSN, DB_RUNTIME_ROLE и стабильным CHAOS_ENCRYPTION_KEY. Чтобы включить управление delivery policy, задайте authority credential парой DB_AUTHORITY_DSN и DB_AUTHORITY_ROLE; его DSN должен устанавливать session search_path точно в pg_catalog,public,pg_temp.

Для production Compose задайте runtime-подключение в MOCKARTY_RUNTIME_DB_DSN; встроенный POSTGRES_USER остаётся владельцем БД и не должен использоваться как DB_RUNTIME_ROLE. Сначала создайте runtime-роль своим административным процессом PostgreSQL. Strict mode — это явный operator cutover, а не автоматическое создание роли.

Serving-процесс завершает запуск с ошибкой, если любая настроенная роль может владеть или создавать объекты схемы, имеет membership, replication или parameter authority, если изменились PUBLIC, default или критические права и объекты схемы, если runtime-, authority- и migration-обязанности используют общие credentials либо owner-подключение маскируется через SET ROLE. Оставьте обе authority-переменные пустыми, чтобы управление было недоступно без отключения runtime policy enforcement. DB_MIGRATION_DSN намеренно запрещён в serving-процессе и не должен храниться в serving Pod, Compose-сервисе или systemd environment.

В SQLite нет разделения PostgreSQL-ролей. Поэтому единственный локальный процесс и владелец файла БД входят в доверенную локальную границу; PostgreSQL authority-переменные в SQLite-режиме задавать нельзя. Legacy PostgreSQL сохраняет такую же owner-trust совместимость через существующее подключение.
Владелец PostgreSQL-миграций также является доверенной maintenance authority: по определению он может менять объекты схемы и триггеры. Строгая гарантия защищает обычную serving-роль от этих возможностей, но не заявляет защиту от скомпрометированного migration owner.

Автоматическое резервное копирование

Mockarty автоматически выполняет резервное копирование по расписанию. Расписание по умолчанию — ежедневно в 2:00 ночи (настраивается через cron-выражение). В распределённых развёртываниях резервное копирование выполняется только на лидер-ноде во избежание дублирования.

Настройка резервного копирования

1. Перейдите в Панель администратора > Backup.
2. Нажмите Create Backup Config (или отредактируйте конфигурацию по умолчанию).
3. Настройте:
   • Schedule — cron-выражение (например, 0 0 2 * * * для ежедневного запуска в 2:00).
   • Retention — число дней хранения старых копий (0 = без ограничений).
   • Compression — включить сжатие для уменьшения размера файлов.
   • Format — custom (рекомендуется, поддерживает pg_restore), plain (текстовый SQL), tar или directory.
   • Include schema / Include data — выбрать, что включать.
4. Включите переключатель Enabled и нажмите Save.

Ручное резервное копирование

Через панель администратора:

1. Перейдите в Панель администратора > Backup.
2. Нажмите Create Backup.
3. Дождитесь завершения процесса.
4. Нажмите Download для сохранения файла резервной копии.

Через API:

# Create a backup
curl -X POST http://localhost:5770/api/v1/admin/backups/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config_id": "your-config-id"}'

# Download the backup
curl http://localhost:5770/api/v1/admin/backups/download?file_path=backup_file.dump \
  -H "Authorization: Bearer $TOKEN" \
  -o backup.dump

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

В режиме по умолчанию восстановление доступно, как описано ниже. В строгом PostgreSQL-режиме (задан DB_RUNTIME_ROLE) restore-endpoints намеренно не регистрируются: serving-роль не может заменять схему или содержимое БД. Остановите трафик, выполните восстановление как явную maintenance-операцию с owner credential, проверьте восстановленную схему, повторно примените полную цепочку миграций и только затем запускайте процесс с runtime-ролью. Не добавляйте owner credential в работающий сервер ради доступности кнопки.

Через панель администратора:

1. Перейдите в Панель администратора > Backup.
2. Нажмите Restore.
3. Загрузите файл резервной копии.
4. Подтвердите операцию восстановления.
5. Дождитесь завершения процесса. Кэш лицензий будет перезагружен автоматически.

Через API:

# Restore from uploaded file
curl -X POST http://localhost:5770/api/v1/admin/backups/restore-from-file \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@backup.dump"

Внимание: Восстановление заменяет все текущие данные. Эта операция необратима.

Что входит в резервную копию

• Полная база данных (все моки, хранилища, пользователи, пространства имён, результаты тестов, журналы аудита, конфигурации)
• Формат зависит от настроек (рекомендуется формат custom для самого быстрого восстановления)

Docker и Kubernetes

Официальный Docker-образ Mockarty включает клиентские инструменты PostgreSQL 18 (pg_dump, pg_restore, psql), поэтому резервное копирование работает из коробки в Docker- и Kubernetes-окружениях для серверов PostgreSQL до версии 18 включительно.

Смонтируйте постоянный том для каталога резервных копий:

docker run -v /host/path/data:/app/data mockarty:latest

Резервное копирование SQLite

Для развёртываний с SQLite Mockarty делает согласованный снимок базы — это безопасно, пока люди продолжают работать. Используется тот же интерфейс панели администратора — дополнительные инструменты не требуются.

Работающий узел не может заменить файл SQLite, с которым работает, поэтому резервная копия SQLite восстанавливается при остановленном сервисе: скачайте файл копии, остановите Mockarty, выполните mockarty --restore <файл копии> с теми же настройками, что у сервера, и снова запустите Mockarty. Прежняя база сохраняется рядом.

Полное резервное копирование для аварийного восстановления — база, вложения и файлы отчётов, с проверкой ключей шифрования при восстановлении — описано в разделе Резервное копирование и восстановление.

Диагностический пакет

Если что-то работает не так и вы обращаетесь в поддержку, скачайте диагностический пакет: панель администратора → Настройки (статус системы и логи) → «Скачать диагностический пакет». Кнопка доступна только администраторам.

В архиве:

Архив никогда не содержит пароли, токены, API-ключи и строки подключения к базе. Каждое скачивание фиксируется в журнале аудита.

Показатели пула относятся только к узлу, создавшему архив. В кластере скачайте пакет с каждого затронутого узла и сравните его с метриками по узлам на обзорном дашборде. Максимум пула 0 означает отсутствие заданного лимита подключений, поэтому долю занятых соединений для него не вычислить. На дашборде также показаны ошибки записи в кэш и ограниченная выборка audit outbox; насыщение выборки не является точным размером очереди. После смены лидера, ошибки чтения или 90 секунд без нового замера выборка скрывается; если пропали все выборки, проверьте часы узлов.

Тот же архив доступен через API:

curl -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -o support-bundle.zip \
  http://localhost:5770/api/v1/admin/support-bundle

Политики очистки

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

Настройка очистки

Перейдите в Панель администратора > Cleanup или Settings > Cleanup внутри пространства имён.

Доступные политики

Варианты обработки истёкших моков:

• Архивировать — пометить истёкшие моки как неактивные. Они перестают сопоставляться с запросами, но остаются видимыми в интерфейсе для справки.
• Автоудаление — окончательно удалять истёкшие моки после настраиваемого льготного периода.
• Ничего не делать — оставить истёкшие моки как есть (не рекомендуется для продакшена).

Журнал аудита

Журнал аудита ведёт подробную запись всех значимых действий, выполненных в системе.

Что регистрируется

• События аутентификации — входы пользователей (успешные и неудачные), выходы, запросы 2FA.
• Операции с моками — создание, обновление, удаление, импорт, экспорт.
• Изменения пространств имён — создание, удаление, назначения ролей пользователей.
• Административные действия — управление пользователями, изменение системных настроек, резервное копирование/восстановление.
• Использование API-токенов — создание, удаление и паттерны использования токенов.
• Операции с хранилищами — изменения в Global-хранилище.

Просмотр журнала аудита

1. Перейдите в Панель администратора > Audit Logs.
2. Просматривайте хронологический список событий.

Фильтрация

Используйте элементы управления фильтрацией в верхней части страницы:

• User — фильтр по конкретной учётной записи.
• Event type — фильтр по типу действия (login, mock.create, namespace.delete и т. д.).
• Date range — задать начальную и конечную дату.
• Namespace — фильтр по пространству имён (для событий, связанных с пространством).

Экспорт журнала аудита

1. Примените нужные фильтры.
2. Нажмите Export.
3. Выберите формат:
   • CSV — значения, разделённые запятыми, удобно для анализа в электронных таблицах.
   • JSON — структурированные данные, удобно для программной обработки.
4. Файл загружается в браузер.

Настройка LLM / AI-ассистента

Mockarty включает AI-ассистента (Agent Chat), помогающего пользователям создавать моки, диагностировать проблемы и исследовать систему на естественном языке.

Включение AI-ассистента

Установите следующую переменную окружения:

ENABLE_LLM=true

MCP-сервер

Если вы хотите предоставить инструменты Mockarty через MCP (Model Context Protocol) для внешних AI-агентов, включите встроенный MCP-сервер:

ENABLE_MCP=true

Параллелизм агента

Подсистема AI-агента (ADK) управляет тем, сколько задач агента могут выполняться одновременно и как долго живут сессии:

Задайте эти переменные до запуска admin-узла и перезапустите узел после изменения. Если хотя бы одно значение имеет неверный формат, выходит за допустимый диапазон или таймаут простоя не меньше общего таймаута, Mockarty применяет оба безопасных значения по умолчанию (180 и 90). Более короткий таймаут вызывающей операции по-прежнему имеет приоритет.

Конфигурация по умолчанию

При включении без дополнительной настройки Mockarty подключается к локальному экземпляру Ollama:

Локальная Ollama (для разработчиков)

Ollama позволяет запускать open-source LLM локально. Это удобно для разработки и тестирования, когда не нужно использовать облачный LLM-провайдер.

Установка Ollama:

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

Запуск Ollama и загрузка модели:

# Start the Ollama server
ollama serve &

# Pull a model (choose size based on available RAM)
ollama pull qwen3:0.6b   # ~1 GB RAM — smallest, fast
ollama pull qwen3:1.7b   # ~2 GB RAM — вариант с большей моделью
ollama pull qwen3:4b     # ~3.5 GB RAM — better quality

Настройка Mockarty для работы с Ollama:

Установите ENABLE_LLM=true и создайте профиль Ollama в Панели администратора > LLM Profiles со следующими параметрами:

• Provider: Ollama
• URL: http://localhost:11434
• Model: загруженная вами модель (например, qwen3:1.7b)

Альтернативно — передайте URL и модель Ollama как переменные окружения при запуске. Они служат значениями по умолчанию, если профиль LLM не настроен:

ENABLE_LLM=true OLLAMA_URL=http://localhost:11434 OLLAMA_MODEL=qwen3:1.7b ./mockarty

Примечание: Для продакшена настраивайте провайдеров LLM через панель администратора. Переменные OLLAMA_URL и OLLAMA_MODEL — это удобные значения по умолчанию, которые переопределяются активным профилем LLM.

Настройка профилей LLM

Через панель администратора можно настроить несколько профилей LLM:

1. Перейдите в Панель администратора > LLM Profiles.
2. Нажмите Create Profile.
3. Заполните:
   • Name — отображаемое имя профиля.
   • Provider — OpenAI, Anthropic (Claude), OpenRouter, Google (Gemini), Mistral, Groq, Ollama (локальный) или Custom (любой OpenAI-совместимый эндпоинт).
   • URL — URL API-эндпоинта.
   • API Key — ключ аутентификации (если требуется провайдером).
   • Model — идентификатор модели.
4. Нажмите Save.
5. Установите один профиль как Default для всех пользователей.

Потребление ИИ и процессов

Откройте Admin → AI & LLM → Потребление, чтобы посмотреть вызовы LLM,
надёжно сохранённые диспатчи инструментов агентов и время завершённых
runner-задач с группировкой по профилю, пространству имён, пользователю,
агенту, продукту, миссии, компоненту, исходу или модулю.
Стоимость провайдера и стоимость для клиента показываются отдельно по каждой
валюте. События без действующей цены остаются в отчёте и считаются как События
без цены: Mockarty не подставляет нулевую стоимость и не смешивает валюты.

Прайсбук хранит неизменяемые версии с датой вступления в силу. Укажите
провайдера, модель, трёхбуквенный код валюты, дату и цены входа, выхода, чтения и
записи кеша за один миллион токенов. Модель * задаёт резервную цену для всего
провайдера. Для исправления тарифа добавьте новую версию с правильной датой —
историческая версия и уже зафиксированные снимки цен не изменяются.

Та же форма тарифицирует реальные ресурсы процесса. Для Вызовов инструментов
укажите провайдер mockarty-agent и имя инструмента, например run_api_test
(или * как резервный тариф). Для Секунд раннера укажите mockarty-runner и тип
runner-задачи (или *). Стоимость провайдера и цена для клиента задаются за вызов или
секунду работы раннера; интерфейс автоматически выбирает нужную единицу.

Цены вводятся в обычных единицах валюты (например, 0.15 USD за миллион
токенов). Поддерживается шесть знаков после запятой. Перед сохранением новой
версии тарифа проверьте сумму и валюту в интерфейсе.

Учёт хранилища и трафика

Кроме токенов, вызовов инструментов и времени раннеров Mockarty учитывает два
физических ресурса по каждому пространству:

• Байт-секунды хранилища — раз в час замеряется объём хранимых файлов
  пространства (вложения, артефакты, записи) и записывается в байт-секундах:
  один байт, хранившийся час, — это 3600 байт-секунд. В кластере замер делает
  ровно один узел, поэтому ничего не считается дважды.
• Исходящие байты — исходящий трафик, отданный админ-узлом, агрегируется
  поминутными окнами. Колонка resource различает источник: proxy — байты
  ответов, которые проксирующий мок отдал своим клиентам, blob-download —
  скачивания файлов. В кластере каждый админ-узел записывает свои байты, а
  колонка узла в выписке показывает, кто их отдал. Трафик выделенных
  resolver-узлов не учитывается.

Оба ресурса видны в итогах панели Потребление и в экспорте
mockarty economics statement (event_kind storage_byte_seconds /
egress_bytes, unit byte_seconds / bytes). Чтобы назначить тариф,
выберите в форме прайс-листа Байт-секунды хранилища или Исходящие
байты, оставьте провайдера mockarty и укажите ресурс — blobs для
хранилища; proxy, blob-download или * для трафика. События без тарифа
остаются видимыми и никогда не тарифицируются нулём.

Учёт включён по умолчанию и практически бесплатен (наносекунды на запрос).
Полностью выключить его — например, на контуре, где учёт ресурсов не нужен, —
можно переменной окружения MOCKARTY_RESOURCE_METERING=off с перезапуском.

Коммерческие условия

Карточка Коммерческие условия на той же вкладке Потребление задаёт, что
вы берёте поверх себестоимости провайдера за каждый учтённый вызов LLM:

• Наценка, % — прибавляется к себестоимости (может быть больше 100 %).
• Платформенный сбор за вызов — фиксированная сумма за вызов в своей валюте.
  Берётся только с вызовов, оценённых в этой валюте.
• Скидка, % — вычитается из промежуточной суммы.
• Налог, % — начисляется на сумму после скидки.

Стоимость для клиента = себестоимость + наценка + сбор − скидка + налог. Если
пространство работает со своим ключом провайдера, себестоимость не ваша, поэтому
она и наценка считаются нулём; сбор и налог применяются.

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

Четыре составляющие видны отдельными колонками в выгрузке выписки, в итогах
панели Потребление и — для администраторов — в карточке экономики каждой
миссии. Агент читает и задаёт условия инструментами llm_commercial_terms_get и
llm_commercial_terms_set.

Бюджеты до вызова и сверка

На той же вкладке Потребление создайте бюджет рабочего пространства,
продукта или миссии. До обращения к провайдеру Mockarty оценивает и атомарно
резервирует стоимость. Вызов отклоняется до расхода, если он пересекает жёсткий
лимит, выходит за включённую сумму и предоплату без разрешённого перерасхода
или не имеет действующей цены при включённом флаге Блокировать вызовы без
цены.
Те же бюджеты допускают до обращения к провайдеру вызовы LLM и поддерживаемые
платные физические эффекты: инструменты агентов, работу раннеров, внешнюю
транскрибацию и вызовы удалённых security-раннеров. Байт-секунды хранения и
исходящие байты измеряются после фактического потребления, поэтому учитываются
без потерь, но не резервируются заранее по оценке.

После ответа провайдера резерв закрывается по фактическим токенам. Интерфейс
разделяет включённую сумму, предоплату и перерасход, показывает открытые и
истёкшие резервы, расхождения реестра, текущий расход в день и прогноз на 30
дней. Нулевой жёсткий лимит отключает только отдельный потолок; он не означает
нулевой допустимый расход.

Бюджет сам сообщает, когда он достигнут. Срабатывают два события, каждое один
раз за период бюджета: LLM-бюджет — пройден мягкий предел, когда резерв
впервые выводит зафиксированный расход за мягкий предел (вызовы продолжаются),
и LLM-бюджет — жёсткий предел остановил вызов, когда жёсткий предел или
лимит без овердрафта отклоняет вызов (все следующие вызовы отклоняются, пока
бюджет не поднимут или не закончится период). Оба видны в колокольчике, их
можно привязать к личному каналу, доставить подпиской командного канала
(Настройки → Колбэки пространства → Командные каналы, группа Система) или
отправить в вебхук; сообщение называет бюджет, суммы и период и открывает
настройки бюджета. Повторный отказ сообщение не повторяет.

Участники пространства имён — и агенты, работающие в нём, — видят, сколько их
область ещё может потратить, без страницы администратора: MCP-инструмент
llm_budget_headroom (или GET /api/v1/namespaces/{namespace}/llm-budget,
при необходимости ?missionId=<id>) показывает действующие бюджеты пространства,
сколько каждый ещё допускает до отказа платного вызова и не исчерпана ли область
уже. Автономный агент проверяет это перед дорогой работой и останавливается у
предела, а не узнаёт о нём из отказа.

Если платный физический эффект был отправлен, но окончательный ответ провайдера
потерялся, он появляется в списке Неоднозначные исходы. Администратор может
нажать Сверить, выбрать авторитетный источник подтверждения и указать
уникальный идентификатор эффекта или строки инвойса провайдера. Выберите
Эффект произошёл и задайте точный объём для списания резерва либо
Эффекта не было только при наличии подтверждения, что провайдер не выполнил
платное действие. Связь с подтверждением и списание или освобождение резерва
фиксируются одной транзакцией; противоречащее решение их не заменяет. Если
инвойс показывает объём выше допущенного, Mockarty учитывает полный фактический
расход и отмечает превышение лимита, а не скрывает стоимость провайдера.

Команда mockarty economics statement выгружает воспроизводимые строки единого
реестра. Помимо событий с токенами LLM, выписка содержит надёжно сохранённые
диспатчи инструментов (tool_call / calls) и время завершённых runner-задач
(runner_seconds / seconds), хранение (storage_byte_seconds /
byte_seconds) и исходящий трафик (egress_bytes / bytes). В столбце
resource указан конкретный ресурс; прежний столбец model продолжает заполняться для совместимости.
Разные ресурсы нужно агрегировать по event_kind, quantity и unit.

Полный возврат клиенту добавляется через mockarty economics refund --event-id ... --reason ...: исходное событие и расход провайдера не стираются. Повторный запрос
идемпотентен. CSV защищён от формул табличного редактора и ограничен 50 000 строками за запрос.

Клиентская LLM

Пользователи также могут подключить собственного LLM-провайдера напрямую из браузера, без маршрутизации API-вызовов через сервер Mockarty. Это полезно, когда:

• У пользователей есть собственные API-ключи для OpenAI, Claude или других провайдеров
• Вы хотите избежать прохождения LLM-трафика через сервер Mockarty
• Разным пользователям нужны разные LLM-провайдеры

В клиентском режиме API-вызовы к LLM выполняются напрямую из браузера к провайдеру, а выполнение инструментов (создание моков, обновление хранилищ и т. д.) по-прежнему происходит на сервере.

Чтобы использовать клиентскую LLM, пользователь выбирает свой профиль в настройках Agent Chat со своим API-ключом и URL провайдера.

Лимиты запросов по пространствам имён

Чтобы предотвратить чрезмерное использование LLM, настройте лимиты запросов на пространство имён:

1. Перейдите в Панель администратора > LLM Profiles.
2. В разделе Rate Limits установите:
   • Requests per minute на пространство имён.
   • Requests per day на пространство имён.
3. Нажмите Save.

Agent Chat

Когда AI-ассистент включён, на каждой странице веб-интерфейса появляется плавающая кнопка чата. Пользователи могут:

• Задавать вопросы об использовании Mockarty.
• Запрашивать создание моков на естественном языке.
• Получать помощь с выражениями JsonPath, функциями Faker и условиями.
• Диагностировать проблемы сопоставления моков.

Режим автоматического одобрения

По умолчанию Agent Chat требует ручного одобрения каждого вызова инструмента (кнопки Accept/Decline). Вы можете включить режим автоматического одобрения, чтобы вызовы инструментов выполнялись без подтверждения:

1. Откройте Agent Chat.
2. Найдите выпадающий список Auto Approve в верхней части панели чата.
3. Переключите с Manual на Auto Approve.

Эта настройка хранится локально в браузере и сохраняется между сессиями. Используйте автоматическое одобрение, когда доверяете AI-агенту выполнять операции без проверки — например, при быстром прототипировании моков в sandbox-пространстве.

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

OpenTelemetry: трассы и метрики

Админ → Мониторинг. Один раз укажите свой OTel-коллектор
(адрес, gRPC или HTTP, при необходимости заголовки) и включите то, что нужно
отправлять.

• Трассы — спаны запросов на пути резолва моков (видно, как запрос прошёл
  через ответивший стаб), а также спаны доставки webhook’ов и LLM-вызовов
  (провайдер, модель, счётчики токенов — никогда не содержимое промпта или
  ответа).
• Также отправлять метрики (OTLP) — раз в минуту отправляет по тому же
  соединению те же ряды, что отдаёт /metrics.

Отправка метрик нужна в одном случае: сеть, где этот узел никто не может
опрашивать (контуры только на исходящие, VPC заказчика с единственным
исходящим маршрутом). Если ваш коллектор уже скрейпит /metrics своим
prometheus-receiver’ом — оставьте выключенным, иначе те же числа поедут дважды.

Отправляются ровно те ряды, что и на /metrics, без изменений: метрики читаются
из того же реестра, а не инструментируются второй раз, поэтому скрейп и push не
могут разойтись. Отправка работает независимо от того, обслуживает ли узел
трафик, — простаивающий узел это как раз тот случай, когда важно видеть, что он
жив.

Выключение телеметрии останавливает оба сигнала.

Фоновые чистки — тоже метрики. Каждая запланированная чистка (retention-развёртки
из Админ → Хранение данных) отчитывается на /metrics, так что остановившаяся
чистка видна без чтения логов:

• mockarty_background_sweep_runs_total{sweep=<тип настройки>,outcome=completed|panicked}
  — один инкремент на запуск (panicked — паника, которую чистка сама не перехватила);
  ряд, который перестал двигаться, — чистка, которая перестала запускаться.
• mockarty_background_sweep_duration_seconds{sweep=<тип настройки>} — длительность
  каждого запуска.

Метка sweep — тип retention-настройки, то же имя, что на странице хранения данных.
Такт обслуживания памяти проекта (приём фактов, индексация, компакция) отчитывается в том
же семействе как sweep="project_memory_runtime"; такт, завершившийся ошибкой, считается
отдельно в mockarty_project_memory_tick_failures_total — постоянно падающий цикл виден
как растущий счётчик, а не как тихо остановившийся ряд. Запись, принятая, когда проект
уже за мягким лимитом бюджета памяти, увеличивает
mockarty_project_memory_degraded_admissions_total (жёсткий потолок по-прежнему
отказывает): рост этого счётчика — предупреждение, что дальше начнутся отказы.

Парк раннеров измеряется на той же странице. Каждая задача, которую узел отдаёт
раннеру, оставляет на /metrics своё ожидание и время выполнения, а глубина очереди
публикуется каждые 15 секунд — так что «парк слишком мал» или «один тип задач
медленный» становится числом, а не ощущением:

• mockarty_runner_demand_pending{capability=<тип задачи>} — задачи в очереди на
  capability, которые раннер ещё не взял; mockarty_runner_demand_busy и
  mockarty_runner_demand_capacity — число выполняющихся задач и суммарное число
  параллельных слотов у раннеров, объявивших эту capability.
• mockarty_runner_task_queue_wait_seconds{task_type=<тип задачи>} — сколько задача
  ждала от создания до того, как раннер её запустил.
• mockarty_runner_task_duration_seconds{task_type=<тип задачи>,outcome=completed|failed}
  — сколько затем занял сам запуск, от старта до отчёта о результате.
• mockarty_runner_tasks_completed_total{task_type=<тип задачи>,outcome=completed|failed}
  — один инкремент на задачу, которую раннер закончил: доложен результат или запуск
  потерян на середине (считается как failed). Задачи, отменённые пользователем, не
  считаются.

Обе задержки считаются по собственным отметкам времени задачи на узле, а не по тому,
что раннер сообщает о себе. Задача, которая так и не стартовала (таймаут в очереди),
учитывается в счётчике, но задержек не даёт — ожидание, которое никто не обслужил, не
сойдёт за быстрый запуск.

UI-прогоны (браузерные и мобильные) отчитываются так же. Когда прогон UI-теста
завершается, узел записывает его вердикт и каждое воспроизведённое действие:

• mockarty_ui_runs_total{platform=web|android|ios,engine=<движок>,outcome=passed|failed|broken|skipped}
  — один инкремент на завершённый прогон.
• mockarty_ui_run_steps_total{platform,engine,status=passed|failed|broken|skipped}
  — один инкремент на воспроизведённое действие.
• mockarty_ui_run_step_duration_seconds{platform,engine} — сколько заняло каждое
  действие; шаг, о котором раннер отчитался без времени, считается, но не измеряется.

engine — браузерный движок (chromium, firefox, webkit, lightpanda, cdp)
или мобильный драйвер (adb, maestro). Значения, которые узел не распознаёт,
сворачиваются в other, чтобы раннер не мог раздуть страницу метрик произвольными
метками.

Рекомендации по безопасности

Следуйте этим рекомендациям, чтобы поддерживать безопасность вашей инсталляции Mockarty.

Немедленные действия после установки

1. Смените пароль администратора по умолчанию. Учётные данные admin/admin описаны в публичной документации. Смените пароль до того, как экземпляр станет доступен по сети.

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

Сетевая безопасность и шифрование

3. Используйте HTTPS. Настройте TLS-сертификаты (автоматически сгенерированные или собственные), чтобы шифровать весь трафик. Установите COOKIE_SECURE=true (значение по умолчанию), чтобы session cookies отправлялись только по HTTPS.

4. Оставьте защиту от SSRF включённой. Параметр ALLOW_PROXY_TO_PRIVATE_IPS по умолчанию равен false, что предотвращает доступ модулей прокси/тестирования к сервисам внутренней сети. Не меняйте значение, если не понимаете рисков. Когда Mockarty работает в том же кластере, что и тестируемые сервисы, предпочтительнее MOCKARTY_TARGET_ALLOWLIST вместо грубого флага: он разрешает только перечисленные диапазоны/хосты (через запятую/пробел — CIDR вида 10.0.0.0/8 и суффиксы хостов вида .svc.cluster.local), оставляя все остальные приватные адреса заблокированными. Cloud-metadata и link-local блокируются независимо от обеих настроек.

5. Ограничьте сетевой доступ. Используйте файрволы или сетевые политики, чтобы ограничить доступ к портам Mockarty:

   Порт	Протокол	Назначение	Кому открывать
   5770	HTTP	Веб-интерфейс, REST API, мок-трафик	Пользователи / команды
   5771	HTTPS	Зашифрованный веб-интерфейс, REST API, мок-трафик	Пользователи / команды (рекомендуется)
   5772	HTTP/SSE	MCP-сервер (только если ENABLE_MCP=true)	AI-агенты / доверенные клиенты
   5773	gRPC	Координатор (регистрация resolver/runner)	Внутри сети: только resolver- и runner-ноды

Контроль доступа

6. Используйте изоляцию пространств имён. Назначьте каждой команде собственное пространство имён с подходящими ролями. Это предотвращает случайное взаимное влияние между командами.

7. Соблюдайте принцип минимальных привилегий. Назначайте минимальную роль, соответствующую потребностям пользователя. Большинству пользователей подойдёт системная роль User с ролью User или Viewer в пространстве имён.

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

9. Просматривайте журналы аудита. Регулярно проверяйте журналы аудита на предмет неожиданной активности, особенно неудачных попыток входа и административных действий.

Операционная безопасность

10. Обновляйте Mockarty. Своевременно применяйте обновления, чтобы получать исправления безопасности.

11. Регулярно создавайте резервные копии. Настройте автоматическое резервное копирование в Панель администратора > Backup. Периодически проверяйте, что копии можно восстановить.

12. Мониторьте состояние системы. Используйте эндпоинты проверки состояния (/health/live для liveness, /health/ready для readiness) для мониторинга статуса системы.

13. Включите контрактное тестирование. Используйте контрактное тестирование для обнаружения дрейфа моков и ломающих изменений. Это гарантирует, что моки остаются синхронизированы со спецификациями API, и предотвращает молчаливое расхождение тестовых окружений с продакшен-поведением.

14. Тестируйте устойчивость через chaos engineering. Используйте chaos engineering, чтобы убедиться, что ваши системы корректно обрабатывают сбои, когда зависящие от Mockarty сервисы испытывают неисправности (требуется PRO-лицензия).

Ограничение частоты запросов

Rate Limiting: Лимиты частоты запросов API настраиваются через базу данных. Лимиты по умолчанию: 10 запросов/секунду, 60/минуту, 1000/час на каждую область (пользователь/пространство имён/глобально), с burst-лимитом 20. Управление лимитами доступно через admin API.

Сводка переменных окружения

Базовая защита (рекомендуемые значения для продакшена):

Задайте эти переменные и на раннерах. Наборы проверок выполняются на раннере, а не на
административном узле, поэтому MOCKARTY_TARGET_CA_BUNDLE, MOCKARTY_TLS_SKIP_VERIFY и
MOCKARTY_TARGET_ALLOWLIST должны присутствовать и в окружении раннера. Сертификат, которому
доверяет только административный узел, на раннере всё равно не пройдёт проверку, а выглядеть это
будет как недоступный продукт, а не как проблема с сертификатом.

Как читать внешнюю проверку качества (AQC): отчёт показывает, что проверено, а что проверить не удалось. Отсутствие результата не означает успешную проверку.

• AQC a11y_score — доля от 0 до 1: 0.92 означает 92%. В отчёте аудита доступности для человека сохраняется оценка из 100.
• Браузерные метрики описывают загрузку страницы, а не нагрузочный тест. Отсутствующее измерение не означает успешный результат с нулевой длительностью; нагрузочной проверке по-прежнему нужны отдельно объявленные цели и разрешение.
• Визуальная оценка адаптивности требует кадра с подтверждённым viewport и доступной vision-модели. Отсутствие кадра или поддержки модели отражается как непроведённая проверка.
• При запрете записи в продукт наблюдение ссылок и DOM-свойств фокуса не доказывает работу кликов или клавиатурной навигации. Для read-only наблюдения нужен совместимый браузерный раннер; старый раннер сообщает о недостающей проверке и не получает разрешения активировать элементы.
• Сохранённые в каталоге сценарии могут быть ручными. Их наличие не доказывает выполнение; автоматической регрессии нужны исполнимые шаги.

HTTP / HTTPS листенер:

Ввод HTTP-матчера. Переменная окружения задаёт режим при запуске. Администратор может
переключить отдельное пространство имён в shadow или off без перезапуска. Перед сменой
режима обслуживания запросов проверьте собранные результаты.

1. Запустите с shadow или включите его для одного пространства имён. Каждый N-й запрос оценивают оба матчера, каждое расхождение
   записывается; ответы по-прежнему отдаёт старый матчер.
2. Прочитайте записанное ($TOKEN — токен администратора):

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:5770/api/v1/admin/http-matcher/status

По каждому пространству имён видно режим, ревизию снимка и находки: winner_mismatch
(скомпилированный индекс ответил бы другим моком), no_candidates (в индексе нет маршрута для
этого запроса), selection_error или evaluation_error. Отсутствие находок означает, что
в проверенных запросах расхождения не записаны; это не доказывает согласованность всех
маршрутов. Узел, на котором
скомпилированный матчер не запущен, отвечает wired: false — это другое утверждение, чем
матчер, который работает и которому нечего сообщить.

Для смены режима одного пространства имён передайте его последнюю ревизию из
modeAuthority.records[].revision в поле expectedRevision. Для первого изменения
используйте 0:

curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"shadow","expectedRevision":0}' \
  http://localhost:5770/api/v1/admin/http-matcher/modes/my-namespace

После изменения снова прочитайте статус. Ответ 409 означает, что ревизия изменилась:
перед повтором получите текущую ревизию. Ответ 202 означает, что изменение сохранено, но
его распространение не подтверждено; перед следующей сменой проверьте
ответ. Пока modeAuthority.available равно false, этот узел обслуживает
запросы через прежний матчер до получения актуального режима.

3. На одном узле переключите режим в on после проверки результатов выборочного сравнения. С этого момента
   ответ отдаёт скомпилированный индекс, а запрос, который он не смог обработать, обслуживает
   старый матчер — и это записывается находкой. Перед сменой режима обслуживания проверьте
   результаты выборочного сравнения.
4. Для отката одного пространства имён отправьте в тот же эндпоинт режим off и последнюю
   ревизию, либо выберите off для этого пространства имён в карточке админ-панели (ниже).
   Изменение исходного режима в переменной окружения по-прежнему требует перезапуска.

Смена режима и наблюдение за вводом в админ-панели

То же состояние видно без API, и там же можно сменить режим. Откройте
Админ-панель > Настройки и найдите карточку HTTP-матчер: она показывает текущий режим
по вашим пространствам имён, последнюю ревизию снапшота, общее число записанных находок и
таблицу по пространствам имён (десять с наибольшим числом находок; кнопка Показать все
раскрывает остальные). Карточка обновляется каждые 30 секунд. На узле, где скомпилированный
матчер не запущен, карточка показывает Не подключён — тот же смысл, что wired: false в
ответе API выше.

В конце каждой строки — селектор режима. Выбор режима применяет его к этому пространству имён
с ревизией из той же строки, поэтому изменение, сделанное тем временем кем-то другим, будет
отклонено, а карточка перечитает текущее значение вместо того, чтобы затереть чужую правку.
Переход в on и из on меняет то, какой матчер отвечает на живые запросы, поэтому он сначала
спрашивает подтверждение; off и shadow оба отвечают старым матчером, поэтому такое
переключение применяется сразу. Если изменение сохранено, но его подтвердили ещё не все узлы,
карточка об этом скажет — перечитайте режим перед следующей сменой.

Пространство имён появляется в таблице только после того, как матчер собрал для него снимок,
поэтому на свежем узле таблица пуста. Строка под ней задаёт режим пространству имён ПО ИМЕНИ:
впишите имя, выберите режим и примените. Отправляется ревизия из строки таблицы, а если
пространства там нет — ревизия первой установки; пространство, у которого режим уже есть,
ответит тем же конфликтом, что и любая устаревшая ревизия, вместо перезаписи, и дальше таблица
покажет его с настоящей ревизией.

В кластере эндпоинт переключения пока принимает только shadow и off. Переключение в on
во время работы возвращает 409, а запуск с MOCKARTY_HTTP_MATCH_MODE=on завершается
ошибкой до появления согласованного ввода.

База данных:

Кэш:

PDF-движок для отчётов Test Plan (опционально):

Эндпоинт экспорта прогона Test Plan может отдавать PDF, если в системе доступен внешний рендерер. Mockarty при старте сам ищет бинарь wkhtmltopdf и подключает его автоматически — в большинстве случаев никаких env-vars выставлять не нужно. Если бинарь не установлен, эндпоинт возвращает 501 Not Implemented с JSON-конвертом, объясняющим как его поставить.

Chromium-вариант сборки. Стандартный release-бинарь distroless-дружелюбный и содержит только путь wkhtmltopdf. Для Chromium-качества PDF нужен Chromium-вариант сборки Mockarty — запросите его у поставщика Mockarty — и Chromium-бинарь, доступный в PATH (или через MOCKARTY_PDF_CHROMIUM_BIN). Для большинства операторов wkhtmltopdf — более простой выбор: установите его пакетным менеджером дистрибутива, и всё готово.

Установка wkhtmltopdf:

Рендерер — это один статический бинарь от wkhtmltopdf.org. Выберите команду под вашу платформу:

• Debian / Ubuntu — sudo apt-get update && sudo apt-get install -y wkhtmltopdf
• Alpine — apk add --no-cache wkhtmltopdf (плюс ttf-dejavu, если в отчётах есть не-ASCII текст)
• macOS — brew install --cask wkhtmltopdf (на старых Homebrew работает brew install wkhtmltopdf)
• CentOS / Rocky / RHEL — скачайте RPM с официальной страницы релизов и установите rpm -i …. Дистрибутивная версия часто старше 0.12.6 и спотыкается на flex-CSS.
• Windows — скачайте .exe-инсталлятор с официальной страницы и укажите путь к нему в MOCKARTY_PDF_WKHTMLTOPDF_BIN.

После установки перезапустите Mockarty. В startup-логе появится test-plan PDF engine selected engine=wkhtmltopdf если детектор сработал. Кнопка «Скачать PDF» в отчёте о прогоне тест-плана начнёт работать без выставления env-vars.

Траблшутинг: если экспорт всё ещё возвращает 501 после установки — проверьте, что бинарь в $PATH admin-ноды (which wkhtmltopdf) и что он исполняется (wkhtmltopdf --version). Если установили в нестандартный путь — выставьте MOCKARTY_PDF_WKHTMLTOPDF_BIN=/полный/путь/к/wkhtmltopdf и перезапустите. Установите MOCKARTY_DEBUG=1, чтобы Mockarty писал упавший HTML в /tmp/mockarty-pdf-*.html для локального воспроизведения.

Кластерный режим (multi-node развёртывания):

Правило для multi-node. CLUSTER_MODE=true требует PostgreSQL (DB_USE=pg). SQLite не поддерживает advisory-lock, используемые для leader election.

Event bus (асинхронная обработка событий):

Аналитика (opt-in, анонимная):

Test Plans (живые логи и долговременный архив):

Движок Test Plans пишет каждую строку лога элемента через sink, который раздваивает запись на основное хранилище (таблица test_plan_item_logs — используется для повторного воспроизведения в UI) и опциональный вторичный архив (локальный файл или S3-совместимое хранилище — используется для длительного хранения или экспорта в SIEM). Если вторичная запись недоступна, основной путь продолжает работать — логи не теряются из-за временной недоступности S3.

Совет для air-gapped. В изолированных от интернета установках оставляйте TESTPLAN_LOGSINK_SECONDARY пустым. Основной sink в БД всё равно сохраняет каждую строку лога, и живой UI-tail продолжает работать.

Общие:

Переходное окно лицензирования (выделение модуля):

Когда модуль выделяется из существующего лицензионного ключа, старый ключ
некоторое время продолжает открывать новый модуль — чтобы обновление уже
работающей установки не отнимало модуль у пользователей. Текущий переходный
режим касается модуля Обработка и коммуникации (processing): его по-прежнему
удовлетворяет ключ Управление тест-кейсами (tcm).

Значение читается на каждой проверке лицензии, поэтому срезы, выводимые из
лицензии (гейт маршрутов, фильтр MCP-инструментов, гейт субагентов), реагируют
на изменение сразу. Персональные наборы модулей кешируются на 30 секунд
и подхватывают изменение при следующем обновлении или после
перезапуска.

Как безопасно закрыть окно. Перед переключением посмотрите доказательства в
/metrics на административном узле:

• mockarty_license_transition_shim_reliant_licenses{feature="processing",parent="tcm"}
  — сколько активных лицензий несут tcm и не несут processing, то есть
  сколько лицензий на этом экземпляре зависит от переходного режима. Значение
  обновляется при каждой перезагрузке лицензий.
• mockarty_license_transition_shim_satisfied_total{feature="processing",parent="tcm",surface=...}
  — сколько проверок прошло только благодаря окну, с разбивкой по surface
  (licence_gate, licence_seats, licence_list, grant_view).

Нулевой gauge вместе с неизменным счётчиком, наблюдаемые в течение окна,
покрывающего рабочие часы ваших пользователей, — это и есть доказательство,
что окно больше никому не нужно. В многоузловом кластере каждый узел публикует
собственный снимок лицензий, поэтому читайте эти серии по узлам (их различает
постоянная метка node_id), а не суммируйте — сумма посчитает одного клиента
по разу на узел. Закрытие окна не влияет на данные: то, что было создано при
открытом окне, остаётся доступным для чтения навсегда, а ключ processing
требуется только для редактирования и запусков.

Администрирование Kubernetes

При запуске Mockarty в Kubernetes административная нода может управлять жизненным циклом кластера напрямую через Admin API и CLI. Оператор отслеживает Custom Resource MockartyCluster и автоматически приводит resolver-ноды, runner-агенты и интеграции к желаемому состоянию.

Переменные окружения для управления K8s

Эндпоинты Admin API

Эти эндпоинты существуют только когда включено управление Kubernetes — то
есть когда Mockarty работает внутри кластера (K8S_MANAGEMENT=auto определяет
это сам) или вы включили его принудительно через K8S_MANAGEMENT=true. На
обычной установке они не регистрируются вовсе и отвечают 404 — это ожидаемо,
а не поломка.

Чтобы проверить без догадок, спросите саму ноду:

curl http://localhost:5770/api/v1/k8s/enabled \
  -H "X-API-Key: $MOCKARTY_API_TOKEN"
# {"enabled":true,"namespace":"mockarty"}

Все Kubernetes-эндпоинты требуют аутентификации и доступны только на административной ноде.

Пример масштабирования:

curl -X POST http://localhost:5770/api/v1/k8s/scale \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"component": "resolver", "replicas": 5}'

Пример обновления:

curl -X POST http://localhost:5770/api/v1/k8s/upgrade \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"component": "runner", "version": "1.3.0"}'

RBAC

• Операции с кластером (scale, upgrade, restart, status, logs) доступны только пользователям с ролью Admin или Support.
• Интеграции пространств имён (/api/v1/k8s/integrations) доступны владельцам пространств имён для своих пространств и администраторам — для любых.

Команды CLI

CLI предоставляет сокращённые команды, вызывающие Admin API под капотом:

# View cluster status
mockarty-cli cluster status

# Scale a component
mockarty-cli cluster scale resolver --replicas 5

# Upgrade cluster image tag (upgrades all components at once)
mockarty-cli cluster upgrade --tag 1.3.0

# Rolling restart
mockarty-cli cluster restart resolver

# Stream pod logs
mockarty-cli cluster logs <pod-name> --follow --tail 100

Экспорт журнала аудита и интеграция с SIEM

Mockarty ведёт неизменяемый журнал аудита всех событий аутентификации, изменений конфигурации и административных действий. Журнал можно экспортировать из Админ-панели или через REST API в одном из четырёх форматов, совместимых с основными SIEM-платформами.

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

Каждая запись, созданная во время HTTP-запроса, несёт в metadata ещё и correlation_id — значение X-Request-Id этого запроса (или сгенерированный Mockarty идентификатор, если клиент его не прислал). Это то же значение, что несут строки лога данного запроса, поэтому запись аудита и логи вызвавшего её вызова можно соединить напрямую, а не сопоставлять по времени. Записи, созданные вне запроса — планировщиком, sweep’ом, раннером — correlation id не несут: выдуманный идентификатор соединял бы ничто.

REST API

# CSV-дамп за последние 24 часа (миллисекунды от эпохи)
curl -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/export?format=csv&from=$(date -u -d '1 day ago' +%s000)" \
     > audit.csv

# Syslog RFC 5424 — поток в SIEM-коллектор
curl -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/export?format=syslog" \
     | nc -u siem-collector.example.com 514

# ArcSight CEF для ingestion существующим SIEM-парсером
curl -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/export?format=cef" \
     > audit.cef

Поддерживаемые фильтры: user_id, action, resource_type, resource_id, namespace, from, to, limit.

CLI

# Почасовой дамп syslog для SIEM
mockarty-cli audit export \
    --format syslog \
    --from $(date -u -d '1 hour ago' +%s000) \
    --to   $(date -u +%s000) \
    > audit-$(date +%s).log

# CEF в файл
mockarty-cli audit export --format cef --output audit.cef

# Фильтр по пользователю
mockarty-cli audit export --format json --user-id u-42 --action login

Формат записей

• Syslog (RFC 5424) — одна запись на строку, facility 13 (security/authorization). Structured-data блок [audit@<PEN> key="value" ...] содержит полную запись. Значение private-enterprise number по умолчанию — placeholder; фактический PEN задаётся на этапе сборки для production-развёртываний.
• CEF 0 — CEF:0|Mockarty|Mockarty|<версия>|<action>|<name>|<severity>|<ext>. Поля расширения используют CEF-словарь (suser, src, act, rt, requestMethod, requestUrl, externalId плюс custom cs1/cs2/cs3 с label’ами для namespace/resource).

Оба SIEM-формата экранируют служебные символы (|, =, \, ", ], переводы строк), гарантируя одну запись на строку и безопасный ingestion в любой RFC- или CEF-совместимый парсер.

RBAC: экспорт аудита требует роли admin или support. Роль support может экспортировать, но не изменять записи.

Срок хранения журналов аудита

Срок хранения журнала аудита задаётся расписанием audit_log_cleanup в Админ-панели → Политики очистки. Значение по умолчанию настраивается под конкретное развёртывание; записи старше этого срока жёстко удаляются, чтобы таблица не разрасталась бесконтрольно.

Для регулируемых развёртываний (банки по 719-П ЦБ РФ §6.4, государственные системы по ФСТЭК приказ №17 п.4.2) Mockarty поддерживает минимальный порог соответствия, заданный переменной окружения. Если переменная установлена, любое меньшее значение, сохранённое оператором через UI, автоматически поднимается до порога — оператор не может случайно сократить срок хранения ниже законодательно установленного минимума.

Типовые значения: 1095 для 719-П ЦБ РФ (3 года), 1825 для расширенных политик ФСТЭК (5 лет). Для нерегулируемых развёртываний переменную оставляют неустановленной.

Порог применяется на каждом тике планировщика очистки и логируется на уровне WARN, когда он поднял эффективный срок хранения.

Юридические блокировки свидетельств (legal hold)

Юридическая блокировка замораживает свидетельства на время нормативной проверки, расследования инцидента или судебного разбирательства. Существующий операторский API /admin/audit/legal-holds защищает строки аудита и подходящие свидетельства автономных миссий: таймлайн и payload, завершённую историю Autotester/Coder, задания кодера и входные записи. Выбора отдельного ID миссии нет: полная область блокировки задаётся документированным временным окном и необязательным namespace.

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

Блокировки закрывают сразу три требования:

• SOX §802 / 18 USC §1519 — уничтожение документов под действующим judicial preservation notice в США является уголовным преступлением.
• 719-П ЦБ РФ §6.4 — банковский оператор обязан иметь возможность заморозить журналы аудита по запросу ЦБ.
• ФСТЭК приказ №17 п.4.2 — целостность журналов в ходе расследования инцидентов ИБ.

Каждая блокировка — это диапазон от метки from_time до опциональной to_time (открытые блокировки допускаются) — и может быть ограничена одним пространством имён или применена глобально. Установка и снятие блокировки сами попадают в аудит через verbs audit_legal_hold_applied и audit_legal_hold_released.

Очистка выполняется ограниченными пачками и не монополизирует базу. Каждая завершённая пачка очистки журнала сама записывается как ресурс audit_log_cleanup со стабильным actor system:retention; если центральный аудит временно недоступен, запись остаётся в надёжной очереди и повторяется без повторного удаления данных.

REST API

# Заморозить последние 7 дней для пространства имён "prod"
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{
       "reason": "INC-42 preservation",
       "from_time": "2026-04-12T00:00:00Z",
       "to_time":   "2026-04-19T23:59:59Z",
       "namespace": "prod",
       "filter_summary": {"ticket": "INC-42"}
     }' \
     "$MOCKARTY_URL/api/v1/admin/audit/legal-holds"

# Список блокировок (status: active|released, limit 1..1000)
curl -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/legal-holds?status=active"

# Снять блокировку (идемпотентно — повторные вызовы возвращают 200 со снятой записью)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
     "$MOCKARTY_URL/api/v1/admin/audit/legal-holds/<hold-id>"

Поведение

• Перед первым удалением каждый проход очистки свидетельств проверяет хранилище блокировок, а destructive-запросы сохраняют коррелированный guard. Partial index активных блокировок ограничивает стоимость обычного пустого случая.
• Блокировка, ограниченная namespace, защищает только строки этого namespace. Блокировка без поля namespace покрывает все пространства имён.
• Открытая блокировка (без to_time) покрывает все строки от from_time и далее без верхней границы.
• Снятые блокировки не удаляются — они остаются в таблице audit_log_legal_holds как доказательная база того, что было заморожено, когда и кем.
• RBAC: POST и DELETE доступны только роли admin. Роль support может просматривать список блокировок (SOC-видимость), но не устанавливать и не снимать их.

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

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

Сборка для соответствия требованиям: SQLite на чистом Go

Релизные бинарники используют движок SQLite на чистом Go — в них нет нативного (libc) кода, именно это делает их пригодными для distroless / scratch-образов и аудита закрытых контуров. Software Bill of Materials (SBOM), публикуемый с каждым релизом, позволяет аудитору подтвердить полный состав зависимостей запускаемого бинарника.

Шифрование персональных данных в хранилище

Если вашей установке нужно защищать персональные данные при хранении, включите эту возможность до запуска. Без ключей она выключена. Храните ключи в менеджере секретов и задайте одинаковые значения на всех админ-нодах. Шифруются email и имя пользователя, а также данные user-agent в аудите. Записи, сохранённые до включения шифрования, нужно перенести отдельно.

Ключ шифрования также защищает поддерживаемые сохранённые учётные данные. Если он не задан, админ-нода при запуске предупреждает, что эти значения хранятся в читаемом виде. Позднее включение шифрования не изменяет старые записи автоматически.

Создайте два разных ключа на доверенной машине и сохраните их как разные секреты:

openssl rand -base64 32  # ключ шифрования
openssl rand -base64 32  # секрет для поиска

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

./mockarty --pii-backfill audit_logs --pii-backfill-dry-run
./mockarty --pii-backfill audit_logs --pii-backfill-batch 1000
./mockarty --pii-backfill users --pii-backfill-dry-run
./mockarty --pii-backfill users --pii-backfill-batch 500

Для шага users нужны оба ключа. После прерывания команду можно повторить: уже преобразованные записи пропускаются. Если меняете ключ, следуйте «Ротации ключей», не подменяйте текущий ключ в работающей установке.

Перенос истории миссий при обновлении

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

1. Сначала обновите все админ-ноды. Пока работает старая нода, не переключайте режим.
2. Проверьте состояние командой ./mockarty --mission-journal-status.
3. Повторяйте ./mockarty --mission-journal-backfill --mission-journal-backfill-batch 128, проверяя состояние после каждого запуска, пока backfillComplete не станет true. После прерывания перенос можно продолжить.
4. Убедитесь, что история миссий открывается и в метрике mockarty_mission_journal_projection_total не растут результаты mismatch и read_error. Только после этого сделайте журнал основным источником:

./mockarty --mission-journal-mode journal_primary_fallback --mission-journal-request-id mission-history-primary-1

Если история неполная или появилась ошибка чтения журнала, на время расследования вернитесь в режим наблюдения:

./mockarty --mission-journal-mode dual_read_observe --mission-journal-request-id mission-history-observe-1

Для каждого отдельного переключения используйте новый request ID. Повторно используйте тот же ID только при повторе попытки с неизвестным результатом. Режимы journal_only и journal_sealed отключают совместимые пути чтения; выбирайте их лишь после проверки всей истории и плана отката вашей установки. После каждого изменения снова запускайте --mission-journal-status.

Источник ключевого материала: software или HSM (PKCS#11)

Для установок госсектора (ФСТЭК приказ №17 п.21, УЗ-2 и выше) и банковского сектора (ЦБ РФ 719-П §5.1) хранить долгоживущие AES- и HMAC-ключи в переменных окружения недостаточно — регулятор требует хранения ключевого материала на сертифицированном оборудовании (ФСТЭК КС2/КС3 или FIPS 140-2 Level 2+). Mockarty абстрагирует источник ключей через единый интерфейс KeyStore с двумя взаимозаменяемыми бэкендами.

Как это работает. Ключ шифрования ключей (KEK) никогда не покидает HSM. При старте Mockarty аутентифицируется к PKCS#11-токену и использует KEK для распаковки ключа шифрования данных из значения MOCKARTY_PKCS11_WRAPPED_PII_KEY — распакованный материал хранится только в памяти процесса и обнуляется при корректном выключении. Отзыв доступа к HSM (смена PIN, блокировка пользователя, выключение токена) достаточен, чтобы заблокировать все работающие и будущие экземпляры Mockarty от зашифрованных данных.

PKCS#11-вариант сборки. Стандартный бинарник Mockarty собирается без CGO (совместим с distroless-образами) и не линкует PKCS#11-библиотеку. Для HSM-интеграции нужен PKCS#11-вариант сборки Mockarty — запросите его у поставщика Mockarty, указав модель вашего HSM, чтобы была слинкована корректная PKCS#11-библиотека вендора.

Выбор MOCKARTY_KEYSTORE=pkcs11 на бинаре, который не включает этот backend, сразу падает на старте с сообщением keystore: PKCS#11 backend is not compiled in — некорректно настроенный деплой никогда не «откатится» тихо на software-ключи.

Провижининг ключей (пример для SoftHSMv2 в staging — в production замените на сертифицированный HSM):

# 1. Инициализировать токен и задать user PIN (один раз на HSM/слот).
softhsm2-util --init-token --slot 0 --label mockarty --pin 1234 --so-pin 5678

# 2. Сгенерировать KEK на HSM — ключ никогда не покинет токен.
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --slot 0 --login --pin 1234 \
    --keygen --key-type AES:32 --label mockarty-pii-kek --usage-wrap --usage-decrypt

# 3. Сгенерировать свежий DEK вне HSM, обернуть его под KEK, выгрузить base64:
openssl rand 32 > /tmp/dek.bin
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --slot 0 --login --pin 1234 \
    --encrypt --mechanism AES-CBC-PAD --iv $(printf '%.0s00' {1..16}) \
    --input-file /tmp/dek.bin --output-file /tmp/dek-wrapped.bin --label mockarty-pii-kek
base64 -w0 /tmp/dek-wrapped.bin    # → значение для MOCKARTY_PKCS11_WRAPPED_PII_KEY

# 4. Повторить для HMAC-pepper (32 случайных байта, обёрнутые под тем же KEK).
# 5. Удалить plaintext DEK и pepper с рабочей станции оператора.
shred -u /tmp/dek.bin

Мониторинг. Эндпоинт /health включает раздел keystore с активным бэкендом (software или pkcs11), флагом pkcs11_compiled_in и результатом проверки PKCS#11-сессии (C_GetSessionInfo). Потерянная HSM-сессия выставляет pod в unhealthy — оператор пересоздаёт деплой для повторной аутентификации.

Соответствие требованиям. ФСТЭК приказ №17 п.21 (УЗ-2+ аппаратная защита ключей), ЦБ РФ 719-П §5.1 (HSM-требование для платёжной инфраструктуры), 152-ФЗ УЗ-3 (разделение владельца ключа и владельца данных — HSM хранит KEK, Mockarty хранит данные).

Журнал человеческих решений

Каждое одобрение, которое человек выносит через защищённые поверхности Mockarty, параллельно попадает в ЕДИНЫЙ кросс-поверхностный журнал — администратор отвечает на вопрос «кто что одобрил», не обходя историю каждого модуля. В журнал пишутся: согласование/отклонение автономных миссий, одобрение деплоя coder-миссии, согласование/отклонение change-request контрактов, ревью записей реестра контрактов, approve/deny отложенных fuzz-прогонов, голоса ревью (approve / request changes / reject), одобрение/отклонение сопряжения companion-устройств, утверждение визуальных базлайнов, решения по одобрениям сканов безопасности и переопределение вердиктов качества (POST /api/v1/quality/verdicts/{taskId}/override).

Журнал пишется «насквозь», но best-effort: поверхность записывает решение сразу после собственного сохранения, а сбой записи журнала никогда не блокирует само одобрение — собственная запись поверхности и аудит-лог остаются авторитетными.

Прочитать журнал (токен администратора или админ-сессия):

curl -H "Authorization: Bearer $MOCKARTY_TOKEN" \
  "http://127.0.0.1:5770/api/v1/admin/human-decisions?namespace=sandbox&limit=50"

Необязательные фильтры: surface, decision, subjectKind, subjectId, namespace (пусто — все пространства имён), limit (по умолчанию 50, максимум 500) и offset. В ответе — decisions (свежие сверху), total (число записей под теми же фильтрами), limit и offset.

Одна запись:

{
  "id": "5f0c6d2e-1b8a-4c1e-9a1d-2f6f1c0e7a11",
  "namespace": "sandbox",
  "surface": "mission",
  "decision": "approve",
  "subjectKind": "mission",
  "subjectId": "9d3a1e40-7c2b-4f6e-8b1a-3e5d7c9f2a10",
  "reason": "scope reviewed, safe to run",
  "actorUserId": "7c1b2a3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "actorEmail": "qa-lead@example.com",
  "decidedAt": "2026-09-19T01:02:03Z"
}

Поверхности: mission, coder_mission, contract_cr, contract_registry, fuzz_held_run, review, companion_pair, visual_baseline, security_scan, aqc_override. Решения: approve, reject, request_changes, deny, expire (одобрение скана безопасности, которое согласующий оставил истечь); для aqc_override решение — исход вердикта, который выставил человек: pass, fail или could_not_verify.

Примечания:

• Журнал только дописывается и читается только через REST — отдельной страницы в веб-интерфейсе у него нет.
• actorEmail хранится под той же защитой «в покое», что и user_email аудит-лога, если настроено шифрование ПДн (см. Шифрование ПДн на уровне полей).
• Журнал содержит одобрения, записанные после включения этой возможности. Ранее принятые решения остаются в соответствующих разделах и журнале аудита.

Смотрите также

• Быстрый старт — Установите Mockarty и создайте первый мок
• Установка и развёртывание — Docker-развёртывание, переменные окружения и настройка TLS
• Руководство по интеграциям — Настройка resolver-нод, runner-агентов и webhooks
• Connection Authority — Публикация и отзыв внешних подключений без исходных учётных данных
• Контрактное тестирование — Валидация моков по OpenAPI-спецификациям и обнаружение дрейфа моков
• Chaos Engineering — Эксперименты с инъекцией сбоев для тестирования устойчивости (PRO)
• Руководство по веб-интерфейсу — Подробное руководство по веб-интерфейсу
• Справочник API — Полная документация REST API для программного доступа