shugo 0.1.0

Minimal MCP guardrails proxy — policy-first, human approvals, hash-chained audit log.

A practical, readable AI agent guardrails framework —
and a working example of how agents should be governed.

Documentation · Quickstart · Repo Structure · Policies · Roadmap

---

🛡️ What is SHUGO? SHUGO is a guardrails-first framework for the agentic AI community. It helps teams define policies, approval gates, tool access, evaluation, observability, and incident response in one repo. It is designed to make AI agent behaviour bounded, visible, and accountable. Responsible AI should not live in a slide deck. It should live in the same repo as the agent — expressed as code, enforced at runtime, and producing evidence by default.

shugo_repo -> shugo_policy -> shugo_runtime 📁 Repo Structure src/shugo/ Proxy, policy engine, audit, CLI policies/ Policy rules and standards examples/ Runnable demo agents and configs evaluations/ Tests, evals, and benchmarks logs/ Runtime events and audit logs docs/ Quickstart, policy guide, layers guardrails.yaml Guardrail configuration incident-playbook.md Incident response and recovery README.md Project overview and getting started

A guardrail should not merely tell an agent what it should do.
The system should enforce what the agent is allowed to do.

---

🧱 Five Guardrail Layers

👤 Identity & Access	🗄️ Data & Context	🔧 Action & Autonomy	🛡️ Safety & Resilience	🎖️ Governance & Assurance
Verify who and what can act, with least privilege and strong authentication.	Control what data enters the agent and how context is handled.	Restrict tools, enforce policies, and require approvals for high-risk actions.	Detect, block, and recover from unsafe behaviour and system failures.	Audit, evaluate, and report to ensure accountability and continuous trust.
v0.1 · partial	v0.1 · partial	v0.1 · full	v0.1 · partial	v0.1 · full

Layers ③ and ⑤ ship complete in v0.1. The others ship at the minimum depth needed to make those two credible, then deepen along the roadmap.

---

⚙️ How it works

SHUGO presents itself to your agent as a standard MCP server and sits between the agent and the tools it calls. Every tools/call is evaluated against a human-readable policy file before it reaches an upstream server. No protocol changes. No agent code changes.

┌──────────────┐   MCP    ┌───────────┐   MCP    ┌──────────────────┐
│  MCP client  │ ───────▶ │   SHUGO   │ ───────▶ │ Upstream MCP     │
│ (any agent)  │ ◀─────── │   guard   │ ◀─────── │ servers (n)      │
└──────────────┘          └─────┬─────┘          └──────────────────┘
                                │
                    ┌───────────┼───────────┐
                    ▼           ▼           ▼
              guardrails    audit log    approval
                 .yaml      (JSONL)       channel

Works with Claude Desktop, Claude Code, Cursor, VS Code, and any framework with an MCP adapter — LangGraph, CrewAI, the OpenAI Agents SDK, n8n.

---

⚡ Quickstart

uvx shugo init      # scaffold a policy from your existing MCP config
uvx shugo serve     # start guarding

Point your MCP client at SHUGO instead of your servers:

{
  "mcpServers": {
    "shugo": {
      "command": "uvx",
      "args": ["shugo", "serve", "--config", "guardrails.yaml"]
    }
  }
}

Your agent now sees only the tools policy allows, blocks on anything needing approval, and writes an audit record for every call it makes.

---

📜 Policy as code

The most important file in the project. Design target: a risk lead can read it unaided, and a reviewer can diff it in a pull request.

version: "0.1"

defaults:
  decision: deny            # deny by default; allowlist upward
  on_error: deny            # fail closed

rules:
  - id: read-only-github
    match:
      server: github
      tool: ["get_*", "list_*", "search_*"]
    decision: allow

  - id: no-force-push
    description: Force push can destroy history irrecoverably
    match:
      server: github
      tool: push
      args: { force: true }
    decision: deny
    reason: Force push is prohibited for autonomous agents.
    controls: [OWASP-LLM06, NIST-AI-RMF-MANAGE-2.2]

  - id: ticket-write-needs-approval
    match:
      server: tickets
      tool: ["update_ticket", "close_ticket"]
    decision: escalate
    approval:
      channel: cli
      timeout_seconds: 300
      on_timeout: deny
    controls: [EU-AI-ACT-ART-14]

Deny by default. First match wins, top to bottom. Globs, not regex — readability is the constraint.

---

🧾 Evidence, not just logs

Enforcement without evidence is unauditable. Evidence without enforcement is theatre. SHUGO does both.

shugo evidence --framework owasp-llm --since 30d --out evidence/

Reads the audit log and produces a control-by-control bundle: which rules were in force, how often each fired, approval latency, exceptions, coverage gaps, and a hash-chain integrity check.

Framework mappings ship as data files sourced from public standards only — NIST AI RMF, EU AI Act, OWASP Top 10 for LLM Applications, and ISO/IEC 42001 control identifiers.

Scope note. SHUGO produces evidence about the guardrail layer. It does not certify an organisation as compliant with any standard.

---

🧰 CLI

Command	Purpose
shugo serve	Run the guard proxy
shugo init	Scaffold a starter policy from installed MCP servers
shugo validate	Lint and schema-check the policy file
shugo explain	Dry-run a call — see which rule fires and why
shugo audit tail / verify	Inspect the log, verify the hash chain
shugo evidence	Generate an evidence bundle
shugo halt	Kill switch — deny all calls immediately

---

🗺️ Roadmap

Version	Theme
v0.1	Guard proxy, policy engine, approvals, audit log, evidence packs
v0.2	Layer ① depth — OAuth 2.1 / OIDC identity, per-principal policy, delegation scoping
v0.3	Layer ② depth — retrieval boundaries, context filters, memory access rules
v0.4	Layer ④ depth — injection detection, output validation, rollback
v0.5	Layer ⑤ depth — policy regression suites, adversarial harness
v1.0	Frozen policy schema, semantic versioning guarantee, plugin API

---

🤝 Contributing

SHUGO is built in public, and the contribution ladder is deliberately low to the ground:

policy pack → scenario test → framework mapping → core

A new policy pack is a self-contained YAML file. You do not need to read the codebase to ship one. Start with CONTRIBUTING.md and the good first issues.

---

📄 License

Released under the MIT License. Use it, fork it, adapt it to your own agent architecture — that is the point.

---

_{守護 — shugo, to guard and protect.}