Области API-доступа для автономных агентов, которые пишут код

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

Я видел, как команды начинали с персонального токена, потому что агенту нужно было «просто начать работать». Через несколько недель этот токен уже позволял читать все репозитории, к которым разработчик когда-либо имел доступ, менять настройки развертывания и отправлять разрушающие запросы, не имеющие отношения к исходной задаче. Риск создал не агент. Его создала небрежно проведенная граница разрешений.

Задача уже роли

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

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

Описывайте контракты задач глаголами и указывайте конкретные ресурсы. Не пишите «запись в репозиторий». Опишите, что агент действительно может делать:

• Читать исходный код, задачи и существующие пул-реквесты в payments-service.
• Создавать и обновлять ветки, имена которых начинаются с agent/.
• Создавать один пул-реквест из этой ветки в назначенную базовую ветку.
• Читать статус и журналы рабочего процесса, запущенного этим пул-реквестом.
• Публиковать комментарий с результатом тестов.

Это не бюрократия. Такой список выявляет решения, которые еще не приняты. Может ли агент закрыть задачу? Может ли изменить чужой пул-реквест? Разрешено ли ему повторно запускать дорогой рабочий процесс? Нужно ли ему получать пакет из частного реестра? Каждое действие либо получает разрешение, либо исключается.

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

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

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

Строка области доступа это вход для авторизации, а не доказательство безопасности API-вызова. Провайдеры используют слово «область» для разных механизмов: строк OAuth, разрешений репозитория, ролей проекта, прав установки и токенов, ограниченных списком ресурсов. Это не взаимозаменяемые понятия.

OAuth 2.0 RFC 6749 определяет область доступа как разделенный пробелами набор строк, ограничивающий доступ токена. При этом смысл каждой строки намеренно оставлен серверу авторизации. Для провайдеров это удобно, но означает, что repo:write, projects.write и api почти ничего не говорят, пока вы не изучите документацию по эндпоинтам провайдера и не протестируете токен.

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

В документации по дизайну держите отдельно три уровня:

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

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

Составьте реестр эндпоинтов до выдачи токена

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

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

Используйте реестр такого вида. Замените показательные пути путями, которые действительно задокументированы вашим провайдером.

task: update dependency and open pull request
resource: org/payments-service
calls:
  - method: GET
    path: /repos/org/payments-service/contents/package-lock.json
    purpose: read current dependency lockfile
    permission: contents:read

  - method: POST
    path: /repos/org/payments-service/git/refs
    constraint: "ref starts with refs/heads/agent/"
    purpose: create working branch
    permission: contents:write

  - method: PUT
    path: /repos/org/payments-service/contents/package-lock.json
    constraint: "branch starts with agent/"
    purpose: commit updated lockfile
    permission: contents:write

  - method: POST
    path: /repos/org/payments-service/pulls
    constraint: "base is main; head starts with agent/"
    purpose: request review
    permission: pull_requests:write

forbidden_calls:
  - DELETE /repos/org/payments-service
  - PATCH /repos/org/payments-service/branches/main/protection
  - POST /repos/org/organization-hooks
  - GET /repos/org/another-service/contents/secrets.yml

Поле constraint важно, потому что разрешения на уровне эндпоинта часто не доходят до уровня задачи. API может разрешать создание веток, но не иметь встроенного ограничения на префикс agent/. Запишите этот пробел. Может понадобиться промежуточный сервис действий, отдельный репозиторий или этап проверки, поскольку область доступа не умеет задавать нужное правило для веток.

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

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

Разделяйте доступ к исследованию и изменению данных

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

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

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

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

Не разделяйте токены просто ради увеличения их числа. Делайте это, когда отличаются допустимый набор ресурсов или действия. Один токен только для чтения может поддерживать цельное исследование. Один токен для записи может обслуживать тесно связанные изменения в одной цели. Смысл в том, чтобы ответ на вопрос «что может сделать этот процесс?» был достаточно коротким для проверки без догадок.

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

Сначала ограничьте ресурс, потом уточняйте область доступа

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

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

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

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

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

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

Проверяйте успех и отказ как единый контракт

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

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

Практическая последовательность теста выглядит так:

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

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

base="https://api.example.internal"
auth="Authorization: Bearer $AGENT_TOKEN"

curl -sS -o allowed.json -w "%{http_code}\n" \
  -H "$auth" \
  -X POST "$base/repos/acme/payments-service/pulls" \
  -H "Content-Type: application/json" \
  -d '{"head":"agent/dependency-bump","base":"main","title":"Update parser"}'
# Expected output: 201

curl -sS -o denied.json -w "%{http_code}\n" \
  -H "$auth" \
  -X DELETE "$base/repos/acme/payments-service"
# Expected output: 403

cat denied.json
# Expected shape: {"message":"Resource not accessible by integration"}

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

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

Неудачный 403 должен менять задачу или разрешение

Ответ 403 Forbidden дает сведения о контракте. Он должен запускать решение, а не автоматический запрос на самое широкое разрешение провайдера.

Я много раз видел такую последовательность. Агент создает ветку и коммитит исправление, а затем получает отказ при попытке открыть пул-реквест. Кто-то выясняет, что разрешение на пул-реквесты у провайдера также позволяет отклонять проверки или шире редактировать обсуждения. Его выдают, потому что агенту нужно завершить работу. Через несколько дней тот же агент начинает «наводить порядок» в старых пул-реквестах и изменяет то, что не входило в задачу.

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

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

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

Тела запросов тоже требуют проверки. Многие модели разрешений API авторизуют эндпоинт, но не различают безопасные и опасные значения. POST /deployments может принимать staging и production при одном разрешении. PATCH /projects/{id} может разрешать безобидное изменение описания и опасное изменение видимости. Если провайдер не умеет разделить эти операции, граница должна находиться выше эндпоинта. Требуйте подтверждения человека, используйте отдельную цель или предоставьте специально предназначенную операцию вместо доступа к необработанному API.

Записывайте отклоненный вызов в реестре вместе с причиной, по которой вы добавили или отклонили его. Через полгода эта запись объяснит, почему агент может создать ветку, но не может переименовать репозиторий. Без нее кто-то сочтет границу произвольной и расширит ее во время срочного исправления.

Этапы подтверждения ловят оставшиеся важные вызовы

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

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

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

Sallyport хранит API- и SSH-учетные данные в зашифрованном хранилище macOS и выполняет запрошенное действие, не раскрывая секрет агенту. Авторизация сессии и подтверждение для каждой учетной записи могут поставить человека на пути вызовов, которым это нужно, но дизайн областей доступа на стороне провайдера по-прежнему определяет, куда может обращаться подтвержденная учетная запись.

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

Для проверки областей доступа нужен триггер, а не обещание по календарю

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

Храните реестр эндпоинтов рядом с кодом, который вызывает агента. Если пул-реквест меняет инструкции для инструментов агента или добавляет API-вызов, требуйте обновить реестр, а также положительные и отрицательные тесты. Так решение о разрешении находится рядом с поведением, которому оно нужно.

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

Следите за постепенным расширением разрешений в небольших изменениях. Запрос на чтение журналов рабочих процессов может превратиться в разрешение на их повторный запуск. Запрос на обновление одной задачи может превратиться в администрирование задач всей организации. Запрос на доступ к одному окружению может превратиться в резервный доступ к production «на всякий случай». Каждый новый вызов должен пройти одну и ту же проверку: может ли агент завершить заявленную задачу без него?

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