API-ключи команды: audit log и ротация без утечек

Короткий ответ: журналируйте событие и владельца, не секрет

Составьте небольшой каталог событий: создание ключа, выдача в server-side secret store, привязка к проекту, изменение роли, проверка использования, отключение и подтверждение ротации. Для каждого события полезны время, actor, объект, причина, результат и безопасный correlation ID. Сам ключ не является идентификатором для лога. Если нужен технический след, применяйте внутренний key ID, отпечаток с контролируемым доступом или ссылку на запись в secret manager.

Не копируйте в журнал полный Authorization header, request body, переменные окружения, screenshot консоли или экспорт Postman. Такие артефакты могут вернуть секрет в резервные копии и системы аналитики. Проверьте, что маскирование работает и на ошибках: именно аварийная ветка часто записывает больше данных, чем успешный путь. Цель аудита — доказать действие и решение, а не собрать всё содержимое интеграции.

Разделите роли и границы проекта

Один общий ключ команды создаёт неопределённость: невозможно быстро понять владельца, назначить минимальные права или отключить только один сервис. Разделяйте ключи по проекту, среде и сервисной роли, если это поддерживается текущей конфигурацией. Development, staging и production не должны автоматически делить секрет. Ключ приложения хранится на сервере, а разработчик получает доступ к безопасному процессу деплоя, а не к значению ключа в браузере.

Перед выдачей роли подтвердите задачу, срок и владельца. Доступ для диагностики не равен праву на изменение production-конфигурации. Внутренний процесс может требовать второго подтверждения для расширения роли, но не должен заставлять человека пересылать секрет в чат. Если сервис, сотрудник или подрядчик больше не выполняет задачу, отключите связанную роль и проверьте зависимые deployments до удаления записи из журнала.

Ротация как контролируемый процесс, а не аварийная кнопка

Ротацию планируйте заранее: создайте замену в разрешённом secret store, обновите одну среду, выполните server-side smoke test с synthetic входом, подтвердите метрики и только затем отключите старый ключ. Запишите время начала, владельца, затронутый сервис, результат проверки и время окончательного отключения. Не включайте значение старого или нового ключа в тикет, commit, лог CI или описание инцидента.

У ротации должны быть стоп-условия и rollback. Если новый секрет не читает разрешённый сервис, не компенсируйте проблему выдачей ключа в локальный файл разработчика. Верните подтверждённую конфигурацию, выясните границу прав и повторите проверку. После завершения проверьте, что старый ключ действительно больше не используется: это можно сделать по безопасному key ID, классу ошибки и агрегированной активности, не раскрывая секрет.

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

Журнал сам является чувствительным операционным документом: по нему видно архитектуру, владельцев и времена изменений. Согласуйте, какие поля нужны, кому они доступны, сколько хранятся и как удаляются. Требования зависят от организации, договора и применимого права; эта статья не является юридическим заключением. Не переносите сроки хранения другого поставщика на RussiaAPI и не считайте отсутствие значения ключа автоматическим снятием всех рисков.

Разделите оперативный журнал и долгосрочный аудит. В оперативном слое достаточно последних событий, алертов и безопасных correlation ID. В долгосрочном — решения о доступе, подтверждения ротации и неизменяемые агрегаты, если это оправдано политикой. Ограничьте экспорт, резервные копии и интеграции с внешними системами. Периодически проверяйте выборку событий: маскирование, корректность actor, отсутствие случайного request body и возможность связать запись с владельцем.

Проверка и реакция на подозрительное событие

Полезная проверка отвечает на четыре вопроса: ключ относится к нужному проекту, владелец известен, использование ожидаемо и есть ли свежая запись о ротации. Сначала смотрите безопасные метаданные и deployment history, затем ограничивайте доступ по утверждённому процессу. Не просите коллегу прислать значение ключа «для сверки» и не публикуйте фрагменты секрета в общем канале. Идентифицируйте объект по внутреннему ID и записи secret manager.

Если действие выглядит подозрительно, заморозьте затронутую роль или маршрут, сохраните неизменяемый след события, уведомите назначенного владельца и проведите ротацию по плану. Проверьте логи на утечки, но не расширяйте поиск до выгрузки всех prompts и заголовков. После инцидента добавьте конкретное улучшение: более узкая роль, обязательный review, срок доступа или тест маскирования. Так audit log помогает предотвратить повтор, а не превращается в формальный отчёт.

Server-side пример

Пример показывает локальную проверку на сервере. Ключи берутся только из окружения; до запуска подтвердите маршрут, model ID и параметры в текущем каталоге RussiaAPI.

export function safeAuditEvent({ action, actorId, keyId, projectId, outcome }) {
  if (!/^[a-z_]{3,64}$/.test(action)) throw new Error('invalid_action');
  return {
    at: new Date().toISOString(), action, actorId, keyId, projectId, outcome,
    // Deliberately no key value, Authorization header, prompt, or request body.
  };
}

export function assertNoSecret(event) {
  if (JSON.stringify(event).match(/bearer\s|sk-[a-z0-9]/i)) throw new Error('secret_detected');
  return event;
}

Проверьте синтаксис через node --check, добавьте аутентификацию своего маршрута и негативные тесты. Не логируйте тело запроса или заголовки только ради отладки.

Границы и безопасный запуск

Это инженерное руководство, а не юридическое заключение и не инструкция по обходу законов, санкций, региональных, платёжных или платформенных ограничений. Не передавайте в тесты персональные данные, коммерческие секреты, upstream-ключи, cookie, пароли или полный заголовок Authorization. Для чувствительных данных подтвердите цель, минимизацию, срок хранения и договорные условия с ответственными специалистами.

Ключ RussiaAPI хранится только в server-side secret store. Разделяйте development, staging и production, ограничивайте доступ и журналируйте лишь безопасные метаданные. Неизвестную функцию, модель, квоту или поле ответа считайте неподтверждёнными, пока не проверите их в текущем разрешённом тестовом контуре.