Plugins And SafetySec
Understand lifecycle plugins and the modular SafetySec security engine.
Plugins And SafetySec
Odock has two extension points in the gateway request path:
- plugins for general lifecycle behavior,
- SafetySec modules for security and safety checks.
Plugin Phases
Plugins implement the plugin.Plugin interface and can run in these phases:
| Phase | Timing |
|---|---|
pre_route | After request decode, before model config and final gates |
pre_upstream | After final rate limit and budget reserve, before provider call |
post_upstream | After provider response, before response encoding/write |
post_response | After response/stream and usage recording |
Plugins can be sequential or parallel-safe. Post-response plugins can run asynchronously when configured.
Bundled Plugins
Current bundled plugins:
| Plugin | Phases | Current behavior |
|---|---|---|
audit_log | pre_route, post_response | Logs structured plugin events |
pii_mask | pre_upstream, post_upstream | Placeholder/no-op mode by default |
request_transform | pre_route, pre_upstream | Logs structured events and demonstrates scoped organisation storage access |
The plugin system is config-driven now. Older notes that say config loading is a stub are outdated.
Plugin Storage Access
Plugin entries can request scoped storage access:
{
"name": "request_transform",
"storage_access": ["organisations"]
}Supported access scopes include repositories such as organisations, users, teams, API keys, models, model access, budgets, usage, policies, Postgres, Redis, and broad all/* access.
Grant the smallest access set a plugin needs.
Plugin Abort Behavior
A plugin can return PluginResult with:
Abort,HttpCode,Code,Message,Err.
The endpoint converts this into a gateway error response. Use this for policy enforcement plugins.
SafetySec
SafetySec is enabled with:
SAFETY_ENGINE_MODE=securityDefault is noop.
SafetySec phases:
| Phase | Timing |
|---|---|
pre_auth | Before API key auth |
post_auth | After API key auth |
pre_upstream | Before provider call |
post_upstream | After provider response |
stream | After streaming finishes |
post_response | After response write |
Built-in SafetySec Modules
Sensitive redaction
Runs in:
pre_upstream,post_upstream.
Detects and redacts default sensitive patterns in text content:
- emails,
- phone-like values,
- credit-card-like sequences,
- OpenAI keys,
- AWS keys,
- JWTs,
- long token-like strings.
Prompt injection
Runs in pre_upstream.
Looks for phrases such as:
- ignore previous,
- system prompt,
- developer message,
- reveal hidden,
- override,
- jailbreak,
- disregard,
- bypass.
It emits observe signals and increments SafetySec session score.
Jailbreak patterns
Runs in pre_upstream.
Looks for role hijacking and jailbreak language such as:
- act as,
- roleplay,
- you are now,
- do anything now,
- DAN mode,
- override policy,
- bypass safety.
Data leakage
Runs in post_upstream.
Detects sensitive data in responses and request echo leakage. It observes by default and can block if the accumulated session score reaches the configured threshold.
SafetySec Sessions
Sessions are stored in Redis:
safety:session:{fingerprint_hash}The session tracks:
- score,
- flags,
- request count,
- block count,
- redact count,
- last seen.
The fingerprint is based on IP, API key ID when known, and user agent. The engine resets fingerprint tracking after auth because the API key becomes known.
SafetySec Block Responses
When a SafetySec result blocks a request, the endpoint returns a gateway error with a status and code derived from the safety action. Typical blocks are 403.
Choosing Plugins vs SafetySec
Use SafetySec for:
- prompt/security inspection,
- redaction,
- cumulative behavior by sender,
- request/response safety decisions.
Use plugins for:
- audit events,
- business policy hooks,
- request/response transformation,
- custom governance integrations,
- side effects after response.