Плейбук DevSecOps / ML-инженера

Note

Spectorn в промышленном API-пути работает как OpenAI-compatible gateway. Приложение меняет base_url на https://spectorn.xyz/v1, а Spectorn уже аутентифицирует tenant, сканирует вход, выбирает provider, форвардит безопасный запрос и сканирует ответ.

1. Минимальная интеграция

Python

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://spectorn.xyz/v1",
    api_key=os.environ["SPECTORN_API_KEY"],
)

response = client.chat.completions.create(
    model="openrouter/deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "Say ok."}],
    max_tokens=64,
)

Для реального chat/completions нужен upstream provider. Его можно:

сохранить в личном кабинете на странице Providers;
добавить API-вызовом PUT /v1/providers;
передать как BYOK через X-Provider-Key, если маршрут настроен на default upstream.

/v1/scan полезен как самый быстрый smoke-test gateway: он требует только ключ Spectorn и не обращается к внешней модели.

2. Provider как код

Shell

curl -X PUT https://spectorn.xyz/v1/providers \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openrouter",
    "base_url": "https://openrouter.ai/api/v1",
    "api_key": "'$OPENROUTER_API_KEY'",
    "is_default": true
  }'

Сохраняйте provider-настройки как часть tenant bootstrap. Ключи provider шифруются на стороне gateway и не возвращаются обратно в UI/API в открытом виде.

3. CI/CD проверки

Перед релизом приложения прогоняйте:

GET /v1/health — gateway жив и возвращает версию сборки.
POST /v1/scan с benign и malicious payload — проверка fail-closed пути.
POST /v1/chat/completions на коротком cheap model — проверка provider routing и billing path.
Проверка, что X-Spectorn-Session работает только там, где нужна gateway memory.

4. Наблюдаемость

Смотрите не только latency, но и:

долю blocked/shadow verdicts;
provider route, model и fallback;
ошибки no_provider, model_blocked, provider_unreachable;
usage/cached tokens для экономики;
scan mode tenant policy: enforce или shadow.

Latency не является универсальным сетевым обещанием: измеряйте её на своём регионе, provider, модели, размере prompt и stream/non-stream режиме.

5. Что не заявляем

Нет требования направлять приложение на локальный sidecar-порт в SaaS-пути.
Нет blanket latency-обещания для сетевого API.
Нет “магической” защиты без provider/model: scan доступен сразу, chat требует upstream.

Implementation Guide for: DevSecOps / ML Engineer

Gateway-first integration