Security proxy for agent and LLM traffic: isolates keys, filters what leaves, keeps access reliable
Plugins add behaviour to the request path without changing Reiki itself, for example rewriting a body or recording requests. They are compiled into the binary; Reiki never loads code at runtime.
Release binaries include the plugins listed in Bundled plugins. Building from source lets you choose which are compiled in, and in what order.
A plugin is configured with a [plugins.<name>] table:
[plugins.requestlog]
file = "/var/lib/reiki/requests.jsonl"
enabled = false turns a configured plugin off.streams = ["client-a", "other"] runs the plugin only for requests on those streams. Without it the plugin runs on every stream. Each name must be a configured stream, or passthrough for unauthenticated passthrough traffic. Any other name is a startup error that names the plugin and the stream.streams gets its request, attempt and response hooks only for those streams, and its on_event calls only for events that name one of them. A cooldown event names no stream, so only plugins without streams receive it. on_admin is not affected.streams is a host key, like enabled and on_error. Every plugin accepts it, and a plugin never reads it.on_error is "pass_through" or "reject". The default is "pass_through" unless the plugin fails closed (it returns true from Plugin::fails_closed, as placeholders does because a failure would send the data unmasked), in which case the default is "reject". Setting "pass_through" on such a plugin is allowed and logs a warning at startup and on reload. It decides what happens when a plugin reports that it could not apply (a skip): pass_through logs it and carries on, reject answers the client with 503. A plugin that deliberately rejects a request always rejects, whatever on_error says.reiki check adds dry_run = true to every plugin table. A plugin should then validate its settings only, and not open files, sockets or threads, so the check has no side effects and works while Reiki is running.streams alone applies live and does not rebuild the plugin, so its counters survive. An unknown plugin name or a bad setting keeps the old config. A plugin that holds a file or socket, such as requestlog, keeps running and is reported as needing a restart. See reload.| Plugin | Feature | What it does |
|---|---|---|
phi |
plugin-phi |
Blocks or reports PHI and NPPI identifiers in outbound requests. See phi. |
finance |
plugin-finance |
Blocks or reports financial identifiers in outbound requests. See finance. |
controlled |
plugin-controlled |
Blocks or reports controlled-information markings (CUI, classification) and label-bound identifiers in outbound requests. See controlled. |
placeholders |
plugin-placeholders |
Swaps credentials and listed terms for placeholders on the way out and restores them in responses. See placeholders. |
requestlog |
plugin-requestlog |
Logs requests to a file and a live socket. See requestlog. |
metrics |
plugin-metrics |
Serves Prometheus metrics at GET /metrics on the admin listener. See monitoring. |
reiki scanreiki scan runs the phi, finance and controlled detectors over files or stdin without the proxy, so you can see what a plugin would flag before you switch it from report to block.
reiki scan export.csv # each plugin's default kinds
cat prompt.json | reiki scan --plugin phi # one plugin, from stdin
reiki scan --kinds ssn,iban dump.sql # named kinds across plugins
reiki scan --all --json notes.txt # every kind, one JSON object per finding
file:line:col plugin kind. The matched text is never printed, so the output is safe to paste into a ticket. A summary goes to stderr.--kinds takes labels from any plugin. --all adds the kinds that are off by default.A detection plugin reports a finding with RequestCtx::report(kind, count, blocked). A plugin that reports per name or per rule, such as a tool allowlist or a lint rule, can add a short label with RequestCtx::report_detail(kind, detail, count, blocked):
ctx.report_detail("tool", "get_weather", 1, true);
The host checks the label before any listener sees it:
A-Z, a-z, 0-9, _, ., :, *, / and -. Other characters are removed, not replaced, so a space, a newline or a quote never gets through.The filter is not a privacy check. A plugin must still never pass matched text, even text that fits the character set.
Event::Finding has a detail: Option<&str> field with the sanitised label. Plugins that match with .. need no change.
Cargo features only switch a plugin’s code on, and they carry no order. Order comes from REIKI_PLUGINS, an ordered, comma-separated list read by build.rs:
# only these two, in this order
REIKI_PLUGINS=placeholders,requestlog cargo build --release --no-default-features \
--features plugin-placeholders,plugin-requestlog
Cargo.toml ([[package.metadata.reiki.plugin]]). The catalog must be a non-empty array of tables with unique names and crates; crate must be a plain Rust identifier.requestlog before placeholders fails the build. The build also warns when requestlog has no masking plugin before it, or when phi, finance or controlled follows placeholders, because either order weakens what the later plugin can see or mask.[plugins.*] is a startup error.A plugin is trusted code that runs inside the Reiki process.
on_request receives the stream name, the upstream name, the method, the request path, the request headers and the request body. It can change the headers and the body, or reject the request with a status and a message. It runs once per request, so every failover attempt sends the same transformed request.authorization header a plugin sets is dropped (on a passthrough upstream the client’s credentials, including one a plugin sets, are forwarded).on_attempt runs after each upstream attempt, including the ones that fail over to the next key. It receives the key’s name from the config, the upstream status (None when no response arrived) and, for an error response, the start of its body. It never receives a key’s secret.on_response_head receives the name of the key that produced the response, the upstream that served it (the fallback upstream after a failover), the upstream status and the headers. on_response_chunk receives each body chunk and may rewrite it. RequestCtx::id is a 32-hex-digit request id shared with the logs.on_request counts as the plugin skipping the request, so on_error decides whether the request goes on or gets a 503. Rust’s panic handler also prints the message to stderr, outside the log settings, so do not unwrap or expect on request data.on_event receives facts about the relay rather than one request: a finished request (stream, upstream, final status), a failover from one key to the next, a key going on cooldown, a stream rate-limit rejection, and a request a plugin rejected (Event::PluginRejected, which the metrics plugin counts). It is not tied to a request’s state and carries key names, never secrets.admin_paths and on_admin let a plugin answer a GET on the admin listener, after the caller has been authenticated. A path must be absolute with no trailing slash, ./.. segment or %. A duplicate path, or one Reiki serves itself (/status, /reload, /keys/enable, their /v1 forms, /v1/openapi.json), is a startup error. The hook receives the current count of available, cooling and out-of-rotation keys.false from uses_bodies, so configuring it does not change how responses are streamed. An observer returns false there and true from needs_response_hooks.content-length, so a plugin may change a body’s length. HEAD, 204 and 304 keep theirs because they have no body.on_response_chunk call with is_last set follows the last chunk. It does not happen after an upstream read error or a client disconnect, so treat the per-request state being dropped as the end-of-response signal.A plugin implements the Plugin trait from the reiki-plugin crate in this repository. The crate is not published; depend on it by path. The error and context types are #[non_exhaustive], so new fields and variants can be added without breaking plugins; Reiki builds the contexts, and tests can use their new functions.
use reiki_plugin::{Plugin, PluginError, RequestCtx};
pub struct Tag;
impl Plugin for Tag {
fn name(&self) -> &str {
"tag"
}
fn on_request(&self, ctx: &mut RequestCtx<'_>) -> Result<(), PluginError> {
ctx.headers.insert("x-tag", http::HeaderValue::from_static("1"));
Ok(())
}
}
pub fn build(_table: &toml::Table) -> Result<Box<dyn Plugin>, String> {
Ok(Box::new(Tag))
}
To compile it in:
reiki.plugin-tag = ["dep:reiki-tag"].Add it to the catalog in Cargo.toml, in default chain order. The crate must export NAME and build:
[[package.metadata.reiki.plugin]]
name = "tag"
feature = "plugin-tag"
crate = "reiki_tag"
Per-request data goes in the value returned by Plugin::new_state, which every hook for that request receives. One plugin instance serves many requests at once, so keep shared data behind its own synchronisation.
Reject a request with PluginError::Reject(status, message); the client receives a JSON error with that status and message. The message is public (sent to the client and logged), so never put request text or a secret in it. Return PluginError::Skip(message) when the plugin does not apply and let on_error decide what follows.