Безопасность API-ключа: подключение шлюза без утечки секретов

API-ключи — самая ценная мишень для AI-агентов. Разбираем, как MCP-серверы, tool calling и подстановка контекста превращают учётные данные в уязвимость, и даём воспроизводимый чеклист проверок для CI/CD.

Диаграмма безопасности MCP-сервера — маршруты передачи API-ключа между агентом, LLM и внешними сервисами с контрольными точками проверки

Ключ стороннего API-шлюза и данные запроса передаются его серверу. Поэтому проверяют четыре разные вещи: где хранится ключ, куда клиент его отправляет, что попадает в запрос и что остаётся в журналах. Правильный ответ нейросети не подтверждает безопасность обработки данных.

Ниже — законченная локальная проверка адреса и маскирования на фиктивном ключе, затем отдельные команды для чтения статистики Zenith. Возможности OpenAI staging-проектов не приписываются стороннему сервису. Локальная проверка не делает запросов и не доказывает сетевую безопасность.

Хранение ключа и разделение сред

OpenAI рекомендует хранить серверные ключи в защищённом secret-management service, ограничивать доступ и регулярно менять ключи. Его отдельные staging-проекты позволяют разделять разработку и production и задавать проектные ограничения скорости и расходов. Это функции OpenAI; наличие аналогичных проектов, прав, сроков и квот у Zenith из этого не следует.

При плановой ротации без признаков утечки создайте замену, переключите приложение, проверьте его и отзовите прежний ключ. При компрометации приоритет другой: немедленно отозвать или заблокировать раскрытый ключ и при необходимости остановить интеграцию. Очистка репозитория не отменяет утечку.

Шлюзовая архитектура может держать ключ поставщика на сервере, выдавать разработчикам отдельные credentials и централизовать аудит/расходы. Это возможная архитектура, не гарантия таких функций у каждого агрегатора. Общий ключ не включают в браузерный bundle; переменная окружения сама по себе не защищает от доступа к процессу и диагностике.

Локальная проверка: адрес и журнал

Это демонстрационный тест зашитого allowlist и маскирования на фиктивном объекте. Он не читает адреса, конфигурацию или журналы вашей интеграции: их сопоставляют отдельно, без включения реального секрета в демонстрацию. Сохраните код как gateway_safety_demo.py и выполните python gateway_safety_demo.py. Нужна только стандартная библиотека Python. Конкретный локальный запуск 28.10.2026 выполнен на фиктивных данных: Python 3.14.3, Windows. SHA-256 файла: d9357a01017478d16557aa4aac2d689e6e62af1cac3b2b0ac53562e865ccd8a1. HTTP не выполнялся; результат относится к этому примеру, а не к безопасности вашей системы. Он создаёт объект запроса в памяти, не отправляет HTTP и не прикладывает содержимое файлов проекта.

import json
from urllib.parse import urlsplit
from urllib.request import Request

def validate_url(url):
    try:
        s=urlsplit(url);port=s.port;hostname=s.hostname
    except ValueError:
        raise ValueError("Некорректный синтаксис URL") from None
    if (s.scheme != "https" or hostname != "api.zenithmarket.dev"
        or s.username or s.password or port not in (None,443)
        or s.query or s.fragment or s.path != "/v1/chat/completions"):
        raise ValueError("Адрес вне allowlist этого примера")
    return url

def redact(value):
    sensitive = {"authorization","api_key","x-api-key","x-goog-api-key"}
    if isinstance(value,dict):
        return {k:"[REDACTED]" if k.lower() in sensitive else redact(v)
                for k,v in value.items()}
    if isinstance(value,list):
        return [redact(v) for v in value]
    return value

url = validate_url("https://api.zenithmarket.dev/v1/chat/completions")
request = Request(url,
    data=json.dumps({"model":"MODEL_FROM_CURRENT_CATALOG",
        "messages":[{"role":"user","content":"Заказ TEST-001, сумма 100 условных единиц"}]}).encode(),
    headers={"User-Agent": "Comrad404SourceReview/1.0", "Authorization":"Bearer DUMMY_NOT_A_REAL_KEY","Content-Type":"application/json"},
    method="POST")
# Constructing Request does not perform an HTTP request.
print("prepared:",request.full_url)
print("masked:",json.dumps(redact({"User-Agent": "Comrad404SourceReview/1.0", "Authorization":"Bearer DUMMY_NOT_A_REAL_KEY"})))
for bad in ("http://api.zenithmarket.dev/v1/chat/completions",
            "https://api.zenithmarket.dev.evil.example/v1/chat/completions",
            "https://[bad/v1/chat/completions"):
    try:
        validate_url(bad)
    except ValueError:
        print("blocked:",bad)
    else:
        raise AssertionError("Недопустимый URL прошёл проверку")

Получены строки prepared с разрешённым HTTPS-адресом, masked с [REDACTED] и три blocked — для HTTP, похожего чужого домена и некорректного синтаксиса URL. Это проверяет работу конкретного локального allowlist и маскирования названных полей. Вложенные словари и списки обрабатываются, но секрет в произвольном тексте, crash dump или нестандартном поле этот пример не обнаружит.

Allowlist URL не проверяет DNS, сертификат, локальный прокси и инфраструктуру поставщика. Для реального клиента сохраняйте проверку TLS и запрещайте автоматическое следование редиректу с ключом. Документация Zenith предписывает отправлять его ключ только https://api.zenithmarket.dev и не пересылать сторонним доменам. Это правило настройки пользователя, не техническая гарантия ограничения ключа.

Чтение статистики с настоящим ключом

Следующий отдельный пример пытается выполнить два HTTP GET и сообщает результат каждого; он требует действующий ключ Zenith и не вызывает генерацию. Ожидаемый результат — HTTP 200 и JSON для этих двух адресов в редакционной проверке 28.10.2026; это описание наблюдения, а не контракт сервиса для любого ключа или будущей версии API. Пример ниже не проверяет схему ответа, поэтому принимает любой JSON как успех. Установите python -m pip install requests, сохраните zenith_stats_check.py, запустите python zenith_stats_check.py. Ключ вводится скрыто; значения приватной истории и заголовок не печатаются.

import getpass
import requests

key=getpass.getpass("Zenith API key: ")
if not key:
    raise SystemExit("Ключ не введён")
failed=False
for path in ("stats","usage"):
    try:
        response=requests.get("https://api.zenithmarket.dev/v1/zenith/key/"+path,
            headers={"User-Agent": "Comrad404SourceReview/1.0", "Authorization":"Bearer "+key},timeout=30,allow_redirects=False)
        if response.is_redirect:
            failed=True
            print(path,"redirect blocked")
            continue
        if response.status_code!=200:
            failed=True
            print(path,"HTTP",response.status_code,"— чтение не подтверждено")
            continue
        data=response.json()
        required={"stats":["data"],"usage":["data"]}
        missing=[field for field in required[path] if field not in data]
        if missing:
            failed=True
            print(path,"HTTP 200, но нет полей:",missing)
            continue
        print(path,"HTTP 200; обязательные поля на месте")
    except (requests.RequestException,ValueError):
        failed=True
        print(path,"не удалось получить JSON; автоматического повтора нет")
if failed:
    raise SystemExit("Проверка выполнена не полностью")

Этот результат относится к наблюдению 28.10.2026 для конкретного ключа и клиента. Он подтверждает успешное чтение двух адресов данным ключом и наличие поля data, а не стабильную схему и не доступность конкретной модели, остаток денег или отсутствие списания за прежнюю генерацию. Схема денежных полей здесь не установлена; при ошибке одного запроса проверка неполная. Для выяснения операции сопоставляют только реально возвращённые сервисом время, ID, категории и сумму; отсутствующее значение нельзя считать нулём.

Перед первым запросом генерации

  1. Выберите доступные именно вашему сервису права и лимиты; если их наличие не документировано, не считайте их включёнными.
  2. Возьмите синтетический заказ из примера, а не клиентский договор. Не включайте файлы, историю проекта и персональные данные.
  3. Запишите точные домен, endpoint, model ID и протокол. Уберите автоматические повторы до проверки неопределённого результата.
  4. При генерации возможен расход баланса. Сохраните обезличенный статус и usage, если он возвращён. Затем ограничьте дальнейшее распространение: удалите секрет из доступных текущих журналов, проверьте скриншоты по разделу «Проверка скриншота перед отправкой» ниже, а при попадании в репозиторий перепишите историю специальными средствами. Исходные артефакты для расследования при этом сохраните отдельно, а владельцев резервных и внешних копий уведомите. Отзыв ключа не отменяет копии, которые уже могли быть созданы.

Эта проверка состава отправляемого запроса не является изоляцией агента от файлов. Для агента с инструментами нужны отдельные права, sandbox и проверка его действий; разрешённый endpoint их не заменяет.

Если секрет оказался в публичном месте

  1. Немедленно отзовите/заблокируйте ключ доступным сервису способом. Если функции нет в интерфейсе, используйте документированный канал поддержки и остановите интеграцию.
  2. Проверьте историю расходов за период раскрытия и ограничьте доступ к уже опубликованным материалам.
  3. Очистите секрет из доступных текущих журналов и скриншотов; если он попал в репозиторий, перепишите Git-историю специальными средствами и проверьте результат отдельным поиском.
  4. Уведомите владельцев резервных и внешних копий, чтобы они удалили секрет в своей зоне ответственности; сохранённые для расследования исходные артефакты храните изолированно.
  5. Создайте замену с минимальными доступными правами; переключите сервер и проверьте безопасный вызов.
  6. Повторно проверьте причину утечки: код, bundle, переменная окружения в диагностике, тело ошибки или сторонний endpoint.

Для чувствительных данных отдельно нужны условия хранения, обучения, удаления и передачи поставщикам. Ни совместимый API, ни маскирование журнала не доказывают политику нулевого хранения.

Какие данные уходят при реальном запросе

В минимальном документированном POST передаются секрет авторизации, model и messages; прикреплённые файлы/изображения добавляют свой контент. Это отличается от локального примера выше, который не отправляет HTTP. В политике Zenith описаны технические логи и возможная передача для обработки/диагностики; точный срок хранения каждого prompt не установлен. Поэтому отсутствие публичной публикации не является обещанием нулевого хранения.

import getpass
from pathlib import Path
secret=getpass.getpass("Отозванный ключ для локального поиска: ").encode()
root=Path(input("Каталог логов: ")).resolve()
if not secret: raise SystemExit("Пустая строка не допускается")
hits=[]
for f in root.rglob("*"):
    if f.is_file():
        try:
            if secret in f.read_bytes(): hits.append(str(f))
        except OSError: pass
print("files_with_match:",hits)
print("match_count:",len(hits))

За окно раскрытия сопоставьте реальные requestId, createdAt и стоимость usage, если история доступна; один текущий spentMicrousd не восстанавливает прошлое окно. Маршруты GET /v1/zenith/key/stats и GET /v1/zenith/key/usage перечислены в llms.txt и отвечали 200 в редакционной проверке 28.10.2026. Это не аудит отсутствия злоупотреблений.

Правило документации Zenith сформулировано прямо: «Never forward Zenith keys to third-party domains». Локальный allowlist выше —редакционный пример синтаксической проверки, не ограничение возможностей самого ключа и не проверка DNS/TLS/прокси.

Как сопоставить расход с окном утечки

В наблюдении 28.10.2026 для конкретного ключа и клиента ответ stats содержал поле data.balanceMicrousd, а usage записи находились в data.usage со полями requestId, model, createdAt, status и costMicrousd. Это результат одного наблюдения, а не стабильная публичная схема. Перед обращением к полю проверяйте его наличие: HTTP 200 и наличие JSON сами по себе не подтверждают такую структуру для любого ключа или будущей версии API. Пример GET блокирует редиректы в этом клиенте; поведение вашего DNS, TLS и прокси требует отдельной проверки.

Ниже синтетическая выгрузка: окно раскрытия 09:00–09:15 UTC, нужная модель gpt-6-luna. Пример выбирает только запись r1, суммирует 128 microUSD и выводит $0,000128. Это учебные данные, не реальные операции редакции. Для своей обезличенной выгрузки параметризуйте start и end и получите все страницы истории через документированные параметры пагинации, повторяя запрос, пока сервис возвращает очередную страницу. Затем проверьте полноту: сумма обработанных записей должна совпадать с общим числом, которое возвращает API; при расхождении выборка неполная. Ожидаемый результат — сумма costMicrousd по всем записям окна для нужной модели, а не только по первой странице. Если API не документирует пагинацию или общее число записей, это ограничение следует явно указать.

from datetime import datetime
rows=[{"requestId":"r1","model":"gpt-6-luna","createdAt":"2026-10-28T09:10:00+00:00","status":"success","costMicrousd":128},
      {"requestId":"r2","model":"gpt-6-luna","createdAt":"2026-10-28T09:20:00+00:00","status":"success","costMicrousd":128}]
start=datetime.fromisoformat("2026-10-28T09:00:00+00:00")
end=datetime.fromisoformat("2026-10-28T09:15:00+00:00")
selected=[r for r in rows if r["model"]=="gpt-6-luna" and start<=datetime.fromisoformat(r["createdAt"])<end]
if any(type(r.get("costMicrousd")) is not int for r in selected): raise ValueError("Нет точной суммы")
print([r["requestId"] for r in selected],sum(r["costMicrousd"] for r in selected)/1_000_000)

Для оценки заданной нагрузки: при прочитанных 28 октября ставках Zenith gpt-6-luna $0,016/$0,08 за миллион, 4000/800 токенов стоят 4000×0,016/1000000 + 800×0,08/1000000 = $0,000128. Пять тысяч таких обращений — $0,64. Это условный расход без кэша, комиссий, иных инструментов и повторов, не верхняя граница ущерба: другая модель, длинный вход или дополнительные вызовы меняют сумму. Лимит баланса и своевременный отзыв ключа важнее этой иллюстрации.

Проверка скриншота перед отправкой

Откройте именно итоговое изображение: проверьте поле ключа, заголовки запроса, консоль, уведомления, всплывающие подсказки и наложенные окна. Ищите не только полный секрет, но и приватные данные запроса, адреса, номера заказов и содержимое документов. При обнаружении закройте эти участки непрозрачным слоем или удалите кадр; экспортируйте и снова откройте результат для повторной проверки. Локальный сканер текста в этой статье не анализирует изображения и не выполняет эту проверку за вас.