Чтобы защитить API-ключ LLM, храните его в менеджере секретов и вызывайте модель только со своего сервера, никогда — из браузера или приложения. Выдайте каждой нагрузке свой ключ, ротируйте ключи по графику, привяжите их к IP своих серверов белым списком, а утёкший ключ сначала отзывайте и только потом разбирайтесь.
В этой статье — привычки, которые сохраняют ключи в безопасности, и конкретные механизмы, которые для этого даёт BroadNet Inference. Пошаговые действия в портале — в руководстве по API-ключам и белым спискам IP; о бюджетах и защите от зациклившихся процессов — в статье контроль расходов на LLM API.
Где хранить API-ключ LLM?
Храните ключи в менеджере секретов или в зашифрованных секретах вашей платформы, никогда — в коде. OWASP Secrets Management Cheat Sheet подробно разбирает варианты. Обратите внимание на его предупреждение: переменные окружения “are generally accessible to all processes and may be included in logs or system dumps” (перевод: «обычно доступны всем процессам и могут попасть в логи или системные дампы»), поэтому OWASP, когда есть выбор, предпочитает смонтированные файлы секретов или получение секретов из хранилища. Переменная окружения, которую при запуске заполняет менеджер секретов, — распространённый компромисс.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"], # fails loudly if missing
)
Используйте os.environ[...], а не os.getenv(...) с захардкоженным значением по умолчанию: именно так ключи и попадают в Git. Для локальной разработки файл .env допустим, если он внесён в .gitignore с первого коммита. Включите сканирование секретов и push protection на вашем Git-хостинге. На GitHub push protection блокирует push с секретами известных форматов ещё до того, как они попадут в репозиторий. Push protection для пользователей включена по умолчанию, а на уровне репозитория она по умолчанию выключена, и включить её должен администратор репозитория или владелец организации.
Можно ли положить API-ключ в браузерное или мобильное приложение?
Нет. Всё, что отдано клиенту, можно извлечь. Фронтенд-код и сборки приложений публичны, как бы их ни минифицировали и ни обфусцировали. Вызывайте LLM со своего сервера, аутентифицируйте там своих пользователей и применяйте собственные лимиты на пользователя, прежде чем пересылать запрос дальше.
То же касается десктопных инструментов, которые вы передаёте другим. Если коллеге нужен доступ к агенту для программирования, дайте ему собственный ключ в его собственном аккаунте, а не общий.
Зачем выдавать каждой нагрузке свой ключ?
В BroadNet Inference на аккаунте может быть до десяти действующих ключей. Пользуйтесь этим:
| Метка ключа | Кто использует |
|---|---|
prod-api |
Продакшен-бэкенд |
prod-worker |
Пакетные задания |
staging |
Staging-окружение |
agent-ci |
Агент для программирования в CI |
dev-laptop-<name> |
Локальная разработка |
Если утечёт один ключ, вы отзываете только его, а остальные продолжают работать. Метки к тому же делают использование понятным: видно, какая нагрузка сколько тратит. Называйте ключи по тому, что их использует, а не по тому, кто их создал.
Как белый список IP защищает ключ?
Белый список IP означает, что украденный ключ не сработает нигде, кроме вашей собственной инфраструктуры. В BroadNet Inference:
- Белый список аккаунта принимает до 32 записей: по одному адресу IPv4 или IPv6 или диапазону CIDR на строку.
- Пустой список означает отсутствие ограничений.
- Новые ключи наследуют список аккаунта, если только вы не создаёте ключ с собственным
allowed_ips, который заменяет унаследованный список для этого ключа. - Запрос с адреса вне списка отклоняется с кодом 403 (“refused by model, route or IP policy”, перевод: «отклонено политикой модели, маршрута или IP»).
Создайте ключ с собственным списком через API портала:
curl -X POST https://inference.broadnet.ai/portal/keys \
-H "Authorization: Bearer $BROADNET_PORTAL_CREDENTIAL" \
-H "Content-Type: application/json" \
-d '{"label":"prod-worker","allowed_ips":["203.0.113.7","198.51.100.0/24"]}'
Ответ содержит ключ в открытом виде один раз. Сразу сохраните его в менеджере секретов: прочитать его повторно нельзя. Полные шаги — в руководстве по белым спискам IP.
Белые списки подходят серверам со стабильными исходящими IP: VPS, NAT-шлюзу, фиксированному IP офиса. Для ноутбуков, которые меняют сети, используйте отдельный ключ без списка и держите сумму, которой он рискует, небольшой.
Зачем отделять ключи инференса от административных учётных данных?
BroadNet использует два вида учётных данных:
| Учётные данные | Что позволяют | Где хранить |
|---|---|---|
| Ключ инференса | Запросы к моделям через /v1/* |
Там, где работает приложение |
| Учётные данные портала | Создавать и отзывать ключи, менять разрешённые IP, совершать покупки | Только в вашей автоматизации или админских инструментах |
Документация советует считать любые учётные данные портала полными правами на аккаунт. Никогда не разворачивайте учётные данные портала рядом с приложением. Если сервер приложения взломают, атакующий должен получить один ключ инференса, а не контроль над аккаунтом.
Как часто ротировать API-ключи?
OWASP рекомендует регулярную ротацию, “so that any stolen credentials will only work for a short time” (перевод: «чтобы любые украденные учётные данные работали лишь короткое время»). Ключи BroadNet действуют один год с момента создания, так что заменять каждый ключ всё равно придётся. Сделайте ротацию рутиной:
- Создайте новый ключ с той же схемой меток и тем же белым списком.
- Разверните его рядом со старым или замените секрет и перезапустите приложение.
- Убедитесь, что трафик перешёл на новый ключ.
- Отзовите старый ключ через
DELETE /portal/keys/{alias}.
Поскольку на аккаунте может быть до десяти действующих ключей, старый и новый ключи могут несколько минут работать одновременно, без простоя. Ключи, к которым имел доступ уходящий из команды сотрудник, ротируйте раньше.
Что делать, если ключ утёк?
Если ключ утёк, сначала отзовите его, а потом разбирайтесь. В BroadNet Inference новые запросы прекращаются в течение пяти секунд после отзыва или изменения белого списка; документация объясняет, что решения об авторизации могут оставаться в реплицируемом кэше в течение этого ограниченного интервала.
После отзыва:
- проверьте использование ключа на странице аккаунта или через
GET /portal/usage; - выясните, как он утёк (история коммитов, логи CI, чей-то скриншот);
- ротируйте другие секреты, которые хранились там же.
Отозванный или заблокированный ключ возвращает 401 или 403; загляните в руководство по ошибкам, чтобы мониторинг не считал эти ошибки временными.
Как ключи утекают через логи?
Утечку через логи легко пропустить. Маскируйте заголовок Authorization в отладочных HTTP-логах, системах сбора ошибок и логах доступа прокси. Обращаясь в поддержку, присылайте X-Request-ID, время, маршрут, код состояния и псевдоним ключа (alias), но никогда не сам ключ. По документации BroadNet, портал хранит только хеш каждого ключа, поэтому показать вам потерянный ключ он тоже не сможет.
Как ограничить ущерб от утечки, которую вы ещё не обнаружили?
Даже при соблюдении всех привычек выше исходите из того, что ключ когда-нибудь может утечь. Уменьшите радиус поражения:
- Держите баланс для оплаты по факту на уровне, потерю которого вы готовы пережить, и пополняйте его по мере необходимости.
- Для нагруженных агентов используйте тариф с фиксированной ценой: у сессии тарифа фиксированная цена, поэтому украденный ключ тарифа не накрутит счёт за токены. См. статью что на самом деле значит «безлимитный».
- Настройте оповещения о необычных расходах или частоте запросов по каждому ключу; калькулятор стоимости LLM API даст вам нормальную месячную цифру, относительно которой срабатывают оповещения. Бюджеты и оповещения разобраны в статье контроль расходов на LLM API.
Какие механизмы защиты ключей даёт BroadNet Inference?
| Механизм | BroadNet Inference |
|---|---|
| Ключ показывается один раз, хранится в виде хеша | Да |
| Действующих ключей на аккаунт | До 10 |
| Срок действия ключа | Один год |
| Белый список IP | До 32 записей IPv4, IPv6 или CIDR |
| Белый список на отдельный ключ | Да, allowed_ips при создании |
| Отзыв вступает в силу | В течение пяти секунд |
| Отдельные административные учётные данные | Учётные данные портала |
Ключи защищают ваш аккаунт; нулевое хранение данных защищает то, что вы через него отправляете. Прочитайте о том и другом до запуска.
