Одобрение агента в macOS должно различать каждую сборку

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

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

Одно имя команды может указывать на несколько исполняемых файлов

Команда оболочки выполняет поиск, а не задает идентичность. Когда вы вводите claude, agent или имя обертки, оболочка может разрешить псевдоним, функцию, shim, символическую ссылку, каталог пакетного менеджера или файл, расположенный в PATH раньше копии, которую вы имели в виду.

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

Сначала выполните:

type -a agent-name
command -v agent-name

Полезный результат может выглядеть так:

agent-name is /Users/me/bin/agent-name
agent-name is /opt/homebrew/bin/agent-name
agent-name is /usr/local/bin/agent-name
/Users/me/bin/agent-name

Вывод говорит, что в этой оболочке первым сработает этот путь. Но он не показывает, является ли /Users/me/bin/agent-name настоящим бинарным файлом, символической ссылкой, скриптом, запускающим другой бинарный файл, или оберткой, которая меняет переменные окружения перед передачей управления.

Сначала разрешите путь, потом проверяйте файл:

BIN="$(command -v agent-name)"
python3 - <<'PY' "$BIN"
import os, sys
print(os.path.realpath(sys.argv[1]))
PY
file "$BIN"

Если file сообщает о shell-скрипте, прочитайте его. Если это символическая ссылка, проверьте адрес назначения. Если это универсальный исполняемый файл Mach-O, изучите его. Обертка может сделать экран одобрения убедительным, а позже запустить другой дочерний процесс.

Не останавливайтесь на текущем победившем варианте. Соберите все результаты type -a, а также копии в папке Applications поставщика, в Downloads, в checkout исходного кода и в хранилищах пакетного менеджера. Копия, которая побеждает сегодня, может уступить завтра после обновления пакетного менеджера или небольшой правки PATH.

Путь показывает расположение, но не подтверждает идентичность

Команды часто начинают с правила по пути, потому что путь легко прочитать. /Applications/Agent.app выглядит намеренно выбранным. /Users/me/dev/agent/bin/agent похож на экспериментальный вариант. Это полезные подсказки, но один путь не доказывает, какой код сейчас находится по этому адресу.

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

Используйте в инвентаризации четыре отдельных поля:

Это различие важно, потому что каждое поле меняется с разной скоростью. Обновление поставщика может сохранить путь и designated requirement, изменив хеш. Бета-версия может оставить ту же подписывающую сторону, но использовать другой идентификатор пакета. Локальная сборка может иметь ту же ревизию исходного кода, что и релиз, но быть подписана самоподписанной подписью или не иметь подписи вовсе.

В Technical Note TN2206 Apple объясняет назначение designated requirement: он должен совпадать с легитимными обновлениями программы и исключать посторонний код. Это механизм непрерывности. Но он не отвечает универсально на вопрос «это именно тот бинарный файл, который я хотел одобрить?». Apple также отмечает, что требование по умолчанию синтезируется из параметров подписи, поэтому его ширина зависит от способа подписи сборки разработчиком.

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

Изучите подпись до создания правила одобрения

Для каждого подходящего исполняемого файла сохраните сведения о подписи и его хеш. Следующие команды используют только встроенные средства macOS и shasum:

inspect_agent() {
  target="$1"
  echo "=== $target ==="
  echo "Resolved path: $(python3 - <<'PY' "$target"
import os, sys
print(os.path.realpath(sys.argv[1]))
PY
)"
  shasum -a 256 "$target"
  codesign --display --verbose=4 "$target" 2>&1 \
    | grep -E '^(Executable|Identifier|TeamIdentifier|Authority|CDHash)='
  codesign --display -r- "$target" 2>&1 \
    | sed -n '/designated/,$p'
  codesign --verify --strict --verbose=2 "$target" 2>&1
}

inspect_agent "$(command -v agent-name)"

Важна структура вывода, а не конкретная строка поставщика:

=== /opt/homebrew/bin/agent-name ===
Resolved path: /opt/homebrew/Cellar/agent-name/2.4.1/bin/agent-name
3b1f...  /opt/homebrew/bin/agent-name
Executable=/opt/homebrew/bin/agent-name
Identifier=com.example.agent
TeamIdentifier=AB12CDE345
Authority=Developer ID Application: Example, Inc. (AB12CDE345)
CDHash=9c1a...
designated => anchor apple generic and identifier "com.example.agent" and certificate leaf[subject.OU] = "AB12CDE345"
/opt/homebrew/bin/agent-name: valid on disk
/opt/homebrew/bin/agent-name: satisfies its Designated Requirement

Не считайте отображаемый CDHash заменой записи SHA-256. Хеш CodeDirectory относится к механизму подписывания кода и может меняться из-за структуры подписи. shasum -a 256 дает привычный точный отпечаток файла для тестовой записи. При расследовании совпадения сохраняйте оба значения.

Для пакета приложения проверяйте настоящий исполняемый файл, а не только каталог пакета. Найти его можно так:

APP="/Applications/Agent.app"
EXEC="$APP/Contents/MacOS/$(defaults read "$APP/Contents/Info" CFBundleExecutable)"
inspect_agent "$EXEC"

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

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

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

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

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

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

label: stable
launch path: /Applications/Agent.app/Contents/MacOS/agent-name
resolved path: /Applications/Agent.app/Contents/MacOS/agent-name
version: 2.4.1
identifier: com.example.agent
team or authority: AB12CDE345
sha256: 3b1f...
designated requirement: anchor apple generic and identifier "com.example.agent" ...
expected approval group: release

label: local
launch path: ~/src/agent/build/agent-name
resolved path: /Users/me/src/agent/build/agent-name
version: git revision recorded separately
identifier: ad hoc or absent
team or authority: none
sha256: 8e52...
designated requirement: unavailable or different
expected approval group: local only

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

Неловкий случай, это две строки с одинаковыми identifier, team и designated requirement, но разными хешами. Это не обязательно дефект. Значит, поставщик создал две сборки, которые macOS может считать экземплярами одной программы. Если вы хотите, чтобы одобрение следовало за каналом релизов поставщика, это может быть приемлемо. Если одобрение должно распространяться только на конкретный артефакт релиза, правило слишком широкое.

Неправильный тест одобряет каждую копию по отдельности

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

Выполните эту последовательность в одноразовой учетной записи или с учетными данными, которые не могут менять рабочие системы:

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

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

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

ssh [email protected] 'id; hostname; date -u +%FT%TZ'

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

Типичный сбой выглядит так. Разработчик одобряет стабильное приложение, затем устанавливает бета-версию, добавившую /Users/me/bin перед /Applications через изменение настроек оболочки. Имя команды не меняется. Бета-версия выполняет вызов без нового запроса, потому что проверка авторизации распознает общую идентичность подписи или слишком широкую группу процессов. Никто этого не замечает, поскольку исходный стабильный процесс все еще работает, а в аудите указано лишь agent-name. Такой сбой предотвращает перекрестный тест, а не чтение заметок к релизу.

Идентичность процесса и точные байты отвечают на разные вопросы

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

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

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

Опасная середина, считать идентификатор подписи единственной идентичностью. Apple документирует, что один идентификатор подписи могут заявлять несколько подписантов. Apple рекомендует при проверке кода сочетать его с подходящими ограничениями проверки и команды. На практике Identifier=com.example.agent без authority или team, это всего лишь метка, которую может повторно использовать кто-то другой.

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

Запишите решение о группе простыми словами рядом с инвентарной записью. Например:

Release group: accept future vendor-signed builds with the release identifier.
Beta group: separate, even when signed by the same vendor identity.
Local group: exact SHA-256 only; rebuild requires another approval.

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

Одобрение сессии не заменяет одобрение каждого вызова

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

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

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

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

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

Пакетные менеджеры и shim скрывают нужный исполняемый файл

Пакетные менеджеры часто устанавливают стабильные входные пути, указывающие в другое место. Команда в /opt/homebrew/bin/agent-name может быть символической ссылкой на каталог Cellar с версией. Другой инструмент может устанавливать shim на JavaScript, Python или shell, который выбирает среду выполнения, а затем загружает пакет из кэша.

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

ls -l "$(command -v agent-name)"
readlink "$(command -v agent-name)" || true
head -n 40 "$(command -v agent-name)" 2>/dev/null || true

В macOS readlink может показать только один переход. Небольшой Python-резолвер из первого раздела надежнее показывает конечную цель. Если входной файл является скриптом, ищите exec, вызовы сред выполнения, пути скачанных бинарных файлов и переменные окружения, выбирающие канал релиза.

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

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

Локальные сборки должны явно оставаться локальными

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

Сначала проверьте состояние подписи:

LOCAL="$HOME/src/agent/build/agent-name"
codesign --display --verbose=4 "$LOCAL" 2>&1 | sed -n '1,25p'
codesign --verify --strict --verbose=2 "$LOCAL" 2>&1
shasum -a 256 "$LOCAL"

Неподписанный файл, самоподписанная и разработческая подписи не взаимозаменяемы. Неподписанный исполняемый файл дает уровню одобрения менее надежные сведения об идентичности. Самоподписанная подпись может создать видимость подписи, не связывая файл с идентичностью разработчика. Разработческая подпись указывает на контекст разработки, но не превращает файл в артефакт релиза.

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

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

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

Запись «агент одобрен» сама по себе дает слабое подтверждение. Через шесть недель вы не поймете, пришла ли одобренная программа из стабильного установщика, бета-папки, символической ссылки пакетного менеджера или локального checkout.

Для каждого теста и значимого изменения сохраняйте:

• путь запуска и конечный разрешенный путь
• идентификатор подписи, authority или team и текст designated requirement
• хеш SHA-256 и версию приложения
• идентификатор процесса, время запуска и результат сессии
• целевой объект действия и результат отдельного вызова

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

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

Превратите это в регрессионный тест, а не разовую уборку

Несколько копий появятся снова. Кто-то установит бета-версию для проверки исправления. Пакетный менеджер обновится ночью. Коллега поделится локальной сборкой. Стабильное приложение обновится на месте. Если проверять все только после тревожного сигнала, конфликт обнаружится, когда агент уже получит доступ.

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

#!/bin/zsh
set -eu

for candidate in \
  "/Applications/Agent.app/Contents/MacOS/agent-name" \
  "/opt/homebrew/bin/agent-name" \
  "$HOME/src/agent/build/agent-name"; do
  [[ -e "$candidate" ]] || continue
  echo "### $candidate"
  echo "resolved: $(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$candidate")"
  shasum -a 256 "$candidate"
  codesign --display --verbose=4 "$candidate" 2>&1 \
    | grep -E '^(Identifier|TeamIdentifier|Authority|CDHash)=' || true
  codesign --display -r- "$candidate" 2>&1 \
    | grep 'designated' || true
  echo
 done

Сравнивайте отчет с последней проверенной копией. После обновления изменение хеша ожидаемо. Изменение подписывающей стороны, идентификатора или designated requirement требует отдельного решения, прежде чем считать обновление обычным. Новому пути, появившемуся перед путем релиза в type -a, нужно уделить такое же внимание.

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