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. + +Молча «исправить» утечку нельзя: решение об отзыве и ротации принимает пользователь. +