This commit is contained in:
PhimmStraiker 2026-10-31 15:26:53 +08:00 • committed by GitHub
commit 2e406baed9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 2432 additions and 45 deletions

View file

@ -1,6 +1,9 @@
from typing import TYPE_CHECKING, Final
from typing import TYPE_CHECKING, Final, Literal
from pydantic import BaseModel, field_validator
import litellm
from litellm._logging import verbose_proxy_logger
from litellm.types.guardrails import SupportedGuardrailIntegrations
from .straiker import StraikerGuardrail
@ -8,6 +11,26 @@ from .straiker import StraikerGuardrail
if TYPE_CHECKING:
from litellm.types.guardrails import Guardrail, LitellmParams
class _V3Routing(BaseModel):
api_version: Literal["v1", "v3"] | None = None
agent_ref: str | None = None
client: str | None = None
format_hint: Literal["anthropic.messages", "openai.chat"] | None = None
@field_validator("api_version", mode="before")
@classmethod
def _unknown_api_version_is_unset(cls, value: object) -> object:
if value is None or value in ("v1", "v3"):
return value
verbose_proxy_logger.warning(
"Straiker guardrail: ignoring api_version %r, expected 'v1', 'v3' or unset; "
"the route follows the api_key prefix",
value,
)
return None
_OPTIONAL_INIT_FIELDS: Final = (
"timeout",
"max_retries",
@ -48,6 +71,12 @@ def initialize_guardrail(litellm_params: "LitellmParams", guardrail: "Guardrail"
for value in [_get_config_value(litellm_params, optional_params, field)]
if value is not None
}
routing: Final = _V3Routing.model_validate(
{
field: _get_config_value(litellm_params, optional_params, field)
for field in ("api_version", "agent_ref", "client", "format_hint")
}
)
_callback: Final = StraikerGuardrail(
api_key=api_key,
api_base=api_base if isinstance(api_base, str) else "https://api.prod.straiker.ai",
@ -55,6 +84,10 @@ def initialize_guardrail(litellm_params: "LitellmParams", guardrail: "Guardrail"
guardrail_name=guardrail.get("guardrail_name", "straiker"),
event_hook=litellm_params.mode,
default_on=litellm_params.default_on,
api_version=routing.api_version,
agent_ref=routing.agent_ref,
client=routing.client,
format_hint=routing.format_hint,
**kwargs,
)

View file

@ -1,9 +1,12 @@
from __future__ import annotations
import asyncio
import hashlib
import json
import random
from collections.abc import Iterable, Mapping
from dataclasses import dataclass
from types import MappingProxyType
from typing import TYPE_CHECKING, Any, Final, Literal, NoReturn
from urllib.parse import urlsplit
@ -12,6 +15,7 @@ from pydantic import BaseModel, TypeAdapter, ValidationError
from litellm._logging import verbose_proxy_logger
from litellm._version import version as litellm_version
from litellm.caching.in_memory_cache import InMemoryCache
from litellm.exceptions import (
BadRequestError,
GuardrailRaisedException,
@ -29,6 +33,7 @@ from litellm.llms.custom_httpx.http_handler import (
get_async_httpx_client,
httpxSpecialProvider,
)
from litellm.proxy._types import SpecialProxyStrings
from litellm.types.guardrails import GuardrailEventHooks, Mode
from litellm.types.proxy.guardrails.guardrail_hooks.straiker import (
STRAIKER_WEBHOOK_SCHEMA_VERSION,
@ -43,7 +48,7 @@ from litellm.types.proxy.guardrails.guardrail_hooks.straiker import (
StraikerWebhookStream,
StraikerWebhookUsage,
)
from litellm.types.utils import GenericGuardrailAPIInputs
from litellm.types.utils import CallTypes, GenericGuardrailAPIInputs, ModelResponse, TextCompletionResponse
if TYPE_CHECKING:
from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
@ -54,6 +59,94 @@ DEFAULT_BLOCK_MESSAGE: Final = "Content violates policy"
DEFAULT_API_BASE: Final = "https://api.prod.straiker.ai"
DEFAULT_MAX_PAYLOAD_BYTES: Final = 524288
WEBHOOK_PATH: Final = "/api/v1/detect/webhook"
V3_DETECT_PATH: Final = "/api/v3/detect"
V3_KEY_PREFIX: Final = "sk_agt_"
V3_SESSION_HEADER: Final = "x-claude-code-session-id"
V3_CLIENT_HEADER: Final = "x-s6r-client"
V3_FORMAT_HEADER: Final = "x-s6r-format"
# (User-Agent prefix, Straiker client value, display name). Straiker recognises a coding agent
# from the system prompt of its main turns only; Claude Code's title and topic sidecars carry
# other prompts and would split the session across two agents. The User-Agent is on every call.
_V3_CLIENT_BY_USER_AGENT: Final = (("claude-cli/", "claude", "Claude"),)
V3_GATEWAY_NAME: Final = "LiteLLM"
V3_DERIVED_SESSION_PREFIX: Final = "litellm-"
V3_AGENT_HEADER: Final = "x-s6r-agent"
V3_RESPONSE_PHASE: Final = "response-sync"
V3_BLOCK_DECISIONS: Final = frozenset({"block", "deny"})
V3_UNDECIDED: Final = frozenset({"ask"})
V3_BLOCKED_TURN_MEMORY: Final = 10_000
V3_BLOCKED_TURN_TTL_SECONDS: Final = 24 * 60 * 60
# An allowlist: the hook's request dict merges the client body with proxy state (`deployment`
# carries the resolved credential), so only fields named here are relayed.
_V3_PROVIDER_BODY_KEYS: Final = frozenset(
{
"model",
"messages",
"tools",
"tool_choice",
"functions",
"function_call",
"temperature",
"top_p",
"n",
"stream",
"stream_options",
"stop",
"max_tokens",
"max_completion_tokens",
"presence_penalty",
"frequency_penalty",
"logit_bias",
"user",
"response_format",
"seed",
"logprobs",
"top_logprobs",
"parallel_tool_calls",
"reasoning_effort",
"modalities",
"audio",
"prediction",
"store",
"service_tier",
"web_search_options",
"prompt",
"suffix",
"echo",
"best_of",
"system",
"stop_sequences",
"top_k",
"thinking",
"container",
"mcp_servers",
"context_management",
"output_format",
"input",
"instructions",
"previous_response_id",
"truncation",
"text",
"include",
"reasoning",
"max_output_tokens",
"background",
"conversation",
"session_id",
}
)
# The scrub of these is one level deep on purpose: a function schema that defines a `token` or
# `headers` property lives under `function.parameters` and must be relayed as sent.
_V3_CREDENTIAL_FIELDS: Final = frozenset({"authorization_token", "authorization", "headers"})
_V3_REDACTED_VALUE: Final = "[redacted]"
_V3_REDACTED_KEYS: Final = frozenset({"tools", "mcp_servers"})
_V3_IDENTITY_METADATA_KEYS: Final = (
"user_api_key_end_user_id",
"user_api_key_user_email",
"user_api_key_user_id",
"user_api_key_alias",
"user_api_key_team_id",
)
RETRY_STATUS: Final = frozenset({408, 429, 500, 502, 503, 504})
UNREACHABLE_STATUS: Final = frozenset({502, 503, 504})
_APPLICATION_METADATA_KEYS: Final = frozenset({"agent_id", "app_name"})
@ -65,13 +158,29 @@ _JSON_DICT_ADAPTER: Final = TypeAdapter(dict[str, object])
class _WebhookFailure:
message: str
is_unreachable: bool
retryable: bool = False
def _status_failure(status: int, text: str) -> _WebhookFailure:
return _WebhookFailure(
f"HTTP {status}: {text[:200]}",
is_unreachable=status in UNREACHABLE_STATUS,
retryable=status in RETRY_STATUS,
)
def _error_response_text(response: httpx.Response) -> str:
try:
return response.text
except Exception: # noqa: BLE001 # a masked response may carry no body
return ""
def _as_dict(value: object) -> dict:
return value if isinstance(value, dict) else {}
def _merged_metadata(request_data: dict) -> dict:
def _merged_metadata(request_data: Mapping[str, object]) -> dict:
return {
**_as_dict(request_data.get("metadata")),
**_as_dict(request_data.get("litellm_metadata")),
@ -268,6 +377,499 @@ def _is_streamed_request(request_data: dict) -> bool:
return body.get("stream") is True
# What the proxy stamps on a master-key call in place of a person. Sent onward, either
# would be recorded as an identity and every master-key turn filed under it.
_PLACEHOLDER_IDENTITIES: Final = frozenset({SpecialProxyStrings.default_user_id.value, "litellm_proxy_master_key"})
def _real_identity(value: object) -> str | None:
"""LiteLLM's proxy-admin placeholders are not a person."""
identity: Final = _as_optional_str(value)
return None if identity in _PLACEHOLDER_IDENTITIES else identity
def _request_header(request_data: Mapping[str, object], name: str | None) -> str | None:
"""A header from the inbound request, when LiteLLM kept it on the request data."""
if not name:
return None
proxy_request: Final = request_data.get("proxy_server_request")
headers: Final = proxy_request.get("headers") if isinstance(proxy_request, Mapping) else None
if not isinstance(headers, Mapping):
return None
wanted: Final = name.lower()
for key, value in headers.items():
if str(key).lower() == wanted and isinstance(value, str) and value.strip():
return value.strip()
return None
def _frozen(pairs: Iterable[tuple[str, object]]) -> Mapping[str, object]:
return MappingProxyType(dict(pairs))
def _json_default(value: object) -> object:
if isinstance(value, Mapping):
return dict(value) # mutable-ok: the JSON encoder needs a dict view of a frozen mapping
return str(value)
def _v3_identity_metadata(request_data: Mapping[str, object]) -> Mapping[str, str]:
"""The proxy-resolved identity fields, and only those, for the relayed body."""
merged: Final = _merged_metadata(request_data)
return MappingProxyType(
{key: value for key in _V3_IDENTITY_METADATA_KEYS if (value := _real_identity(merged.get(key)))}
)
def _v3_request_body(request_data: Mapping[str, object], request_texts: Iterable[object] = ()) -> Mapping[str, object]:
"""The provider body LiteLLM received, stripped of everything the proxy added.
The hook sees the client's request merged with proxy bookkeeping: logging objects,
the resolved key, the inbound headers. Only the provider body is Straiker's to read,
and the client's Authorization header must not travel. Identity survives as the
metadata subset the Straiker LiteLLM adapter reads. A call with no provider body, such
as /guardrails/apply_guardrail with only `text`, relays `request_texts` as user turns.
"""
identity: Final = _v3_identity_metadata(request_data)
turns: Final = (
_v3_prompt_as_messages(request_data.get("prompt"))
if _v3_text_completion_route(request_data) and "messages" not in request_data
else None
)
texts: Final = tuple(text for text in request_texts if isinstance(text, str) and text)
no_conversation: Final = (
not request_data.get("messages") and "prompt" not in request_data and "input" not in request_data
)
text_turns: Final = (
tuple(_frozen((("role", "user"), ("content", text))) for text in texts)
if turns is None and no_conversation
else ()
)
provider: Final = tuple(
(key, _v3_without_credentials(value) if key in _V3_REDACTED_KEYS else value)
for key, value in request_data.items()
if key in _V3_PROVIDER_BODY_KEYS
and not (turns is not None and key == "prompt")
and not (text_turns and key == "messages")
)
prompt_turns: Final = (
(("messages", turns),) if turns is not None else ((("messages", text_turns),) if text_turns else ())
)
return _frozen((*provider, *prompt_turns, *((("metadata", identity),) if identity else ())))
def _v3_without_credentials(entries: object) -> object:
if not isinstance(entries, (list, tuple)):
return entries
return tuple(
_frozen(
(str(key), _V3_REDACTED_VALUE if str(key).lower() in _V3_CREDENTIAL_FIELDS else item)
for key, item in entry.items()
)
if isinstance(entry, Mapping)
else entry
for entry in entries
)
def _v3_route_is(request_data: Mapping[str, object], call_type: CallTypes) -> bool:
from litellm.litellm_core_utils.api_route_to_call_types import get_call_types_for_route
route: Final = _merged_metadata(request_data).get("user_api_key_request_route")
if not isinstance(route, str) or not route:
return False
return call_type in (get_call_types_for_route(route) or ())
def _v3_anthropic_messages_route(request_data: Mapping[str, object]) -> bool:
return _v3_route_is(request_data, CallTypes.anthropic_messages)
def _v3_text_completion_route(request_data: Mapping[str, object]) -> bool:
return _v3_route_is(request_data, CallTypes.text_completion)
def _v3_is_token_list(value: object) -> bool:
return (
isinstance(value, (list, tuple))
and bool(value)
and all(isinstance(token, int) and not isinstance(token, bool) for token in value)
)
def _v3_decode_tokens(tokens: Iterable[object]) -> str | None:
ids: Final = [token for token in tokens if isinstance(token, int)] # mutable-ok: tiktoken decodes a list
try:
import tiktoken
return tiktoken.encoding_for_model("text-davinci-003").decode(ids)
except Exception: # noqa: BLE001 # no tokenizer available: the raw prompt is relayed instead
return None
def _v3_prompt_texts(prompt: object) -> tuple[str, ...] | None:
"""The text the model receives for a completions `prompt`, in the proxy's own terms.
LiteLLM accepts a string, a list of strings, a list of token ids, or a list of token-id
lists, and decodes token ids with the text-davinci-003 tokenizer before calling the model.
The same decoding here means Straiker screens what the model gets. None when the prompt
is a shape this cannot render, so the caller relays it untouched rather than screening
something else.
"""
if isinstance(prompt, str):
return (prompt,)
if not isinstance(prompt, (list, tuple)) or not prompt:
return None
if all(isinstance(item, str) for item in prompt):
return tuple(str(item) for item in prompt)
if _v3_is_token_list(prompt):
decoded: Final = _v3_decode_tokens(prompt)
return (decoded,) if decoded is not None else None
if all(_v3_is_token_list(item) for item in prompt):
decoded_each: Final = tuple(_v3_decode_tokens(item) for item in prompt)
return None if any(text is None for text in decoded_each) else tuple(text or "" for text in decoded_each)
return None
def _v3_prompt_as_messages(prompt: object) -> tuple[Mapping[str, object], ...] | None:
texts: Final = _v3_prompt_texts(prompt)
if texts is None:
return None
return tuple(_frozen((("role", "user"), ("content", text))) for text in texts)
def _v3_answer(request_data: Mapping[str, object], model: str | None) -> Mapping[str, object] | None:
"""The answer in the API shape the client spoke, which is what a relay forwards.
On a streamed Messages call the proxy rebuilds the answer as a chat completion before
the hook runs. Straiker's coding-agent reader parses a Messages answer, so a Claude Code
turn sent as a chat completion scores nothing; the proxy's own adapter turns it back.
"""
response: Final = request_data.get("response")
if isinstance(response, TextCompletionResponse):
return _v3_text_completion_as_chat(response)
if not isinstance(response, ModelResponse) or not _v3_anthropic_messages_route(request_data):
return _jsonable_dict(response)
from litellm.llms.anthropic.experimental_pass_through.adapters.transformation import (
LiteLLMAnthropicMessagesAdapter,
)
translated: Final = LiteLLMAnthropicMessagesAdapter().translate_openai_response_to_anthropic(response=response)
re_keyed: Final = dict(translated, model=response.model or model) # mutable-ok: adapter TypedDict re-keyed
return _jsonable_dict(re_keyed)
def _v3_text_completion_as_chat(response: TextCompletionResponse) -> Mapping[str, object]:
"""A legacy completion answer in the chat shape the platform scores.
Straiker has no reader for a `text_completion` answer on a gateway: the request phase
of a /v1/completions call is scored, the response phase is refused. A completion is one
user turn and one assistant turn, so both phases are presented as that exchange.
"""
choices: Final = tuple(
_frozen(
(
("index", index),
("finish_reason", getattr(choice, "finish_reason", None)),
("message", _frozen((("role", "assistant"), ("content", getattr(choice, "text", "") or "")))),
)
)
for index, choice in enumerate(response.choices)
)
usage: Final = _jsonable_dict(getattr(response, "usage", None))
return _frozen(
(
("id", response.id),
("object", "chat.completion"),
("created", response.created),
("model", response.model),
("choices", choices),
*((("usage", usage),) if usage else ()),
)
)
def _v3_answer_json(
inputs: GenericGuardrailAPIInputs, request_data: Mapping[str, object], model: str | None
) -> str | None:
"""The model's answer as the raw response body Straiker parses on the response phase.
The real response object carries tool calls, which a coding-agent turn is scored on,
so it is preferred. A streamed answer reaches the hook already assembled into texts,
and those become a minimal chat completion so the answer is still scored.
"""
response: Final = _v3_answer(request_data, model)
if response:
return json.dumps(response, default=_json_default)
texts: Final = tuple(t for t in (inputs.get("texts") or []) if t)
if not texts:
return None
message: Final = _frozen((("role", "assistant"), ("content", "\n".join(texts))))
choice: Final = _frozen((("index", 0), ("finish_reason", "stop"), ("message", message)))
return json.dumps(_frozen((("object", "chat.completion"), ("choices", (choice,)))), default=_json_default)
def _v3_payload(
envelope: StraikerWebhookRequest,
inputs: GenericGuardrailAPIInputs,
request_data: Mapping[str, object],
input_type: Literal["request", "response"],
request_body: Mapping[str, object],
) -> Mapping[str, object]:
"""The /api/v3/detect body for one phase of a turn, the unified Kong plugin's contract.
Request phase: the provider body itself. Response phase: the answer beside the request
it answers, `{straiker_phase, sse, model, request}`, which is how Straiker classifies a
tool call the model just made. Straiker parses either and derives prompt, answer, agent
and archetype from the traffic; nothing is pre-digested here. Identity and session ride
on both phases the way Kong sends them.
"""
context: Final = envelope.context
answer_json: Final = _v3_answer_json(inputs, request_data, context.model) if input_type == "response" else None
phase: Final = (
tuple(request_body.items())
if input_type == "request"
else (
("straiker_phase", V3_RESPONSE_PHASE),
("model", context.model),
("request", request_body),
*((("sse", answer_json),) if answer_json is not None else ()),
)
)
session: Final = _v3_session_id(envelope, request_data, request_body)
user: Final = _v3_user(envelope)
return _frozen(
(
*phase,
*((("session_id", session),) if session else ()),
*(
(("original", _frozen((("processed", _frozen((("Meta", _frozen((("user", user),))),))),))),)
if user
else ()
),
)
)
def _v3_conversation_prefixes(request_body: Mapping[str, object]) -> tuple[str, ...]:
"""A fingerprint of the conversation after each of its messages, first to last.
The last one names the conversation as sent; the earlier ones let a request that
carries a blocked exchange as its history be recognised, not only an exact resend.
A `prompt` or a string `input` has one fingerprint.
"""
messages: Final = _v3_messages(request_body)
if messages:
digest: Final = hashlib.sha256()
def after(message: object) -> str:
digest.update(json.dumps(message, sort_keys=True, default=str).encode("utf-8"))
digest.update(b"\x1e")
return digest.copy().hexdigest()
return tuple(after(message) for message in messages)
plain: Final = request_body.get("input") if "input" in request_body else request_body.get("prompt")
if plain is None:
return ()
return (hashlib.sha256(json.dumps(plain, sort_keys=True, default=str).encode("utf-8")).hexdigest(),)
def _v3_session_id(
envelope: StraikerWebhookRequest,
request_data: Mapping[str, object],
request_body: Mapping[str, object],
) -> str | None:
"""A stable id for the conversation, in Kong's order of precedence.
Claude Code names its session on the wire and that wins. Then the session LiteLLM
resolved from its own metadata. Then, for a conversation that states none, a hash of
the principal, the system prompt and the first message: a chat client replays the
whole conversation on every turn, so that triple is constant for its lifetime and
groups the turns. A fresh synthetic id per request would group nothing.
The principal is in the hash because Straiker skips turns it has already scored for a
session. Two users who open with the same words are two conversations; hashed on the
words alone they shared one session, and the second user's copy of an attack came
back as a replay, unscored and allowed (measured 2026-09-20).
"""
supplied: Final = _request_header(request_data, V3_SESSION_HEADER)
if supplied:
return supplied
if envelope.context.session_id:
return envelope.context.session_id
conversation: Final = f"{_v3_system_text(request_body) or ''}\0{_v3_first_message_text(request_body)}"
if conversation == "\0":
return None
seed: Final = f"{_v3_user(envelope) or ''}\0{conversation}"
return V3_DERIVED_SESSION_PREFIX + hashlib.sha256(seed.encode("utf-8")).hexdigest()[:32]
_V3_PREAMBLE_ROLES: Final = frozenset({"system", "developer"})
def _v3_message_text(message: object) -> str:
"""Every text block of a message, so a turn that opens with an image or a document still
seeds on what the user wrote."""
content: Final = message.get("content") if isinstance(message, Mapping) else None
if isinstance(content, str):
return content
if isinstance(content, (list, tuple)):
return "\n".join(
str(block["text"]) for block in content if isinstance(block, Mapping) and isinstance(block.get("text"), str)
)
return ""
def _v3_messages(request_body: Mapping[str, object]) -> tuple[Mapping[str, object], ...]:
messages: Final = request_body.get("messages") or request_body.get("input")
if isinstance(messages, (list, tuple)):
return tuple(message for message in messages if isinstance(message, Mapping))
return ()
def _v3_system_text(request_body: Mapping[str, object]) -> str | None:
"""The preamble, wherever the API puts it: Anthropic's `system`, the Responses API's
`instructions`, or the leading system or developer message of an OpenAI chat body."""
system: Final = request_body.get("system")
if isinstance(system, str):
return system
if system is not None:
return json.dumps(system, default=str)
instructions: Final = request_body.get("instructions")
if isinstance(instructions, str):
return instructions
preamble: Final = next((m for m in _v3_messages(request_body) if m.get("role") in _V3_PREAMBLE_ROLES), None)
return _v3_message_text(preamble) if preamble is not None else None
def _v3_first_message_text(request_body: Mapping[str, object]) -> str:
"""What the user first said: the first `user` message, never the system prompt that an
OpenAI chat body carries as `messages[0]`, else a Responses `input` string, else `prompt`."""
first_user: Final = next((m for m in _v3_messages(request_body) if m.get("role") == "user"), None)
if first_user is not None:
return _v3_message_text(first_user)
plain: Final = (
request_body.get("input") if isinstance(request_body.get("input"), str) else request_body.get("prompt")
)
return plain if isinstance(plain, str) else ""
def _v3_user(envelope: StraikerWebhookRequest) -> str | None:
"""Who is asking: the key's own user first, then the end user the request named.
The key is the authenticated principal, the way a Kong consumer is, so a per-user key
names the person even when the client packs something else into the body. Claude Code
packs a hashed account-and-session token into `metadata.user_id`, which is what the end
user resolves to when nothing better is set; it is a session, not a person, and only
surfaces when the key names nobody. A master-key call resolves to LiteLLM's
`default_user_id`; sent as an identity it would become one.
"""
identity: Final = envelope.identity
for candidate in (identity.litellm_user_email, identity.litellm_user_id, identity.end_user_id):
real = _real_identity(candidate)
if real:
return real
return None
def _v3_client_from_user_agent(request_data: Mapping[str, object]) -> tuple[str, str] | None:
"""`(client, agent name)` for a User-Agent this gateway recognises, else None."""
user_agent: Final = (_request_header(request_data, "user-agent") or "").lower()
return next(
(
(client, f"{display} ({V3_GATEWAY_NAME})")
for prefix, client, display in _V3_CLIENT_BY_USER_AGENT
if user_agent.startswith(prefix)
),
None,
)
def _v3_headers(
request_data: Mapping[str, object],
agent_ref: str | None = None,
client: str | None = None,
format_hint: str | None = None,
) -> Mapping[str, str]:
"""Per-call routing hints, the unified Kong plugin's set. All optional.
`x-s6r-agent` names ONE application when a gateway fronts several: the route's
`agent_ref`, else the caller's own header, else the agent this gateway names from the
User-Agent. The operator's value comes first because the header is caller-supplied, and
honouring it over a pinned route would let any key file its traffic under another
application's agent and controls. `x-s6r-client` is the route's `client` config, else
the client the User-Agent names. `x-s6r-format` comes from config alone. Claude Code's own session header is
forwarded when the client sent it, which is how a coding session groups the way the
native hook would.
"""
session: Final = _request_header(request_data, V3_SESSION_HEADER)
recognised: Final = _v3_client_from_user_agent(request_data)
agent: Final = (
agent_ref or _request_header(request_data, V3_AGENT_HEADER) or (recognised[1] if recognised else None)
)
named_client: Final = client or (recognised[0] if recognised else None)
candidates: Final = (
(V3_SESSION_HEADER, session),
(V3_AGENT_HEADER, agent),
(V3_CLIENT_HEADER, named_client),
(V3_FORMAT_HEADER, format_hint),
)
return MappingProxyType({name: value for name, value in candidates if value})
def _v3_decision(body: Mapping[str, object]) -> tuple[str | None, Mapping[str, object]]:
"""``(decision, verdict)``: the enforceable decision and the object carrying it.
Straiker answers in two envelopes. A relayed body gets the hook contract,
`hookSpecificOutput.permissionDecision`, with the flat fields nested under `straiker`;
a flat call answers `action` at the top level. Reading only one of them would silently
make block mode a no-op on the other.
"""
nested: Final = body.get("straiker")
verdict: Final = nested if isinstance(nested, Mapping) else body
hook: Final = body.get("hookSpecificOutput")
decision: Final = hook.get("permissionDecision") if isinstance(hook, Mapping) else None
if isinstance(decision, str) and decision:
return decision.lower(), verdict
action: Final = verdict.get("action")
return (action.lower() if isinstance(action, str) and action else None), verdict
def _v3_blocked_by(verdict: Mapping[str, object]) -> tuple[str, ...]:
raw: Final = verdict.get("blocked_by")
return tuple(sorted(str(control) for control in raw)) if isinstance(raw, list) else ()
def _v3_response(body: Mapping[str, object]) -> StraikerWebhookResponse | None:
"""Map a v3 verdict onto the action the guardrail already acts on.
A detect-mode control fires into `controls` without changing the decision, so it
correctly reads NONE. `blocked_by` is the block-mode subset and is honoured even if a
build answers it without flipping the decision. None when Straiker stated no verdict:
a missing decision, or `ask`, which a gateway has no one to put to.
"""
decision, verdict = _v3_decision(body)
blocked_by: Final = _v3_blocked_by(verdict)
if (decision is None or decision in V3_UNDECIDED) and not blocked_by:
return None
blocked: Final = decision in V3_BLOCK_DECISIONS or bool(blocked_by)
stated: Final = (verdict.get("block_message"), verdict.get("deny_reason"), body.get("stopReason"))
reason: Final = (
next(
(text.strip() for text in stated if isinstance(text, str) and text.strip()),
f"Straiker blocked this turn: {', '.join(blocked_by) or 'policy'}",
)
if blocked
else None
)
return StraikerWebhookResponse(
action="BLOCKED" if blocked else "NONE",
blocked_reason=reason,
blocked_by=blocked_by,
turnId=_as_optional_str(verdict.get("turn_id")) or _as_optional_str(body.get("turn_id")),
)
class StraikerGuardrail(CustomGuardrail):
@staticmethod
def get_config_model() -> type[GuardrailConfigModel]:
@ -284,6 +886,10 @@ class StraikerGuardrail(CustomGuardrail):
self,
api_key: str,
api_base: str = DEFAULT_API_BASE,
api_version: Literal["v1", "v3"] | None = None,
agent_ref: str | None = None,
client: str | None = None,
format_hint: Literal["anthropic.messages", "openai.chat"] | None = None,
source: str = "LiteLLM Gateway",
timeout: float = 5.0,
max_retries: int = 2,
@ -302,9 +908,31 @@ class StraikerGuardrail(CustomGuardrail):
raise ValueError("api_key must be non-empty")
if unreachable_fallback not in ("fail_open", "fail_closed"):
raise ValueError(f"unreachable_fallback must be 'fail_open' or 'fail_closed'; got {unreachable_fallback!r}")
if api_version not in (None, "v1", "v3"):
raise ValueError(f"api_version must be 'v1' or 'v3'; got {api_version!r}")
# The v1 webhook rejects an sk_agt_ key, so an sk_agt_ key always means v3. Guardrails
# saved on 1.101.3 or older carry api_version 'v1' from the old shared default.
is_v3_key: Final = api_key.startswith(V3_KEY_PREFIX)
if is_v3_key and api_version == "v1":
verbose_proxy_logger.warning(
"Straiker guardrail: api_version 'v1' cannot use an sk_agt_ key, routing to /api/v3/detect"
)
self.api_key = api_key
self.api_base = api_base.rstrip("/")
self.api_version: Literal["v1", "v3"] = "v3" if is_v3_key else (api_version or "v1")
self.agent_ref = _as_optional_str(agent_ref)
self.client = _as_optional_str(client)
if format_hint is not None and format_hint not in ("anthropic.messages", "openai.chat"):
raise ValueError(f"format_hint must be 'anthropic.messages' or 'openai.chat'; got {format_hint!r}")
self.format_hint = format_hint
# Blocked conversations by session, so a resend or a conversation grown past a blocked
# turn is blocked again here: Straiker de-duplicates turns it has already scored per
# session and answers a replay `allow`, whatever the original verdict was (measured
# 2026-09-20). Per process; a replica that did not see the block asks Straiker.
self._v3_blocked_turns = InMemoryCache(
max_size_in_memory=V3_BLOCKED_TURN_MEMORY, default_ttl=V3_BLOCKED_TURN_TTL_SECONDS
)
self.source = source
self.timeout = float(timeout)
self.max_retries = max(0, int(max_retries))
@ -330,17 +958,18 @@ class StraikerGuardrail(CustomGuardrail):
self.configured_modes = _configured_modes(self.event_hook)
def _webhook_url(self) -> str:
return f"{self.api_base}{WEBHOOK_PATH}"
return f"{self.api_base}{V3_DETECT_PATH if self.api_version == 'v3' else WEBHOOK_PATH}"
def _headers(self) -> dict[str, str]:
reserved: Final = {"authorization", "content-type", "x-straiker-webhook-format"}
extra: Final = {k: v for k, v in self.custom_headers.items() if k.lower() not in reserved}
return {
headers: Final = {
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
"X-Straiker-Webhook-Format": "litellm",
**extra,
}
if self.api_version != "v3":
headers["X-Straiker-Webhook-Format"] = "litellm"
return {**headers, **extra}
def _build_application(self, request_data: dict) -> StraikerWebhookApplication:
meta: Final = _merged_metadata(request_data)
@ -417,9 +1046,11 @@ class StraikerGuardrail(CustomGuardrail):
metadata=_build_webhook_metadata(request_data, self.default_metadata),
)
async def _post_webhook(self, payload: dict) -> tuple[StraikerWebhookResponse | None, _WebhookFailure | None]:
async def _post_webhook(
self, payload: Mapping[str, object], headers: Mapping[str, str] | None = None
) -> tuple[StraikerWebhookResponse | None, _WebhookFailure | None]:
try:
body = json.dumps(payload).encode("utf-8")
body: Final = json.dumps(payload, default=_json_default).encode("utf-8")
except (TypeError, ValueError, OverflowError) as error:
return None, _WebhookFailure(f"request serialization failed: {error}", is_unreachable=False)
body_bytes: Final = len(body)
@ -430,7 +1061,7 @@ class StraikerGuardrail(CustomGuardrail):
)
url: Final = self._webhook_url()
headers: Final = self._headers()
merged_headers: Final = {**self._headers(), **(headers or {})}
attempts: Final = self.max_retries + 1
last_failure: _WebhookFailure | None = None
@ -443,48 +1074,60 @@ class StraikerGuardrail(CustomGuardrail):
"bytes": body_bytes,
"payload": payload,
},
default=str,
default=_json_default,
)
)
for attempt in range(attempts):
try:
resp = await self.async_handler.post(url, content=body, headers=headers, timeout=self.timeout)
if resp.status_code == 200:
try:
body = resp.json()
parsed = StraikerWebhookResponse.model_validate(body)
except (ValidationError, json.JSONDecodeError) as ve:
return None, _WebhookFailure(f"invalid response schema: {ve}", is_unreachable=False)
if self.verbose:
verbose_proxy_logger.info(
json.dumps(
{
"event": "straiker.webhook_response",
"status_code": resp.status_code,
"body": body,
},
default=str,
)
)
return parsed, None
last_failure = _WebhookFailure(
f"HTTP {resp.status_code}: {resp.text[:200]}",
is_unreachable=resp.status_code in UNREACHABLE_STATUS,
)
if resp.status_code not in RETRY_STATUS:
return None, last_failure
except (httpx.RequestError, asyncio.TimeoutError, Timeout) as e:
last_failure = _WebhookFailure(f"{type(e).__name__}: {e}", is_unreachable=True)
except (json.JSONDecodeError, TypeError, ValueError) as e:
return None, _WebhookFailure(f"{type(e).__name__}: {e}", is_unreachable=False)
parsed, last_failure = await self._attempt(url, body, merged_headers)
if last_failure is None or not last_failure.retryable:
return parsed, last_failure
if attempt < attempts - 1:
backoff = min(self.initial_backoff * (2**attempt), self.max_backoff)
await asyncio.sleep(random.uniform(0, backoff))
return None, last_failure or _WebhookFailure("unknown error", is_unreachable=True)
async def _attempt(
self, url: str, body: bytes, headers: dict[str, str]
) -> tuple[StraikerWebhookResponse | None, _WebhookFailure | None]:
try:
resp: Final = await self.async_handler.post(url, content=body, headers=headers, timeout=self.timeout)
except httpx.HTTPStatusError as status_error:
return None, _status_failure(status_error.response.status_code, _error_response_text(status_error.response))
except (httpx.RequestError, asyncio.TimeoutError, Timeout) as e:
return None, _WebhookFailure(f"{type(e).__name__}: {e}", is_unreachable=True, retryable=True)
except (json.JSONDecodeError, TypeError, ValueError) as e:
return None, _WebhookFailure(f"{type(e).__name__}: {e}", is_unreachable=False)
if resp is None:
return None, _WebhookFailure("no response", is_unreachable=True, retryable=True)
if resp.status_code == 200:
return self._parse_verdict(resp)
return None, _status_failure(resp.status_code, resp.text)
def _parse_verdict(self, resp: httpx.Response) -> tuple[StraikerWebhookResponse | None, _WebhookFailure | None]:
try:
body: Final = resp.json()
if not isinstance(body, Mapping):
return None, _WebhookFailure(
f"invalid response schema: expected an object, got {type(body).__name__}", is_unreachable=False
)
parsed: Final = (
_v3_response(body) if self.api_version == "v3" else StraikerWebhookResponse.model_validate(body)
)
except (ValidationError, json.JSONDecodeError) as ve:
return None, _WebhookFailure(f"invalid response schema: {ve}", is_unreachable=False)
if parsed is None:
return None, _WebhookFailure("invalid response schema: no allow or block decision", is_unreachable=False)
if self.verbose:
verbose_proxy_logger.info(
json.dumps(
{"event": "straiker.webhook_response", "status_code": resp.status_code, "body": body},
default=_json_default,
)
)
return parsed, None
def _record(
self,
*,
@ -519,7 +1162,7 @@ class StraikerGuardrail(CustomGuardrail):
"error": error,
"fail_open": fail_open,
},
default=str,
default=_json_default,
)
)
if fail_open:
@ -564,6 +1207,82 @@ class StraikerGuardrail(CustomGuardrail):
return_inputs["texts"] = parsed.texts
return return_inputs
async def _apply_v3(
self,
*,
inputs: GenericGuardrailAPIInputs,
request_data: dict,
input_type: Literal["request", "response"],
logging_obj: LiteLLMLoggingObj | None,
) -> GenericGuardrailAPIInputs:
"""One phase of a turn against /api/v3/detect: relay, read the decision, enforce."""
try:
envelope: Final = self._build_envelope(
inputs=inputs,
request_data=request_data,
input_type=input_type,
logging_obj=logging_obj,
)
request_body: Final = _v3_request_body(
request_data, (inputs.get("texts") or ()) if input_type == "request" else ()
)
payload: Final = _v3_payload(envelope, inputs, request_data, input_type, request_body)
headers: Final = _v3_headers(request_data, self.agent_ref, self.client, self.format_hint)
# The memory is scoped by the principal (the user, else the key) and the session
# together; a request that has neither is never remembered, so two callers never
# share a block.
session: Final = _v3_session_id(envelope, request_data, request_body)
principal: Final = _v3_user(envelope) or envelope.identity.litellm_key
scope: Final = f"{principal or ''}\0{session or ''}" if session or principal else ""
prefixes: Final = _v3_conversation_prefixes(request_body) if scope else ()
except (ValidationError, TypeError, ValueError) as error:
return self._fail(
inputs=inputs,
request_data=request_data,
input_type=input_type,
error=str(error),
is_unreachable=False,
)
replayed: Final = self._v3_replayed_block(scope, prefixes) if input_type == "request" else None
if replayed is not None:
self._block(request_data=request_data, input_type=input_type, message=replayed, blocked_content=True)
parsed, failure = await self._post_webhook(payload, headers)
if failure is not None or parsed is None:
return self._fail(
inputs=inputs,
request_data=request_data,
input_type=input_type,
error=failure.message if failure is not None else "empty response from Straiker",
is_unreachable=failure.is_unreachable if failure is not None else False,
)
self._record(request_data=request_data, logging_obj=logging_obj, parsed=parsed)
if parsed.action == "BLOCKED":
message: Final = parsed.blocked_reason or DEFAULT_BLOCK_MESSAGE
# Only a block that names a control is remembered. The same words are the same
# attack tomorrow, but a block that comes from state -- an engaged kill switch,
# a governance action -- is lifted by an administrator, and a remembered copy
# would keep refusing a conversation the platform now allows. A blocked answer is
# not remembered: the question that produced it may be harmless.
if input_type == "request" and prefixes and parsed.blocked_by:
self._v3_blocked_turns.set_cache(f"{scope}\0{prefixes[-1]}", message)
self._block(request_data=request_data, input_type=input_type, message=message, blocked_content=True)
return inputs
def _v3_replayed_block(self, scope: str, prefixes: tuple[str, ...]) -> str | None:
"""The block message a conversation already earned, when this request repeats or
extends a conversation this process blocked in the same scope (session or principal)."""
for prefix in prefixes:
message: str | None = self._v3_blocked_turns.get_cache(f"{scope}\0{prefix}")
if message is not None:
if self.verbose:
verbose_proxy_logger.info(
json.dumps({"event": "straiker.replay_blocked", "scope": scope, "prefix": prefix})
)
return message
return None
@log_guardrail_information
async def apply_guardrail(
self,
@ -572,6 +1291,10 @@ class StraikerGuardrail(CustomGuardrail):
input_type: Literal["request", "response"],
logging_obj: LiteLLMLoggingObj | None = None,
) -> GenericGuardrailAPIInputs:
if self.api_version == "v3":
return await self._apply_v3(
inputs=inputs, request_data=request_data, input_type=input_type, logging_obj=logging_obj
)
try:
envelope: Final = self._build_envelope(
inputs=inputs,

View file

@ -83,6 +83,9 @@ class StraikerWebhookResponse(BaseModel):
action: StraikerWebhookAction = "NONE"
blocked_reason: str | None = None
#: The controls that blocked this turn, when the platform names them. Empty for a block
#: that comes from state rather than content, such as an engaged kill switch.
blocked_by: tuple[str, ...] = ()
texts: list[str] | None = None
schema_version: str | None = None
turn_id: str | None = Field(default=None, alias="turnId")
@ -125,6 +128,36 @@ class StraikerGuardrailConfigModelOptionalParams(BaseModel):
gt=0,
description="Maximum serialized webhook payload size sent to Straiker.",
)
api_version: Literal["v1", "v3"] | None = Field(
default=None,
description=(
"Straiker detect API the gateway calls. 'v1' posts the structured webhook envelope "
"to /api/v1/detect/webhook (legacy Defend, UUID collection key). 'v3' relays the "
"provider request and response to /api/v3/detect, the v3 platform's only detect "
"route, which accepts only an sk_agt_ integration key. Unset: chosen from the key "
"prefix, so a v3 key needs no extra configuration."
),
)
agent_ref: str | None = Field(
default=None,
description=(
"v3 only. Names the Straiker agent this route's traffic belongs to when one gateway "
"fronts several applications, sent as x-s6r-agent. It wins over a client-supplied "
"x-s6r-agent header. Names ONE agent, never a kind of agent: Straiker keys per-agent state on it, so "
"sharing a value across applications merges them into one agent."
),
)
client: str | None = Field(
default=None,
description=(
"v3 only. Optional x-s6r-client routing hint. Leave unset on a shared gateway; set it on a "
"route that serves a single application."
),
)
format_hint: Literal["anthropic.messages", "openai.chat"] | None = Field(
default=None,
description="v3 only. Optional x-s6r-format hint. Only breaks the messages-array tie between formats.",
)
custom_headers: dict[str, str] | None = Field(
default=None,
description="Additional HTTP headers sent to Straiker, excluding Authorization and the webhook-format header.",