Files
homelab-infra/AGENTS.md
T
karpenok 090a92174b docs(agents): запретить вывод секретов и требовать сообщать о компрометации
Агент работает через прокси, ключи подставляет прокси, поэтому значения
секретов агенту не нужны. Всё, что попало в вывод команды или тело ответа,
уже в контексте модели, то есть у провайдера.

Добавлены два раздела: что запрещено по умолчанию (печать секретов, поиск
эндпоинтов с креденшлами, выпуск токенов «для проверки») и как сообщать
об утечке — сразу, с именем ключа и местом, без повторения значения,
с предложением отозвать и ротировать.
2026-11-13 21:16:54 +07:00

4.8 KiB

Доступ к сервисам 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. Узнай, что разрешено сессии:
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.

Молча «исправить» утечку нельзя: решение об отзыве и ротации принимает пользователь.