Как тестировать доступ агента к API перед запуском в production

Агент получает доступ к production API не за один удачный ответ в sandbox, а за правильное поведение, когда запрос отклонен, составлен неверно, выполняется слишком долго или опасен. Дружелюбная демонстрация скрывает важные сбои: подтверждение относится не к тому процессу, токен попадает в журнал агента, цикл повторных попыток перегружает лимит частоты, а журнал не может объяснить, кто разрешил опасный вызов.

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

Непроизводственный endpoint должен быть отделен там, где ошибка причинит вред

У полезного тестового endpoint свои учетные данные, свои данные и граница возможного ущерба, которую можно объяснить одним предложением. Вызов production hostname с query-параметром, который якобы включает тестовый режим, не подходит, если тот же токен по-прежнему читает записи клиентов или позволяет тратить деньги.

Используйте vendor sandbox, если он дает изолированный аккаунт и тестовые учетные данные. Если sandbox нет, используйте выделенный tenant. Если нет и его, разместите небольшой сервис под своим контролем на другом hostname и подключите к нему одноразовые данные. Важно не название вроде staging, а то, что ошибочный запрос не затронет production-пользователей, production-балансы и production-секреты.

Пусть endpoint доказывает, что он непроизводственный. Возвращайте очевидное поле окружения в каждом успешном ответе, а destructive routes направляйте только в тестовый ledger. Ответ такого вида не даст оператору принять успешный тест за изменение в production:

{
  "environment": "test",
  "request_id": "req_7f1a",
  "status": "accepted",
  "resource_id": "demo-order-184"
}

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

Не используйте production bearer token в тестовой среде ради удобства. Я видел, как команды называли это временным обходным решением, а потом оставляли его, потому что каждая следующая задача казалась важнее. У тестовой учетной записи должны быть имя, владелец, срок действия и разрешения, соответствующие конкретным тестам. Если никто не может объяснить, для какого теста нужно разрешение, удалите его.

Первый запуск должен проверять границу авторизации, а не API

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

Так выявляется различие, которое команды часто смешивают: подтверждение пользователя не равно подтверждению процесса. Оператор может доверять собственному терминалу, но не доверять плагину, скопированному скрипту или агенту, запущенному другим приложением. На экране подтверждения нужно показать, какой исполняемый объект просит разрешение. Кнопка Allow без этого контекста заставляет человека одобрять неизвестный процесс.

Зафиксируйте для этого теста четыре наблюдения:

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

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

Затем перезапустите агента и повторите безобидное чтение. Если второй процесс унаследовал разрешение первого, выясните причину. Кэшированная авторизация выглядит эффективной на демонстрации, но превращается в тихую выдачу разрешений, когда агент перезапускается после обновления или другая программа вызывает ту же команду.

У Sallyport подтверждение сессии включено по умолчанию. При первом вызове от нового процесса агента система показывает полномочие процесса на подпись кода. Это подходящий момент для проверки решения человека, до того как запрос с учетными данными попадет во внешний сервис.

Для передачи учетных данных нужно доказать, что секрет никогда не попадал агенту

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

Настройте тестовые учетные данные так, чтобы удаленный сервис мог распознать их без раскрытия значения. Многие API предоставляют метку токена, идентификатор клиента или поле аудита. Если у вашего API этого нет, создайте тестовый маршрут, который возвращает идентификатор увиденных учетных данных, но не сами учетные данные. Результат должен показывать, какая тестовая личность прошла аутентификацию.

Для API с bearer-токеном запрос на уровне передачи обычно выглядит так:

GET /v1/test/projects/demo HTTP/1.1
Host: api.test.example
Authorization: Bearer [injected outside the agent]
Accept: application/json

Текст в квадратных скобках предназначен для документации, а не для заполнения агентом. Агент должен указать метод, назначение и разрешенные аргументы запроса. Обработчик учетных данных добавляет заголовок авторизации только после решения по подтверждению. Для Basic authentication и схем с пользовательскими заголовками нужен тот же тест, поскольку при неверной настройке они дают сбой в разных местах.

Проверьте журнал агента, историю запросов инструментов, shell-окружение, доступное агенту, и все файлы, созданные во время запуска. Ищите как сам токен, так и косвенные утечки, например объект запроса с заголовком authorization. Последующее удаление данных не исправит дизайн, при котором секрет изначально передали процессу.

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

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

Сложность подтверждения должна соответствовать ущербу от вызова

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

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

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

1. Первое действие достигло тестового сервиса и вернуло идентификатор запроса.
2. Отклоненное действие не достигло тестового сервиса.
3. Агент не заявил, что изменение было выполнено.
4. Сессия осталась пригодной для операций, которым не нужны отклоненные учетные данные.

Четвертый пункт выявляет неприятный сценарий. Некоторые интеграции воспринимают отклонение чувствительного запроса как причину завершить все последующие операции. Другие игнорируют отказ и повторяют запрос, пока кто-нибудь случайно не подтвердит его. Оба варианта усложняют человеческий контроль.

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

Коды состояния HTTP должны определять поведение агента

Агенту нужно явно задать поведение для разных классов сбоев, потому что успешный HTTP-ответ и успешное выполнение задачи не одно и то же. RFC 9110 описывает смысл кодов состояния HTTP: ответ 401 означает отсутствие или недействительность учетных данных, а 403, что сервер понял запрос, но отказывается его выполнять. Обрабатывайте эти ответы по-разному. Повторение обоих запросов без изменений обычно создает шум, а не прогресс.

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

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

Проверяйте сбой передачи данных отдельно от HTTP 503. Отключите тестовый сервис или направьте контролируемый тестовый запрос на недоступный адрес. Агент должен отличать отсутствие ответа от ответа сервера. Это важно, когда операция могла дойти до сервиса, но ответ потерялся. Повторение операции создания после неясного тайм-аута может создать дубликаты.

Используйте идентификаторы идемпотентности, если API их поддерживает. Если нет, перед повторением потенциально изменяющего вызова пусть агент проверит наличие существующего результата. Фраза «повторить три раза» не является планом восстановления, если каждая попытка может списать деньги с карты, создать пользователя или отправить сообщение.

Неудачный запуск часто начинается с безобидного цикла повторных попыток

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

Это можно воспроизвести без риска для production. Пусть тестовый маршрут принимает запрос создания, сохраняет тестовый объект, а затем намеренно закрывает соединение до отправки ответа. Запустите агента с фиксированным идентификатором запроса. Безопасное ожидаемое поведение, проверить этот идентификатор в тестовом сервисе до повторения создания. Если агент не может этого сделать, он должен остановиться и сообщить о неясном результате.

Минимальный контракт тестового сервиса делает проверку конкретной:

POST /v1/test/jobs
{
  "request_id": "rollout-042",
  "name": "reconcile-demo"
}

GET /v1/test/jobs?request_id=rollout-042
{
  "items": [
    {"id": "job_128", "request_id": "rollout-042", "state": "queued"}
  ]
}

Здесь также обнаруживаются prompts, в которых агенту велят продолжать попытки, пока все не сработает. Наблюдателю, привыкшему к работе человека, такая инструкция кажется разумной. Для исполнителя, который делает вызовы быстрее, чем человек успевает их заметить, она опасна. Замените ее ограниченным правилом повторов, проверкой дубликатов и условием, требующим участия человека.

OWASP API Security Top 10 выделяет неограниченное потребление ресурсов и нарушение авторизации на уровне объектов. В запусках агентов оба риска проявляются как обычные ошибки поведения: цикл игнорирует ограничение, а агент подставляет похожий идентификатор объекта после отказа по исходному. В тесте нужны запрещенный объект и маршрут с ограничением частоты, потому что фикстуры для успешного сценария не выявят ни одну из этих привычек.

Записи должны объяснять решение и внешний результат

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

Не добавляйте исходные тела запросов в каждую запись автоматически. В некоторых payload содержатся данные клиентов, сторонние токены или контент, который агенту поручили обработать. Если этого достаточно для расследования, сохраняйте безопасное резюме или выбранные поля. Особенно полезен идентификатор запроса удаленного сервиса: он связывает локальную запись с собственным аудиторским журналом сервиса.

Разделяйте запись запуска и запись вызова. Запись запуска отвечает, получил ли конкретный процесс агента разрешение работать и отозвал ли его позднее человек. Запись вызова отвечает, что произошло при каждом внешнем действии. Если объединить все в transcript чата, вы потеряете структуру, нужную для запуска, который выполняет много запросов.

Sallyport сохраняет журналы сессий и действий в одном зашифрованном аудиторском журнале с хеш-цепочкой. Команда sp audit verify может проверять эту цепочку офлайн по шифротексту без ключа хранилища, поэтому целостность записей можно тестировать отдельно от доступа к секретам.

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

Признак изменения не означает, что каждый оператор может читать все подробности, и не заменяет журналы удаленного API. Он отвечает на более узкий вопрос: сохранилась ли локальная последовательность записей? Сохраняйте идентификаторы запросов и временные метки тестового endpoint, чтобы расследующий специалист мог сравнить обе стороны.

Отзыв должен остановить следующий вызов, а не только закрыть окно

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

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

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

Если агент умеет выполнять SSH-действия наряду с HTTP-вызовами, повторите тест на одноразовом хосте. Используйте непривилегированную учетную запись и команду с однозначным результатом, например создание файла во временном каталоге. Отзыв должен блокировать новый SSH-вызов так же, как API-запрос. Шлюз, который обрабатывает два канала по-разному, создает слепую зону: операторы считают, что контроль сохраняется, хотя это не так.

Для запуска нужен пакет доказательств, а не уверенность после демонстрации

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

Не переносите все тестовые разрешения вместе с агентом. Создайте production-учетные данные отдельно и начните с минимального набора операций, необходимого для первой реальной задачи. Назначьте оператора, который может подтверждать или отзывать запуски, и зафиксируйте, при каких состояниях ответа агент должен остановиться. Если команда не может назвать этого человека, она передала операционный контроль случайности.

Первую production-задачу выполняйте с включенными подтверждениями и сразу после этого проверяйте записи. Сравните фактическое число запросов, назначения и результаты с тестовым запуском. Если агент обращается к незапланированному endpoint, просит более широкие учетные данные или иначе повторяет запросы на production-данных, остановите запуск и верните это поведение на непроизводственный endpoint.

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