Python Guards Guide¶

Overview¶

The Python Guard SDK lets you create custom guards entirely in Python by subclassing the CustomGuard base class.

Installation¶

pip install oxideshield

Or with uv:

uv pip install oxideshield

Creating a Custom Guard¶

from oxideshield import CustomGuard

class MyGuard(CustomGuard):
    def __init__(self):
        super().__init__("MyGuard")

    def check(self, text):
        if "bad" in text.lower():
            return self.flag("Found bad keyword")
        return self.pass_check()

# Usage
guard = MyGuard()
result = guard.check("this is bad content")
print(result)        # GuardCheckResult(passed=False, ...)
print(result.passed) # False
print(result.reason) # "Found bad keyword"

CustomGuard API¶

Constructor¶

CustomGuard(name, action="block")

name — Guard name (string)
action — Default action: "block", "allow", "alert", "log", "sanitize", "suggest"

Methods¶

`pass_check()`¶

Returns a passing result (content is safe):

return self.pass_check()

`flag(reason, matches=None)`¶

Returns a failing result (content is flagged):

# Simple flag
return self.flag("Found suspicious content")

# Flag with matches
matches = [
    CustomGuard.create_match("bad_word", start=5, end=13, category="profanity")
]
return self.flag("Found profanity", matches=matches)

`create_match(text, start=0, end=0, category="custom")`¶

Static method to create match objects:

match = CustomGuard.create_match(
    text="suspicious_phrase",
    start=10,
    end=27,
    category="injection"
)

Examples¶

Keyword Guard¶

class KeywordGuard(CustomGuard):
    def __init__(self, keywords):
        super().__init__("KeywordGuard")
        self.keywords = [kw.lower() for kw in keywords]

    def check(self, text):
        lower_text = text.lower()
        found = [kw for kw in self.keywords if kw in lower_text]
        if found:
            return self.flag(f"Found keywords: {', '.join(found)}")
        return self.pass_check()

Regex Guard¶

import re

class RegexGuard(CustomGuard):
    def __init__(self, patterns):
        super().__init__("RegexGuard")
        self.patterns = [re.compile(p) for p in patterns]

    def check(self, text):
        matches = []
        for pattern in self.patterns:
            for m in pattern.finditer(text):
                matches.append(
                    CustomGuard.create_match(
                        text=m.group(),
                        start=m.start(),
                        end=m.end(),
                        category="regex_match"
                    )
                )
        if matches:
            return self.flag(f"Found {len(matches)} regex match(es)", matches=matches)
        return self.pass_check()

ML Guard¶

class MLGuard(CustomGuard):
    def __init__(self, model_path, threshold=0.5):
        super().__init__("MLGuard")
        self.threshold = threshold
        # self.model = load_model(model_path)

    def check(self, text):
        # score = self.model.predict(text)
        score = 0.1  # placeholder
        if score >= self.threshold:
            return self.flag(f"ML score {score:.3f} exceeds threshold {self.threshold:.3f}")
        return self.pass_check()