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

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

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

Содержание

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

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

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

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

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

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

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

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

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

http://localhost:5770/ui/

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

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

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

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

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 дня

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

Если внешний провайдер идентификации не настроен, 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

• Для сброса пароля пользователя: Панель администратора > 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. Подтвердите удаление.

Внимание: Удаление пространства имён удаляет все моки, хранилища, коллекции тестов и другие ресурсы внутри него. Это действие необратимо.

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

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

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

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

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

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

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

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

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

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

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

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.

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

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?path=backup_file.dump \
  -H "Authorization: Bearer $TOKEN" \
  -o backup.dump

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

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

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-client (pg_dump, pg_restore, psql), поэтому резервное копирование работает из коробки в Docker- и Kubernetes-окружениях.

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

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

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

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

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

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

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

Перейдите в Панель администратора > 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) управляет тем, сколько задач агента могут выполняться одновременно и как долго живут сессии:

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

При включении без дополнительной настройки 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 — balanced (default)
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 для всех пользователей.

Клиентская 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-пространстве.

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

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

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

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

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

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

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

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

4. Оставьте защиту от SSRF включённой. Параметр ALLOW_PROXY_TO_PRIVATE_IPS по умолчанию равен false, что предотвращает доступ режима прокси моков к сервисам внутренней сети. Не меняйте значение, если не понимаете рисков.

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.

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

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

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

База данных:

Кэш:

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

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

О теге сборки chromium. Chromium-движок компилируется только при сборке Mockarty командой go build -tags chromium. Стандартный release-бинарь distroless-дружелюбный и содержит только путь wkhtmltopdf. Чтобы получить Chromium-качество PDF — пересоберите 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 продолжает работать.

Общие:

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

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

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

Эндпоинты Admin API

Все 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-платформами.

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

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)

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

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

• 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.

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>"

Поведение

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

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

Если на момент очистки БД недоступна, планировщик прерывает текущий тик, а не рискует удалить защищённые строки. Повтор будет на следующем интервале.

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

Mockarty поддерживает два драйвера SQLite, выбираемых на этапе сборки через Go build tags:

Все продуктовые Dockerfile (Dockerfile.mockarty, Dockerfile.runner, Dockerfile.resolver, Dockerfile.operator, Dockerfile.server-generator, Dockerfile.mockarty-license-server) собираются с CGO_ENABLED=0. Аудитор может проверить, какой драйвер связан в релизной сборке:

go tool nm mockarty | grep -E 'sqlite3?' | head

Сборка, соответствующая требованиям, содержит только символы modernc.org/sqlite и ни одной ссылки на github.com/mattn/go-sqlite3.

Шифрование ПДн на уровне полей (at-rest)

Для регулируемых установок под требования 152-ФЗ «О персональных данных» (УЗ-3 / УЗ-4) и 719-П ЦБ РФ §6.5 (защита ПДн у оператора) Mockarty умеет шифровать высокочастотные PII-колонки на уровне приложения. Защищены: колонка user_agent журнала аудита (стабильный PII-отпечаток клиента, пишется на каждый аутентифицированный запрос), email и full_name (ФИО) пользователей.

Функция выключена по умолчанию — если переменные окружения не установлены, колонки хранятся в открытом виде, что корректно для dev- и нерегулируемых окружений. Включение — нулевой даунтайм: существующие plaintext-строки продолжают читаться через прозрачный passthrough, а новые записи ложатся уже зашифрованными конвертами.

Генерация секретов (на доверенной рабочей станции; оба значения отдельными записями в секрет-менеджер):

# AES-256 ключ шифрования (ровно 32 байта)
openssl rand -base64 32
# HMAC pepper для blind-индекса (минимум 32 байта; длиннее — допустимо)
openssl rand -base64 32

Почему два разных секрета. Ключ шифрования защищает конфиденциальность конвертов; pepper ключует детерминированные хеши для equality-запросов (логин по email, привязка OAuth/SAML-аккаунтов) и подстрочного поиска. Компрометация одного не должна автоматически компрометировать другой — оба хранятся как отдельные записи в секрет-менеджере и ротируются независимо.

Что шифруется. При включении обеих переменных шифруются: user_agent аудита, email и full_name пользователя. Все операции, необходимые системе (логин по email, привязка OAuth/SAML-аккаунтов, поиск в админке), продолжают работать прозрачно — Mockarty поддерживает детерминированные поисковые индексы, поэтому функциональность сохраняется полностью. Атакующий, получивший копию базы данных, не сможет восстановить email или ФИО без pepper.

Ротация:

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

Backfill legacy-plaintext строк

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

# audit_logs.user_agent — посчитать кандидатов (без записи)
./mockarty --pii-backfill audit_logs --pii-backfill-dry-run

# audit_logs.user_agent — зашифровать пакетами по 1000 строк
./mockarty --pii-backfill audit_logs --pii-backfill-batch 1000

# users.email + users.full_name + hmac + триграммы (требует MOCKARTY_PII_HMAC_PEPPER)
./mockarty --pii-backfill users --pii-backfill-dry-run
./mockarty --pii-backfill users --pii-backfill-batch 500

# Ограничить объём работы для репетиции на большой таблице (10 батчей по 500)
./mockarty --pii-backfill audit_logs --pii-backfill-max-batches 10

Таргет users шифрует email и full_name вместе со связанными поисковыми индексами. При ошибке на отдельной записи прерывается только эта запись — остальной батч продолжается без изменений.

Свойства:

• Идемпотентность. Уже зашифрованные строки пропускаются, поэтому повторные запуски после падения пода или перезапуска безопасны.
• Без блокировок. Батчи коммитятся независимо — чтения и записи продолжаются с обычной пропускной способностью в течение всего backfill.
• Корректная реакция на сигналы. SIGINT/SIGTERM прерывает работу после текущего батча; следующий запуск продолжит с того же места.
• Требует оба ключа. Субкоманда немедленно завершается с ошибкой, если MOCKARTY_PII_ENCRYPTION_KEY не задан или некорректен. Таргет users дополнительно требует MOCKARTY_PII_HMAC_PEPPER.

Запускается на основной БД (те же DB_DSN, DB_USE, что у админ-ноды). Возвращает код 0 при успехе и печатает итог: PII backfill complete: table=audit_logs column=user_agent scanned=... encrypted=... skipped=... batches=... dry_run=false.

Источник ключевого материала: 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-интеграция, собирают собственный образ с build-tag pkcs11:

# Требует CGO и наличие PKCS#11 shared library от HSM-вендора в путях поиска библиотек.
# Для сборки с поддержкой PKCS#11 обратитесь к вашей CI/CD-документации или
# к поставщику Mockarty — необходим build-flag -tags pkcs11 и CGO_ENABLED=1.

Выбор MOCKARTY_KEYSTORE=pkcs11 на бинаре, собранном без тега, сразу падает на старте с сообщением keystore: PKCS#11 backend is not compiled in — rebuild with -tags pkcs11 — некорректно настроенный деплой никогда не «откатится» тихо на 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 хранит данные).

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

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