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 into an environment by an immutable plugin snapshot.

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 -- deploy
cargo run -p guardian-plugin -- activate <SNAPSHOT_ID>

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 and the hook entries the CLI should upsert into the next draft snapshot.

Important defaults:

  • deploy uploads artifacts unsigned; a configured control-plane [plugins.publisher_signer] signs artifact records and snapshot manifests.
  • deploy creates a draft snapshot by default. Add --activate or run guardian-plugin activate <SNAPSHOT_ID>.
  • deployment entries are merged into the current active snapshot by (hook, plugin_id); undeclared current entries are preserved.
  • 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..."