Skip to content

plugin-catalog.md

Latest commit

 

History

History
273 lines (218 loc) · 18.6 KB

plugin-catalog.md

File metadata and controls

273 lines (218 loc) · 18.6 KB
Raw

Plugin Catalog

Catalog of AuthBridge pipeline plugins — every plugin with a Go implementation that calls plugins.RegisterPlugin(). For the config convention, session-event contract, and lifecycle interfaces plugins implement, see plugin-reference.md. For writing a new plugin, see plugin-tutorial.md.

"Production ready?" reflects whether the plugin is compiled into the default build of cmd/authbridge-proxy / cmd/authbridge-envoy (opt-out via -tags exclude_plugin_<name>) versus opt-in (-tags include_plugin_<name>) or requiring a separate binary. It is a build-tag signal, not a claim about test coverage or operational maturity.

Plugins

"Direction" is inbound (caller → this agent) or outbound (this agent → callee); "both" means the plugin evaluates on both pipelines. "Default config?" marks whether the plugin is enabled in Rossoctl's default AuthBridge pipeline YAML, not whether it is compiled into the binary (see "Production ready?" above for that).

Name Description Production ready? Direction Default config?
a2a-parser Parses A2A messages into pctx.Extensions.A2A for downstream plugins. Beta Inbound No
context-guru Compacts the outbound LLM request context before forwarding. Coming Soon Outbound No
cpex APL DSL + named CPEX plugins (Cedar, PII, audit, …) over a single chain step. Coming Soon Outbound No
ibac LLM-judge intent-based access control for outbound tool calls. Alpha Outbound No
inference-parser Parses LLM completions into pctx.Extensions.Inference. Alpha Outbound No
jwt-validation Inbound JWT validation (signature, issuer, audience) against JWKS. Ready Inbound YES
litellm-budget-track Tracks x-litellm-response-cost and enforces a daily budget limit. Alpha Inbound No
mcp-parser Parses MCP tool calls/results into pctx.Extensions.MCP. Beta Outbound No
opa OPA policy enforcement for inbound and outbound requests. Alpha Both No
sparc Pre-tool reflection: blocks ungrounded/hallucinated tool calls. Alpha Outbound No
static-inject Swaps a placeholder credential for a real static credential on outbound requests. Alpha Outbound No
session-budget Enforces per-session token, call, and duration budgets via Redis. Alpha Outbound No
token-broker Exchanges incoming tokens against a configured IdP via a broker service. Alpha Outbound No
token-exchange RFC 8693 outbound token exchange per route. Ready Outbound YES

a2a-parser

Parses A2A JSON-RPC 2.0 request bodies into pctx.Extensions.A2A (method, session ID, message parts, role) for downstream guardrails.

No configuration — registered as a bare plugin name, no config: block.

context-guru

Compacts an agent's outbound LLM request context before forwarding, using the embedded context-guru engine. OnResponse is currently a pass-through; model-driven expand/restore is a later integration. Opt-in at build time (-tags include_plugin_contextguru) because its engine pulls a large transitive dependency set.

  • paths ([]string) — inference request paths to compact. Default: /v1/chat/completions, /v1/completions, /v1/messages.
  • model (object) — optional "cheap" LLM endpoint for model-backed components (summarize, extract:code); omitted means those degrade to deterministic/no-op.
    • base_url — OpenAI-compatible endpoint base.
    • model — model name to call.
    • api_key — optional bearer token.
    • max_tokens — completion cap, default 4096.
    • timeout_ms — per-call timeout, default 150000.
  • engine (object) — native context-guru config (preset / pipeline / per-component / store), passed through verbatim. Default: preset: balanced.

cpex

Bridges AuthBridge hooks to the CPEX framework (a policy enforcement runtime for AI agents): an APL DSL plus named CPEX policy plugins (Cedar, PII, audit, …). Requires the separate authbridge-cpex binary (-tags cpex, CGO_ENABLED=1, links a pinned libcpex_ffi.a). Full details in cpex-plugin.md; see also the plugin's README.

  • hooks.on_request / hooks.on_response ([]string) — CPEX hook names to fire on each phase, in order (AuthBridge classifies traffic onto the cmf.* hooks — see Hook chains).
  • config (string) — inline CPEX runtime YAML (plugins:/global:/plugin_settings:); mutually exclusive with config_file.
  • config_file (string) — path to a file with the CPEX runtime YAML; mutually exclusive with config.
  • fail_open (bool) — allow traffic through if CPEX itself errors/panics. A CPEX policy deny is always honored regardless. Default false.
  • worker_threads (int) — size of CPEX's tokio worker pool; 0 = automatic.
  • bypass_hosts / bypass_paths ([]string) — globs skipped entirely (outbound only for hosts); default to Keycloak/SPIRE/observability infra.

ibac

LLM-judge intent-based access control: judges outbound tool calls against recorded inbound user intent. Full details, including the prompt-injection threat model, in ibac-plugin.md.

The "LLM-judge service" is any OpenAI-compatible chat-completions endpoint (a local Ollama/vLLM, or a hosted provider) — AuthBridge ships no judge of its own. The plugin POSTs the recorded user intent plus the proposed action to {judge_endpoint}/v1/chat/completions and parses an allow/deny verdict from the reply — see Request Flow. For guidance on which model to point it at, see Choosing a Judge Model.

  • judge_endpoint (string) — base URL of the LLM-judge service ({endpoint}/v1/chat/completions).
  • judge_model (string) — model name passed to the judge.
  • judge_bearer (string) — optional bearer token; empty for unauthenticated local LLMs.
  • system_prompt (string) — override the built-in judge system prompt.
  • timeout_ms (int) — per-call timeout; values below 100 rejected. Default 5000.
  • judge_max_tokens (int) — cap on judge reply length. Default 1024.
  • judge_json_mode (*bool) — force response_format: json_object. Default true.
  • judge_inference (bool) — also judge outbound LLM-reasoning traffic (high cost). Default false.
  • agent_llm_host (string) — the agent's own LLM host; auto-added to bypass_hosts.
  • bypass_hosts / bypass_paths ([]string) — globs skipped without judging.
  • no_intent_policy (string) — behavior when an action has no recorded intent: allow (default) or deny.
  • unclassified_policy (string) — behavior when no parser claimed the request: passthrough (default) or judge.

inference-parser

Parses outbound OpenAI-compatible LLM inference requests/responses into pctx.Extensions.Inference for downstream policy plugins.

No configuration — no config struct, does not implement Configurable.

jwt-validation

Validates inbound JWTs: signature via JWKS, issuer, and audience.

  • issuer (string) — expected iss claim; required.
  • jwks_url (string) — JWKS endpoint; derived from Keycloak URL/realm or issuer when omitted.
  • keycloak_url / keycloak_realm (string) — used to derive jwks_url when omitted.
  • audience (string) — expected aud claim; one of audience / audience_file / audience_mode=per-host required.
  • audience_file (string) — file to read expected audience from. Default /shared/client-id.txt.
  • audience_mode (string) — static (default) or per-host (derived from the Host header via waypoint routing).
  • allowed_audiences ([]string) — extra audience values accepted (OR semantics).
  • bypass_paths ([]string) — path globs skipped. Default /healthz, /readyz, /livez, /metrics, /.well-known/*.
  • placeholder_mode (bool) — replace the validated inbound token with an opaque placeholder before forwarding, for later outbound resolution. Default false.
  • placeholder_ttl (string) — how long the real token is retained. Default 1h.

litellm-budget-track

Tracks the x-litellm-response-cost response header and enforces a daily spend budget. Full details in litellm-budgettrack-plugin.md.

Provider-specific: x-litellm-response-cost is emitted only by LiteLLM, so this plugin works only when LiteLLM is the inference provider in front of the model. Against a provider that doesn't set the header (raw OpenAI, Ollama, vLLM, …), no cost is ever accumulated and the budget never trips.

  • spend_file (string) — path to the JSON spend ledger file; required. The ledger is a small JSON file the plugin creates and rewrites, holding the current UTC date plus the cumulative spend and call count for that day (it resets automatically at midnight UTC) — see Ledger Format.
  • max_budget (float64) — daily budget in USD; required, must be > 0.

mcp-parser

Parses MCP tool calls/results into pctx.Extensions.MCP for downstream policy plugins.

This plugin makes no decisions of its own — it exists to feed others. The plugins that consume pctx.Extensions.MCP are:

Consumer How it uses the MCP extension
ibac Reads the tool name and arguments to judge the call against user intent. Declares mcp-parser in RequiresAny.
sparc Extracts the tool name/arguments to reflect on, and returns clarifications as MCP results. Declares mcp-parser in RequiresAny; required in enforcement: mcp mode.
cpex Converts the parsed call/result into a CMF message for the cmf.tool_pre_invoke / cmf.tool_post_invoke hooks. Declares mcp-parser in RequiresAny.
opa Exposes the parsed call as input.mcp for policy (add mcp.params to include for arguments).

Place mcp-parser before these plugins on the outbound chain; without it they see no MCP data and pass the traffic through unclassified.

  • paths ([]string) — URL path globs treated as MCP endpoints (for body-less transport detection: SSE GET, session-terminate DELETE). Default ["/mcp"].

opa

Evaluates OPA (Open Policy Agent) policy bundles against inbound and outbound requests, using an embedded OPA engine and four fixed decision paths. Full details in the plugin's README.

  • bundle_url (string) — base URL of the Rossoctl Bundle Server, the in-cluster service that serves per-agent OPA policy bundles keyed by SPIFFE ID (see how it works); required.
  • agent_id_file (string) — path to the agent's client-ID file. Default /shared/client-id.txt.
  • agent_id (string) — inline agent ID; overrides agent_id_file when set.
  • polling_min_delay / polling_max_delay (int) — bundle polling interval bounds in seconds. Defaults 10 / 120.
  • include ([]string) — optional field groups exposed in the OPA input document (e.g. mcp.params, a2a.content, inference.messages); default lean/empty.

sparc

Pre-tool reflection: sends proposed tool calls to a SPARC reflection service — a companion HTTP service wrapping the SPARCReflectionComponent from the agent-lifecycle-toolkit (ALTK) package — and enforces the configured policy on the result. It must be deployed once per cluster before enabling this plugin. Full details in sparc-plugin.md.

  • reflector_endpoint (string) — base URL of the SPARC reflection service ({endpoint}/reflect); required.
  • reflector_bearer (string) — optional bearer token.
  • enforcement (string) — mcp (gate outbound MCP tools/call, default) or inference (gate/rewrite LLM completions).
  • track (string) — reflection track: fast_track (default), slow_track, syntax, spec_free, transformations_only.
  • timeout_ms (int) — per-call timeout; values below 100 rejected. Default 30000.
  • on_reject_action (string) — observe (log only), reflect (default, return clarification), or deny (hard block).
  • deny_score_threshold (float64) — escalate a reject to hard deny when the grounding score is at or below this value. 0 disables escalation.
  • fail_policy (string) — behavior when SPARC is unreachable: open (default, allow + record) or closed (block).
  • skip_tools / reflect_tools ([]string) — tool-name globs to exclude from, or restrict, reflection.
  • bypass_hosts / bypass_paths ([]string) — globs skipped without reflecting; default to Keycloak/SPIRE/otel/etc.

static-inject

Swaps a placeholder credential for a real static credential on outbound requests, so the workload never holds the real secret.

  • source (string) — secret_dir (read one file per key from secret_dir) or mappings (inline map; tests/dev only).
  • secret_dir (string) — directory of per-key credential files.
  • mappings (map[string]string) — inline key-to-credential map; not for real secrets.
  • key_by (string) — host (default, use the outbound destination host) or static (always use key).
  • key (string) — lookup key used when key_by=static.
  • placeholder (string) — if set, the inbound bearer must exactly equal this value before injection proceeds.
  • inject_header (string) — header to inject the credential into. Default Authorization (writes Bearer <value>); any other value writes the raw credential and drops the inbound Authorization header.

session-budget

Enforces per-session token, call-count, and duration budgets via Redis. Opt-in at build time (-tags include_plugin_sessionbudget). Full details in session-budget-plugin.md.

  • redis_url (string) — Redis/Valkey connection URL; required.
  • max_tokens (int64) — cumulative token ceiling per session. 0 = no limit.
  • max_calls (int64) — max inference calls per session. 0 = no limit.
  • max_duration_seconds (int64) — wall-clock session lifetime. 0 = no limit.
  • on_exceed (string) — deny (default, block), observe (log only), or pause (HITL webhook approval).
  • pause_webhook (string) — URL to POST for approval when on_exceed=pause. Required in pause mode.
  • pause_timeout (string) — how long to wait for webhook response. Default 30s.
  • pause_timeout_action (string) — fallback on timeout/error: deny (default) or allow.
  • pause_grace_period (string) — suppress repeated webhooks after approval. Default 5m.
  • session_ttl_seconds (int) — Redis key TTL; must be ≥ max_duration_seconds when the latter is set (enforced at Configure time). Default 7200.
  • refresh_interval (string) — how often the local cache syncs from Redis. Default 5s.
  • redis_unavailable (string) — only fail_open (default) is implemented; fail_closed is rejected at Configure time.

Cold-cache behavior is mode-dependent; see session-budget-plugin.md for details.

token-broker

Exchanges incoming tokens against a configured IdP through an external token broker service, per host-based routing rules. An alternative to token-exchange, not a complement — both replace the outbound Authorization header, so use one or the other on a given chain. Full details in token-broker-plugin.md.

  • broker_url (string) — base URL of the token broker service; required.
  • default_policy (string) — behavior when no route matches: passthrough (default) or broker.
  • routes.file (string) — path to a routes.yaml file; merged with inline rules.
  • routes.rules (list) — inline route entries; each has:
    • host — glob pattern to match the target host.
    • action — broker (default) or passthrough.
    • authorization_endpoint / token_endpoint — per-route OAuth endpoint overrides sent to the broker.

token-exchange

RFC 8693 outbound token exchange per route. Supports Keycloak, Entra ID, Okta, and any RFC 8693-compliant IdP. For the IdPProvider interface each IdP implements, see idp-plugin-contract.md.

  • token_url (string) — OAuth token endpoint; required unless derived from provider + provider_url(+provider_realm), or the deprecated keycloak_url/keycloak_realm.
  • provider (string) — IdP selector for endpoint derivation and client auth: keycloak, generic.
  • provider_url / provider_realm (string) — IdP base URL and realm/tenant, meaning varies by provider.
  • keycloak_url / keycloak_realm (string) — deprecated aliases for provider_url/provider_realm with provider=keycloak.
  • default_policy (string) — behavior when no route matches: passthrough (default) or exchange (empty-audience client-credentials) for hosts explicitly configured in authproxy-routes.
  • no_token_policy (string) — behavior for outbound requests with no bearer token: client-credentials, allow, or deny (default).
  • identity.type (string) — spiffe (JWT-SVID assertion) or client-secret; required.
  • identity.client_id / identity.client_id_file — OAuth client ID, inline or from file (default /shared/client-id.txt).
  • identity.client_secret / identity.client_secret_file — client secret, inline or from file (default /shared/client-secret.txt).
  • identity.jwt_audience (string) — audience claim minted on the JWT-SVID assertion; required when type=spiffe.
  • identity.assertion_type (string) — client-assertion URN: jwt-spiffe (default) or jwt-bearer (Okta).
  • routes.file (string) — path to routes.yaml. Default /etc/authproxy/routes.yaml.
  • routes.rules (list) — inline route entries (host, target_audience, token_scopes, token_url, action), combined with file-loaded routes.
  • audience_from_host (bool) — derive audience from host for unrouted requests (waypoint mode). Default false.
  • resolve_placeholders (bool) — resolve an inbound placeholder-prefixed bearer to its real token before exchange; unresolvable placeholders are denied. Default false.