From 090a92174b0fc48be1a78293459935bdd04168ae Mon Sep 17 00:00:00 2001 From: karpenok Date: Fri, 13 Nov 2026 21:16:54 +0700 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=D0=B7=D0=B0=D0=BF=D1=80=D0=B5?= =?UTF-8?q?=D1=82=D0=B8=D1=82=D1=8C=20=D0=B2=D1=8B=D0=B2=D0=BE=D0=B4=20?= =?UTF-8?q?=D1=81=D0=B5=D0=BA=D1=80=D0=B5=D1=82=D0=BE=D0=B2=20=D0=B8=20?= =?UTF-8?q?=D1=82=D1=80=D0=B5=D0=B1=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20=D1=81?= =?UTF-8?q?=D0=BE=D0=BE=D0=B1=D1=89=D0=B0=D1=82=D1=8C=20=D0=BE=20=D0=BA?= =?UTF-8?q?=D0=BE=D0=BC=D0=BF=D1=80=D0=BE=D0=BC=D0=B5=D1=82=D0=B0=D1=86?= =?UTF-8?q?=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Агент работает через прокси, ключи подставляет прокси, поэтому значения секретов агенту не нужны. Всё, что попало в вывод команды или тело ответа, уже в контексте модели, то есть у провайдера. Добавлены два раздела: что запрещено по умолчанию (печать секретов, поиск эндпоинтов с креденшлами, выпуск токенов «для проверки») и как сообщать об утечке — сразу, с именем ключа и местом, без повторения значения, с предложением отозвать и ротировать. --- AGENTS.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e0f4d03 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,53 @@ +# Доступ к сервисам homelab + +Прокси Agent Vault на этой машине уже запущен. Сессию запускать не нужно. Токен в репозиторий не класть и у пользователя не спрашивать. + +- Прокси: `127.0.0.1:17323` +- Infisical: `https://infisical.gunihome.ru` +- Токен сессии: единственная строка файла `.agent-vault-session` в корне этого репозитория +- CA прокси: `http://127.0.0.1:17323/_agent-vault/ca`, поле `certificate` + +Запросы к сервисам homelab отправляй через этот прокси. Прокси из окружения редактора для них не использовать. + +1. Прочитай токен из `.agent-vault-session` в корне этого репозитория. +2. Скачай CA и сохрани сертификат в файл. +3. Узнай, что разрешено сессии: + +```bash +curl -sS --proxy "http://x-agent-vault:${TOKEN}@127.0.0.1:17323" \ + --cacert /tmp/av-ca.pem \ + https://infisical.gunihome.ru/api/v1/agent-vault/session/services +``` + +В ответе имена сервисов, хосты, методы и пути. Ключей там нет. Ходи только в то, что вернул список. + +Если этот адрес отвечает 404, список на текущей версии Infisical ещё не отдаётся. Тогда сервис берётся из запроса пользователя, а прокси сам решает, есть ли он в access bundle. Отказ прокси — это не повод просить ключ: сессия его не отдаёт. + +Ответ **407** значит, что токен не подставился. Ответ **403** с текстом про недействительную сессию значит, что токен в файле протух: остановись и скажи об этом. Ответ **502** про сертификат upstream значит, что прокси не доверяет CA целевого сервиса. + +Proxmox `netcore` — один из сервисов бандла, не единственный: `https://192.168.1.100:8006/api2/json/...`. + +## Секреты + +Значения ключей, токенов и паролей агенту не нужны: прокси подставляет их сам. Поэтому: + +- Не читай и не печатай значения секретов: `cat .env`, `infisical secrets get --plain`, `ansible-playbook -vvv` с телами запросов, дампы переменных. +- Не клади секреты в файлы, коммиты, тикеты и во внешние сервисы. +- Не ищи эндпоинты, которые возвращают креденшлы, и не выпускай новые токены «чтобы проверить». +- Проверяй наличие секрета по метаданным (имя, дата создания, `last_used`), а не по значению. + +Всё, что попало в вывод команды или в тело ответа, считается переданным в облако агента: контекст модели уходит провайдеру и может сохраняться в логах. + +## Уведомление о компрометации + +Сообщи пользователю **немедленно и явно**, если значение секрета попало в контекст: в вывод команды, в тело HTTP-ответа, в лог прогона, в файл, который ты прочитал, или в ответ сервиса, вернувшего креденшл. Подозрение на утечку — тоже повод сообщить. + +Порядок действий: + +1. Останови текущую задачу: сообщение важнее её результата. +2. Назови, что утекло: сервис, имя ключа (например `NETBIRD_API_TOKEN`), где именно оказалось, когда. +3. Значение не повторяй — максимум префикс и длину. +4. Предложи конкретные шаги: отозвать ключ и выпустить новый там, где он создаётся, обновить секрет в Infisical, перезапустить затронутый пайплайн. Если утёк session-токен из `.agent-vault-session` — отозвать сессию в Infisical. + +Молча «исправить» утечку нельзя: решение об отзыве и ротации принимает пользователь. +