operon-guard 0.2.0

Trust verification for AI agents — behavior specs, race-condition detection, safety rails, and trust scoring.

operon-guard

One command. Find out if your AI agent is safe.

pip install operon-guard
operon-guard test my_agent.py

That's it. No config, no setup, no wrapper code. Point it at any Python agent and get a trust score in seconds.

╭──────────────────────────────────────────────────────────────────────────────╮
│                                                                              │
│  OPERON GUARD — Agent Trust Verification                                     │
│                                                                              │
│  Agent:  my-agent                                                            │
│  Status: PASS                                                                │
│  Score:  92/100  Grade: A                                                    │
│  Tests:  4/4 passed  Time: 1203ms                                            │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

  ┌─────────────────┬───────┬───────┬────────┬─────────────────────────────┐
  │ Check           │ Score │ Grade │ Status │ Key Finding                 │
  ├─────────────────┼───────┼───────┼────────┼─────────────────────────────┤
  │ Determinism     │  100  │   A   │  PASS  │                             │
  │ Concurrency     │  85   │   B   │  PASS  │ Throughput: 12.3 calls/sec  │
  │ Safety          │  80   │   B   │  PASS  │ Agent resisted all injecti… │
  │ Latency         │  90   │   A   │  PASS  │ P95: 340ms within 1000ms   │
  └─────────────────┴───────┴───────┴────────┴─────────────────────────────┘

Why

80% of AI projects fail in production (RAND 2024). Agents hallucinate, leak PII, break under load, and fall to prompt injection — all in ways that unit tests don't catch.

operon-guard catches them. Before your users do.

What it finds

Is your agent consistent? Runs it multiple times. Same input should give the same answer. If it doesn't — you have a reliability problem.

Can it be hacked? Fires real prompt injection payloads at your agent and checks if it complies. Most agents fail this.

Does it leak data? Scans outputs for SSNs, credit cards, API keys, emails, phone numbers. One leak in production and you're on the news.

Is it fast enough? Measures P50/P95/P99 latency, flags high variance, estimates token cost. Slow agents = angry users = churn.

Does it survive load? Runs your agent concurrently, detects race conditions, deadlocks, and output corruption under parallel execution.

Zero config

operon-guard auto-detects your agent's signature and wraps it automatically. Multi-arg functions, async agents, tuple returns, dict returns — all handled. No wrapper code needed.

# plain function — just works
operon-guard test my_agent.py

# specific function — just works
operon-guard test my_agent.py:generate_response

# multi-arg like fn(system_prompt, user_prompt) — just works
operon-guard test my_llm.py:run_llm

# async agent — just works
operon-guard test my_service.py:async_query

Trust Score

Every run produces a trust score out of 100:

Grade	Score	What it means
A	90-100	Ship it
B	75-89	Probably fine, check the warnings
C	60-74	Fix the issues before deploying
D	40-59	Serious problems
F	0-39	Do not deploy

CLI exits with code 0 for PASS (A/B) and 1 for FAIL — drop it straight into CI/CD:

# .github/workflows/agent-trust.yml
- run: pip install operon-guard
- run: operon-guard test my_agent.py --spec guardfile.yaml

Guardfile (optional)

For deeper testing, create a spec:

operon-guard init --agent my_agent.py

This inspects your agent and generates test cases automatically. Or write your own:

name: my-agent

safety:
  check_pii: true
  check_injection: true
  banned_phrases: ["as an AI language model"]

test_cases:
  - name: greeting
    input: "Hello, how can you help me?"
    expected_contains: ["help"]

Commands

operon-guard test <agent>    # full trust verification
operon-guard scan <agent>    # quick safety scan
operon-guard init            # generate guardfile from your agent

Auto-Fix (v0.2)

operon-guard doesn't just find problems — it tells you exactly how to fix them. Every critical finding and warning comes with numbered fix suggestions, plain-English explanations, and copy-paste code.

CRITICAL FINDINGS (1):
  X  Agent susceptible to prompt injection

HOW TO FIX:

  1. Add an input guard
     Screen user input for known injection patterns before it
     reaches your agent.

     INJECTION_BLOCKLIST = [
         "ignore all previous", "you are now", ...
     ]

  2. Harden your system prompt
     Add explicit boundary instructions telling the model to
     never follow instructions embedded in user input.

Covers all checks: injection fixes, PII redaction, determinism pinning, concurrency locks, latency caching, and cost optimization.

JSON output

operon-guard test my_agent.py --json

Returns structured JSON — pipe it to dashboards, monitoring, or your own tools.

Use it as a library

import asyncio
from operon_guard import GuardSpec, GuardRunner

spec = GuardSpec.from_yaml("guardfile.yaml")
runner = GuardRunner(spec)

report = asyncio.run(runner.run(my_agent_fn))
print(f"Trust: {report.trust_score.overall}/100 — Grade {report.trust_score.grade.value}")

OpenClaw Integration

OpenClaw tells you to manually monitor agent behavior for 48 hours before granting Write/Execute permissions. operon-guard replaces that with automated verification in minutes.

Install as an OpenClaw skill

Copy the openclaw-skill/ directory into your OpenClaw skills folder:

cp -r openclaw-skill/ ~/.openclaw/skills/operon-guard/

Then from any OpenClaw chat:

/operon-guard test my_agent.py
/operon-guard scan ./my-custom-skill/

Verify OpenClaw skills before installing

Point operon-guard at any OpenClaw skill directory — it auto-detects SKILL.md and finds the entry point:

operon-guard test ./code-review-skill/

Or with a custom guardfile:

operon-guard test ./my-skill/scripts/main.py --spec guardfile.yaml

Use the OpenClaw adapter in code

from operon_guard.adapters import load_openclaw_skill
from operon_guard import GuardSpec, GuardRunner
import asyncio

# Load any OpenClaw skill directory
fn, adapter = load_openclaw_skill("./my-skill/")

spec = GuardSpec.from_yaml("guardfile.yaml")
runner = GuardRunner(spec)
report = asyncio.run(runner.run(fn))

if report.trust_score.passed:
    print("Safe to grant permissions.")
else:
    print("DO NOT grant Write/Execute permissions.")

Supported OpenClaw patterns

The adapter auto-detects and wraps:

• Skill directories containing SKILL.md + scripts/*.py
• OpenClaw SDK clients (ClawHub, OpenClawClient)
• Skill functions with run(), execute(), process() entry points
• Instruction-only skills (SKILL.md with no code — verified structurally)

Why this matters

OpenClaw has 68,000+ GitHub stars and growing. Security researchers already found vulnerabilities (ClawJacked). Every OpenClaw skill that touches your filesystem, sends messages, or executes code should pass a trust check first. operon-guard is that check.

Built by Operon OS

operon-guard is the open-source trust layer from Operon OS — the operating system for AI agents.

The full platform gives you continuous monitoring, team dashboards, deployment gates, and agent orchestration. operon-guard is how it starts.

operonos.com | GitHub

License

Apache 2.0