Skip to content
Gateway Guardian

Guardian Plugin Developer MVP

Guardian gateway custom plugins are WASM modules that implement the Guardian core ABI and are bound to the gateway by an immutable plugin configuration.

Developer loop

Section titled “Developer loop”

To use the guardian-plugin CLI tool:

Terminal window
cargo install --path crates/guardian-plugin --force
# OR
cargo run -p guardian-plugin ...
Terminal window
cargo run -p guardian-plugin -- init
cargo run -p guardian-plugin -- init --template vtscan guardian.plugin.toml
cargo run -p guardian-plugin -- validate
cargo run -p guardian-plugin -- publish
cargo run -p guardian-plugin -- config apply

Use --manifest path/to/guardian.plugin.toml for non-default paths. Use --base-url or [control_plane].base_url to target a control-plane. When control-plane auth is enabled, pass a bearer token with --token or GUARDIAN_CONTROL_PLANE_TOKEN.

Rust guest SDK

Section titled “Rust guest SDK”

Add the SDK to a Rust plugin crate:

[lib]
crate-type = ["cdylib"]


[dependencies]
guardian-plugin-sdk = { path = "../../crates/guardian-plugin-sdk" }

Minimal plugin:

use guardian_plugin_sdk::{export_plugin, Decision, Request};


fn handle(_request: Request) -> Decision {
    Decision::allow()
}


export_plugin!(handle);

Build for WASI:

Terminal window
cargo build --release --target wasm32-wasip1

Manifest

Section titled “Manifest”

guardian.plugin.toml describes the reusable plugin package; guardian.config.toml owns the desired configuration scope and the complete [[deployment.entries]] set applied by guardian-plugin config apply (see plugin configuration as code).

Important defaults:

  • publish uploads artifacts unsigned; a configured control-plane [plugins.publisher_signer] signs artifact records and configuration manifests.
  • publish never changes configuration state; config apply validates, creates, and activates the declared entry set for the exact scope.
  • config plan/apply compare the complete desired entry set with the exact active configuration; entries not declared in the manifest are removed.
  • builtin.authorization is never inserted implicitly. Declare it in [[deployment.entries]] when it belongs in the chain.

See:

  • test-plugins/rust-allow-all/guardian.plugin.toml
  • test-plugins/rust-host-capability-probe/guardian.plugin.toml
  • test-plugins/allow-all.guardian.plugin.toml
  • llm-gateway/docs/local-plugin-e2e.md

Control-plane signer

Section titled “Control-plane signer”

The control-plane can sign plugin releases during authenticated admin upload:

[plugins.publisher_signer]
key_id = "control-plane-publisher"
seed_file = "/run/secrets/guardian-plugin-publisher-seed"

Configure gateways with the matching public key:

[plugins.trusted_signer_keys]
control-plane-publisher = "did:key:z..."