Reiki

Security proxy for agent and LLM traffic: isolates keys, filters what leaves, keeps access reliable

View the Project on GitHub ddproxy/reiki

Plugins

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.

Use a plugin

A plugin is configured with a [plugins.<name>] table:

[plugins.requestlog]
file = "/var/lib/reiki/requests.jsonl"

Bundled plugins

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.

Tune a detector with reiki scan

reiki 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

Report findings with a detail

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:

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.

Choose and order plugins at build time

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

What a plugin can see and do

A plugin is trusted code that runs inside the Reiki process.

Write a plugin

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:

  1. Add the crate to the workspace and as an optional dependency of reiki.
  2. Add a feature of the same name that enables it, for example plugin-tag = ["dep:reiki-tag"].
  3. 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.