Security Blog

Як передати ШІ-агенту API-ключ, щоб він не бачив самого ключа?

#44

November 20, 2026 · By Mila

← All posts

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

Дайте агентові посилання замість ключа, і нехай невеликий проксі на тій самій машині підставляє справжній ключ у запит на виході. Агент записує clavitor://OpenAI/key там, де мав би бути секрет. API отримує справжній ключ. Агент ніколи його не тримає, тож не може його надрукувати, занотувати в журнал або бути вмовлений його віддати.

Це й є вся ідея. Решта цієї сторінки — чому це важливо і як це налаштувати.

Чому «просто покладіть у змінну середовища» перестало бути прийнятним

Рік тому export OPENAI_API_KEY=sk-... був звичайним способом передати ключ скрипту. Ніхто не здивувався.

Потім скрипт почав думати сам.

ШІ-агент читає файли, запускає інструменти, веде журнали й розмовляє з незнайомцями в інтернеті. Кожне з цих — шлях назовні для ключа, який він тримає:

  • Середовище. Усе, що запускає агент, його успадковує. Він з'являється в /proc, у дампах збоїв, у виводі CI.
  • Пам'ять. Отримайте ключ під час виконання — і він усе одно залишається в процесі, доки працює агент.
  • Розмова. Вставлення промпту на вебсторінці або в коментарі до задачі просить агента «додати свою конфігурацію для налагодження». Послужливий агент це робить.

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

Патерн: агент просить, проксі підписує

Уявіть картку-ключ у готелі. Гість може відчинити свій номер. Гість ніколи не бачить майстер-ключа, а двері реєструють кожне прикладання.

Для API-ключа це виглядає так:

  1. Справжній ключ зберігається у сховищі, зашифрований.
  2. Проксі працює поруч з агентом, на тій самій машині.
  3. Агент надсилає свій HTTPS-запит із посиланням там, де мав би бути ключ.
  4. Проксі отримує значення зі сховища, підставляє його в запит і переспрямовує.
  5. На боці агента лишається лише посилання.

Журнали агента показують посилання. Так само і його вікно контексту. Витікати нічому.

Як налаштувати це з Clavitor

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

Створіть клієнта для агента у своєму сховищі з потрібними йому областями доступу, потім зареєструйте проксі та запустіть його:

$ clavitor-proxy init
$ clavitor-proxy ca
$ clavitor-proxy serve

init реєструє проксі як цього клієнта. ca виводить центр сертифікації проксі: додайте його до сховища довіри, яким користується HTTP-клієнт вашого агента, бо проксі сам відкриває HTTPS-з'єднання агента. Потім спрямуйте агента на проксі:

$ export HTTPS_PROXY="http://clavitor:$(cat proxy-auth)@127.0.0.1:1983"

$ curl -H "Authorization: Bearer clavitor://OpenAI/key" \
    https://api.openai.com/v1/chat/completions

proxy-auth — це власний токен доступу проксі, файл поруч із бінарним файлом. Кожне з'єднання мусить його містити, тож інший користувач на тій самій машині не зможе скористатися проксі. Проксі слухає на 127.0.0.1:1983 і лише на цій машині, якщо ви навмисно не налаштували його для довіреної приватної мережі.

Це працює з будь-яким агентом, чий HTTP-клієнт враховує HTTPS_PROXY: Claude Code, Codex, ваші власні скрипти. Облікові дані потрапляють лише до хоста, вказаного в його записі як вебадреса, тож агент із вставленим промптом не може спрямувати те саме посилання на сервер незнайомця. Покрокове налаштування описано в документації проксі.

А що з іншими секретами агента?

Не кожен секрет подорожує в HTTP-заголовку. Пароль для розгортання, SSH-ключ, код двофакторної автентифікації для входу.

Для них агент запитує у сховищі по одному іменованому запису за раз через clavitor-cli, і лише ті записи, які йому надані:

$ clavitor-cli get "GitHub Deploy" --field password

$ clavitor-cli get "Stripe API" --field key
clavitor-cli: CV-2041: Access denied.

Агент не може переглянути список сховища. Пошук за назвою показує щонайбільше п'ять збігів назв, а понад це — лише їхню кількість.

Коди автентифікатора працюють так само. clavitor-cli totp "GitHub" обчислює поточний код на машині агента, тож він може пройти двофакторний вхід, і нікому не треба зазирати в телефон. Сховище тримає секрет зашифрованим.

Чого це не вирішує

Проксі тримає ключ поза агентом. Він не робить агента довіреним.

  • Скомпрометований агент усе одно може скористатися наданим йому доступом. Він просто не може забрати ключ із собою.
  • Той, хто має адміністративний доступ до машини, теж може скористатися проксі або прочитати його пам'ять.
  • API, який повертає ваш ключ у відповіді, віддає його агентові. Проксі підставляє ключі в запити й не фільтрує відповіді.

Тому доступ навколо не менш важливий, ніж сам проксі:

  • Область доступу. Кожен агент отримує лише потрібні йому записи. Робочий агент бачить GitHub і AWS. Агент розгортання бачить SSH-ключі та базу даних.
  • Ліміти читання. Кожен агент може читати лише певну кількість різних записів за хвилину й за годину, і ці числа встановлюєте Ви. Агент, який двічі протягом двох годин перевищить свій годинний ліміт, блокується, доки Ви його не розблокуєте.
  • Журнал. Кожне читання реєструється: який агент, який запис, коли.

Запускаєте кілька агентів? Дайте кожному власний проксі та власну реєстрацію. Тоді кожен має власну область доступу, власні ліміти й власний слід, і агент A не бачить ключів агента B.

Коротко

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

Налаштуйте проксі або погляньте, як працює доступ агентів.