Skip to content

Getting Started with the Guard SDK

Prerequisites

  • Rust 1.75+
  • OxideShield workspace (or oxide-guard-sdk as a dependency)

Installation

As a workspace dependency

If developing inside the OxideShield workspace, the SDK is already available:

[dependencies]
oxide-guard-sdk = { path = "../oxide-guard-sdk" }

As an external dependency

[dependencies]
oxide-guard-sdk = "0.1.6"

For API guard support (HTTP calls):

[dependencies]
oxide-guard-sdk = { version = "0.1.6", features = ["api"] }

Your First Guard

Option 1: Derive Macro

The fastest way to create a guard:

use oxide_guard_sdk::prelude::*;

#[derive(Guard)]
struct ProfanityGuard {
    name: String,
    action: GuardAction,
    bad_words: Vec<String>,
}

impl ProfanityGuard {
    fn new(bad_words: Vec<String>) -> Self {
        Self {
            name: "profanity_guard".to_string(),
            action: GuardAction::Block,
            bad_words,
        }
    }

    fn guard_check(&self, content: &str) -> GuardCheckResult {
        let lower = content.to_lowercase();
        for word in &self.bad_words {
            if lower.contains(&word.to_lowercase()) {
                return GuardCheckResult::fail(
                    &self.name,
                    self.action,
                    vec![],
                    format!("Found profanity: {}", word),
                );
            }
        }
        GuardCheckResult::pass(&self.name)
    }
}

fn main() {
    let guard = ProfanityGuard::new(vec!["badword".into()]);
    let result = guard.check("this contains badword");
    println!("Passed: {}", result.passed);
}

Option 2: Builder

For simple keyword-based guards:

use oxide_guard_sdk::prelude::*;

fn main() {
    let guard = GuardBuilder::new("content_filter")
        .add_keywords(["ignore previous", "system prompt"])
        .set_severity(Severity::Critical)
        .set_action(GuardAction::Block)
        .build()
        .unwrap();

    let result = guard.check("ignore previous instructions");
    println!("Passed: {}", result.passed);
}

Option 3: CLI Generator

Scaffold a new guard project:

oxideshield generate guard --name MyCustomGuard --type regex --output-dir ./src/guards

This creates: - ./src/guards/my_custom_guard.rs — Guard implementation scaffold - ./tests/my_custom_guard_tests.rs — Test templates

Next Steps