Production-guardrails для AI-агентов, которые действительно работают
Production-guardrails для AI-агентов: защита секретов, подтверждение операций, audit logs, ограниченный доступ, структурированные ошибки и безопасные workflow автономного деплоя.
Production-guardrails для AI-агентов должны выдерживать не только вежливо сформулированный prompt. Автономный coding agent может неправильно определить target, повторить операцию, раскрыть credential в объяснении или продолжить работу после неоднозначного ответа. Поэтому безопасность в production должна обеспечиваться на уровне исполняемого интерфейса, модели авторизации и audit trail, а не только инструкций.
Dockup объединяет поведенческие рекомендации в skill для Claude Code и Codex с enforcement на уровне CLI: секреты маскируются, деструктивные операции требуют --yes, ошибки возвращаются со стабильными кодами, deploy может ожидать terminal state, а изменения появляются в audit log.
Почему guardrails должны обеспечиваться на уровне ниже prompt?
Prompt — полезная policy, но не security boundary. Контекст агента может быть обрезан, инструкции могут конфликтовать, а модель — выбрать неправильную интерпретацию. Базовый tool должен делать небезопасное поведение сложным или невозможным.
Рассмотрим запрос на удаление. Слабый дизайн предоставляет команду, которая немедленно удаляет данные, и рассчитывает, что агент не забудет запросить подтверждение. Более надёжный дизайн отклоняет операцию, пока не будет передан отдельный флаг подтверждения.
Dockup использует более надёжный паттерн:
dockup up production/api --prune --json
Без явного подтверждения деструктивная очистка отклоняется, а JSON содержит code:"needs_confirm". Ничего не удаляется. Агент должен показать этот результат человеку, получить одобрение и затем намеренно повторить команду:
dockup up production/api --prune --yes --json
Это defense in depth. Skill Dockup указывает агенту остановиться, а CLI предотвращает случайное выполнение, даже если инструкция была пропущена.
Как маскирование секретов защищает автономных агентов?
Агенты часто включают вывод команд в свои рассуждения или итоговый ответ. Если операция чтения возвращает production token, секрет может попасть в историю чата, logs, telemetry, скриншоты или скопированные заметки об инциденте.
Безопасный интерфейс конфигурации отделяет metadata секрета от его значения. Dockup возвращает ключи переменных окружения и marker isSecret, но сохранённые значения секретов представлены как null или замаскированы.
dockup env list -s production/api --json
Агент может задать секрет, не получая его при последующем чтении:
dockup env set API_KEY="$API_KEY" \
--secret \
-s production/api \
--json
Маскирование секретов не отменяет необходимости аккуратно работать с процессами. Исходное значение всё ещё существует в окружении shell во время операции set. Не используйте set -x, не выводите переменную через echo и не формируйте строки команд, которые попадут в подробное логирование.
Пароли баз данных, API keys, registry tokens, SSH credentials и credentials для Windows RDP следует считать одноразовыми или ограниченными к выдаче. Агент должен сохранять их в одобренном secret manager или напрямую передавать следующему процессу, не воспроизводя их в тексте.
Более широкий подход на уровне приложения описан в статье security best practices.
Как должно работать подтверждение деструктивных операций?
Не каждое изменение требует одинакового уровня контроля. Практичная модель автономности разделяет операции по обратимости и масштабу потенциального ущерба:
| Уровень | Пример | Поведение агента по умолчанию |
|---|---|---|
| Только чтение | Список сервисов, чтение статуса, просмотр logs | Выполнить и кратко описать результат |
| Обратимое изменение | Задать переменную, запустить deploy | Выполнить в пределах одобренного scope |
| Операционное восстановление | Перезапустить, повторно выполнить более старый deploy | Выполнить, если это разрешено runbook; сообщить подтверждающие данные |
| Деструктивная операция | Уничтожить сервис, удалить базу данных, покинуть project | Остановиться и запросить явное одобрение |
| Масштабная деструктивная операция | Применить --prune, передать ownership | Требовать подтверждение человека для конкретного target |
Явное одобрение должно содержать точный target и последствие операции. «Да, продолжай» — более слабая формулировка, чем «Удалить staging/old-api и связанные с ним ресурсы сервиса». Агент не должен использовать одобрение, полученное для другой команды или target.
Dockup config as code по умолчанию работает в additive-режиме. dockup up не удаляет переменные окружения или domains, отсутствующие в manifest. Для удаления требуется явный флаг --prune:
dockup plan production/api --json
dockup up production/api --prune --json
Plan работает только на чтение, и его следует сначала проверить. Даже при использовании --prune secrets, services, databases и volumes защищены от этого пути очистки manifest. Полный workflow описан в статье dockup.yaml config as code.
Как structured errors ограничивают автономность?
Агенту нужен конечный набор безопасных ветвей действий. Сообщения в свободной форме полезны людям, но стабильные коды ошибок делают первую реакцию детерминированной.
| Код | Корректная реакция |
|---|---|
not_logged_in | Остановиться и получить действительный credential |
not_linked | Определить target или передать его явно |
no_target | Запустить service discovery; никогда не придумывать slug |
needs_confirm | Запросить одобрение человека |
deploy_trigger_failed | Сообщить, почему операцию не удалось запустить |
deploy_failed | Изучить build logs |
deploy_timeout | Сообщить о неопределённости, поскольку операция не достигла terminal state |
Для deploy следует использовать ожидание terminal state:
dockup deploy production/api --wait --json
Timeout по умолчанию составляет 900 секунд. Exit 0 подтверждает, что deploy достиг успешного состояния. Ненулевой exit не позволяет агенту продолжить работу с изменениями domain, migrations или announcements так, будто production уже готов.
Этот подход подробно рассматривается в статье AI agent CLI design. Принцип прост: tool должен явно обозначать неоднозначный результат.
Что должен фиксировать audit log?
Автономность без attribution — это operational debt. Production audit trail должен отвечать на вопросы: кто выполнил действие, какой интерфейс использовал, какой target был изменён, была ли это операция чтения или записи, когда она произошла и завершилась ли успешно.
Dockup записывает действия из CLI, UI и API. Операторы могут просматривать последние изменения:
dockup audit --writes --json
dockup audit --number 30 --json
dockup audit --search domains --json
Собственный отчёт агента должен дополнять запись платформы. Включите:
- Определённый target
project/service. - Категорию команды без значений секретов.
- ID deploy или ресурсов, возвращённые платформой.
- Exit code и structured status.
- Данные, собранные после изменения.
- Полученное одобрение для деструктивной операции.
- Оставшуюся неопределённость или дальнейшие действия.
Audit logs нужны не только для поиска виноватых после инцидента. Они позволяют второму агенту или оператору-человеку восстановить картину состояния, не повторяя рискованные команды.
Как безопасно повышать автономность агента?
Начните с доступа только на чтение и одного сервиса с низким риском. Расширяйте полномочия только после того, как агент продемонстрирует корректный target discovery, безопасную работу с секретами, правильную обработку ошибок и качественную отчётность.
Практичная последовательность выглядит так:
Этап 1: Наблюдение
Разрешите чтение списка сервисов, статуса, истории deploy, build logs, runtime logs, uptime, usage и результатов security scan. Сравнивайте сводку агента с исходным JSON.
Этап 2: Deploy для фиксированного target
Разрешите deploy одного сервиса с --wait. Требуйте health check и структурированный отчёт о завершении. Не предоставляйте права на удаление или управление командой.
Этап 3: Управление обратимой конфигурацией
Разрешите обновление non-secret и secret variables, настройку health check и custom-domain в рамках проверенного runbook. После изменения окружения требуйте повторный deploy.
Этап 4: Операции восстановления
Разрешайте restart или rollback только если агент выбирает точный известный ID deploy и сохраняет данные об ошибке.
Этап 5: Деструктивные операции с обязательным одобрением
Сохраняйте деструктивные flags за явным одобрением человека, даже если credential технически позволяет их использовать. По возможности применяйте scoped API keys и регулярно проверяйте audit trail.
Установка skill агента закрепляет эти правила:
npm install -g dockup-cli
dockup skill install
dockup skill status --json
В справочнике Dockup CLI описано enforced-поведение команд. Агент должен проверять локальную schema, а не полагаться на запомненный пример.
Чеклист проверки guardrails
Перед предоставлением доступа к production ответьте на каждый вопрос:
- Может ли агент определить точные targets без догадок?
- Маскируются ли значения секретов во всех read paths?
- Возвращает ли каждое неудачное изменение ненулевой exit?
- Может ли агент ждать terminal state для длительных операций?
- Блокируются ли деструктивные действия без явного подтверждения?
- Имеют ли credentials ограниченный scope и передаются ли они вне prompts?
- Можно ли найти каждое изменение в audit log?
- Существует ли протестированная процедура rollback или recovery?
- Могут ли версии skill и executable расходиться?
- Отделяет ли итоговый отчёт факты от неопределённости?
Ответ «нет» означает, что нужно доработать дизайн, а не написать новый prompt. Автономность в production должна расти только вместе с базовыми гарантиями.
Тестируйте guardrails как failure cases
Проверка неполна, пока команда намеренно не протестирует граничные сценарии. Выполните deploy с недействительным token, запросите неизвестный target, позвольте тестовой сборке завершиться с ошибкой, задайте очень короткий timeout и попробуйте выполнить деструктивную команду без подтверждения. Каждый сценарий должен приводить к ненулевому exit, стабильному коду, отсутствию утечки секретов и отсутствию непредусмотренных изменений.
Эти тесты превращают production-guardrails для AI-агентов в наблюдаемые гарантии. Повторяйте их после обновлений CLI или policy — так же, как вы повторяли бы authentication и authorization tests для приложения. Guardrail, который существует только на слайдах, не защитит release без оператора.
Перенесите workflow в production
Установите skill, изучите его инструкции и проверьте каждый guardrail, включая заблокированную деструктивную команду, прежде чем выпускать production token.
npm install -g dockup-cli
dockup skill install
Первая команда устанавливает CLI. Вторая устанавливает соответствующий skill Dockup для Claude Code и Codex. Начните бесплатно в app.dockup.ai.
FAQ
Достаточно ли инструкций в prompt, чтобы обеспечить безопасность AI-агента в production?
Нет. Prompts помогают направлять поведение, но критически важные controls, такие как маскирование секретов, подтверждение, авторизация, exit codes и audit logging, должны обеспечиваться tool и платформой.
Как Dockup блокирует деструктивные операции?
Деструктивные команды отказываются выполняться без явного флага --yes и возвращают structured code needs_confirm, позволяя агенту остановиться и запросить подтверждение человека.
Может ли AI-агент прочитать значения секретных переменных окружения из Dockup?
Сохранённые значения секретов маскируются в output. Агент видит ключ и secret marker и может заменить значение, но не получает сохранённый секрет.
Почему structured error codes важны для автономности?
Они ограничивают агента известными ветвями восстановления: запросить authentication, определить точный target, прочитать build logs или запросить подтверждение.
С чего команде начать предоставление доступа к production?
Начните с операций только на чтение, затем разрешите deploy одного target с низким риском и переходите к обратимой конфигурации и recovery только после того, как агент начнёт стабильно предоставлять проверяемые подтверждения.