convez.ai
MCP Server
tenuo-ai

claude-governance

tenuo-ai/claude-governance

Ver no GitHub
InicialPluginScore · de 0 a 100

Governance for Claude Code: audit and constrain which tools and arguments Claude Code can use, with cryptographic Tenuo warrants enforced on every call.

Instalação

$npx convez-ai tenuo-ai/claude-governance

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
62%
Último commit
há 3 dias
Versão
v0.7.0
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Tenuo for Claude Code

PyPI Python CI License: Apache-2.0

Claude Code can read files, run shell commands, fetch URLs, and call MCP tools. Tenuo lets you write a tenuo.yaml policy for which of those calls are allowed, then checks every model-invoked tool call before it runs.

That policy is compiled into a signed, expiring credential called a warrant. A local authorizer checks each tool call against it and logs the decision. The same policy is applied no matter why the model tried the call: prompt injection, hallucination, poisoned tool output, or an unsafe request.

Start with the local quickstart below. Optional Cloud control-plane setup is in Cloud mode.

Quickstart

Requires Python 3.10+. Uses Docker if it's running; otherwise a native authorizer binary, installed automatically.

pip install tenuo-claude-code
mkdir my-project && cd my-project
tenuo-claude bootstrap

bootstrap writes a starter tenuo.yaml, starts the authorizer, and runs a self-test (verify). The starter policy is deliberately strict:

name: my-project
sandbox: ./workspace
mode: enforce
enforce:
  Read: "subpath:{sandbox}"          # Read only files under ./workspace
  Bash: "shlex:ls,pwd,echo,date"     # Bash only these commands
default: deny                        # every other tool call is denied

Now open Claude Code in my-project/:

claude

The agent is governed: Read ./workspace/notes.txt is allowed; Read /etc/passwd, Bash(curl …), or any tool not listed is denied and logged. After Claude runs a few tools, run tenuo-claude audit to see the decisions. Edit tenuo.yaml to fit your project (see Policy), then tenuo-claude refresh.

For an example with MCP and subagents, see the reference demo.

NextGo to
Write the policyPolicy
Day-to-day commandsCommands
Org root, receipts, approvals, revocationCloud mode
Security model and limitsSecurity
Something brokeTroubleshooting · deep dive docs/DETAILS.md

Policy

tenuo.yaml is the whole configuration — it drives the warrant, the authorizer, the hooks, and the MCP proxy. You list tools under enforce: and give each a constraint on its key argument.

name: acme-backend
sandbox: ./workspace        # a directory; {sandbox} expands to its absolute path
mode: enforce               # block out-of-scope calls. 'audit' = log only, don't block

enforce:
  Read:  "subpath:{sandbox}"
  Write: "subpath:{sandbox}"
  Bash:  "shlex:ls,pwd,echo,cat,grep"
  WebFetch:
    domains: ["api.github.com", "*.githubusercontent.com"]

default: deny               # anything not listed above is denied

subagents:                  # optional: each role runs under a narrower warrant
  analyst:
    tools: [Read, Grep, Glob]

mcp:                        # optional: govern a downstream MCP server's tools
  downstream: ./your_mcp_server.py
  enforce:
    read_file: "subpath:{sandbox}"

Constraints

Each constraint checks one argument of the tool call:

ConstraintApplies toWhat it checks
subpath:DIRpath tools (Read, Write, Edit, Glob, Grep)the path argument must resolve to a location inside DIR. Symlinks are resolved first, so a link planted in the directory can't point outside it.
shlex:a,b,cBashthe command's executable must be one of a,b,c, and the command must be a single simple command — pipes, &&/; chaining, subshells, and shell expansion are rejected. (This allowlists the verb, not file paths: cat /etc/passwd passes if cat is allowed. Use Read/Write to scope files; drop Bash for a hard lock.)
domains / cidrsWebFetchthe URL's host must match an allowed domain (* matches one label) or CIDR range, and pass SSRF hygiene — https-only by default, with loopback, cloud-metadata IPs, encoded-IP tricks, and spoofed hosts (api.github.com.evil.com) blocked.
oneof:a,b · exact:v · pattern:glob · regex:reany tool argumentthe value must be in the set / equal / glob-match / regex-match.

{sandbox} is a convenience variable for the directory in sandbox:; you can point subpath: at any path. Tools you don't list aren't governed individually — they're caught by default.

  • mode: enforce blocks denied calls. mode: audit computes and logs the same decisions but blocks nothing — use it to dry-run a policy, then switch to enforce.
  • default: deny denies any tool not listed (recommended). default: audit logs-and-allows unknown tools instead.
  • subagents: declares roles; spawning is gated to those roles, and each runs under the session warrant attenuated to its tools (it can only ever do less than the session). Details.

Ready-made policies: examples/policies/. After any edit, run tenuo-claude refresh.

Commands

Day to day, you mostly need up (start), audit (review), and refresh (after editing policy).

CommandWhat it does
onboardStart here. Interactive first-run setup (--local / --cloud); scaffolds an example policy if you don't have one.
bootstrapNon-interactive first run: scaffold starter policy (if none) → init → up → verify. --cloud for Cloud.
initCompile an existing tenuo.yaml: mint the warrant, wire the PreToolUse hook and MCP proxy. Pass --scaffold to write an example if none exists (it no longer does so automatically).
up / downStart / stop the authorizer (auto-selects Docker or native; --native to force).
refreshRecompile after editing tenuo.yaml (restarts the authorizer if running). In Cloud mode, warns if capability rules drifted from the last tenuo-admin setup.
verify [--deep]Self-test the live policy against the authorizer — no Claude session needed. --deep adds an SSRF / encoded-IP matrix, extra Bash deny cases, and a live PreToolUse exit-code harness — a reproducible artifact for security review.
audit [--tail N]Show the decision log (.state/receipts.jsonl).
checkPreflight: dependencies, wiring, audit-sink health, leaked admin keys, and (Cloud) control-plane bindings.
statusWarrant, mode, audit-sink health, and Cloud summary.
install-authorizerInstall the native authorizer to ~/.tenuo/bin (no Docker, no Cargo).
bench [--json]Measure per-call overhead on your machine (PoP sign, authorizer round-trip, full hook path).
revokeRevoke the current session warrant.

The warrant is short-lived (~1h TTL); up refreshes it. The authorizer listens on 127.0.0.1:9090 — change it with TENUO_AUTHORIZER_PORT before bootstrap. Generated files (don't commit): .state/ (keys, warrant, credentials), .claude/settings.json (hooks), .mcp.json (MCP wiring).

Working from a git clone instead of PyPI? See Build from source.

How enforcement works

init compiles tenuo.yaml into a signed warrant and wires two interception points; both check the same warrant against the same local authorizer:

  • Native tools (Read, Bash, WebFetch, …) → a Claude Code PreToolUse hook intercepts the call, signs a proof-of-possession with the session key, and asks the authorizer.
  • MCP tools → Claude is pointed at a proxy that stands in for the downstream MCP server; the proxy authorizes, then forwards only if allowed.

Architecture

The authorizer (a small local service, ~1–3 ms/call) verifies the warrant's signature, proof-of-possession, and expiry, then checks the call's arguments against the warrant's constraints → allow, deny, or (Cloud) approval-required. Full detail in docs/DETAILS.md.

Cloud mode

Local mode is enough to evaluate Tenuo on one project. Connect cloud.tenuo.ai for organization-scale governance:

  • Tenant-root warrants — sessions chain to your org root, not a key on the laptop.
  • Signed receipts — one verifiable allow/deny/approval audit stream (Ed25519 over CBOR).
  • Fleet revocation — revoke a warrant id; authorizers pick it up within ~30s.
  • Human approval gates — specific calls pause for a person instead of allow/deny (below).
  • Managed rollout — push hook/MCP wiring through Claude Code managed settings instead of per-project local settings.

Setup

Two keys, kept apart — the runtime never sees the admin key:

KeyFromGoes inUsed by
Runtime (tenuo_ct_…)cloud.tenuo.ai → Agents → Quick Connect → Authorizer Only.state/cloud.envtenuo-claude up, hooks
Tenant-admin (tc_…)Settings → API Keys → Create (admin role)~/.tenuo/admin.envtenuo-admin setup (once)
mkdir my-project && cd my-project
tenuo-claude bootstrap --cloud      # wizard prompts for the runtime token, then sets up + verifies

Every session after that:

tenuo-claude check && tenuo-claude up

If check reports a cloud bindings failure, run tenuo-admin setup and retry.

tenuo-claude up refuses to start if a tenant-admin key is in the environment — keep it only in ~/.tenuo/admin.env. And once a project is on Cloud, don't re-run plain bootstrap: it reverts the project to local mode and moves your Cloud files aside. Use check && up.

CI / non-interactive and manual step-by-step setup: docs/DETAILS.md § Tenuo Cloud. After changing enforce/mcp/subagents/approvals on Cloud, re-run tenuo-admin setup; for mode-only changes, refresh suffices.

Human approval (Cloud)

A gated capability returns a third outcome — approval-required — instead of allow/deny. The hook opens a Cloud approval request, waits for an approver on their notification channel, then re-authorizes with their signed approval. The repo ships two worked examples (off-allowlist WebFetch, and delete_deployment with target=production). Setup and policy shape: docs/DETAILS.md § Human approval.

Security

Tenuo runs alongside Claude Code permissions; it doesn't replace managed settings. The difference is where and how policy is enforced:

Claude Code permissionsTenuo warrant
FormAllow/ask/deny rules in settingsSigned, expiring capability token; Cloud chains to your org root
Enforcement pointClaude's permission UIPreToolUse hook + MCP proxy, checked by the authorizer
--dangerously-skip-permissionsSkips the promptsDoes not disable installed Tenuo hook/proxy checks
ExpiryUntil edited~1h session TTL; up refreshes
RevocationEdit rules (live sessions may keep allowances)Revoke warrant id → ~30s fleet sync (Cloud)
EvidenceOptional hook logsLocal JSONL; signed receipt stream in Cloud
Org deploymentPer-user settings, locally editableManaged-settings hooks + shared policy

Admins can also block the bypass flag entirely in managed settings (disableBypassPermissionsMode).

What's in scope. Tenuo governs model-invoked tool calls — Read, Bash, WebFetch, MCP tools, subagent spawns — on the PreToolUse path, including the agent's own Bash. The TUI ! shell (a command the operator types) is not a tool call and is out of scope; the model can't invoke it. (details)

Fail-closed. A missing or broken tenuo.yaml denies every governed call until it's restored. Keys under .state/ must be owner-only (0600).

Receipts. Every governed call carries a proof-of-possession signature the authorizer verifies. Locally, the hook appends a JSON line to .state/receipts.jsonl (read with tenuo-claude audit; in mode: audit, denials show as WOULD-DENY):

{"phase":"pre","decision":"deny","claude_tool":"Read","governed":true,
 "args":{"file_path":"/etc/passwd"},"reason":"Constraint not satisfied"}

Connected to Cloud, the authorizer also emits signed receipts to your tenant — the verifiable record for compliance and fleet audit.

Rolling out to a team. Keep tenuo.yaml in version control, push the hook/MCP wiring through Claude Code managed settings (not per-developer settings.local.json), and use Cloud for org-root warrants, central audit, and revocation. Start in mode: audit, review the WOULD-DENY rows, then switch to enforce. Talk to us about managed-settings rollout. Report issues: SECURITY.md.

Build from source

For development, running the demo from a checkout, or using ./bin/tenuo-claude:

git clone https://github.com/tenuo-ai/claude-governance.git
cd claude-governance
uv venv && uv sync && source .venv/bin/activate     # Windows: .venv\Scripts\activate
chmod +x bin/tenuo-claude
uv run tenuo-claude install-authorizer              # only if you don't use Docker

Run via ./bin/tenuo-claude --help, uv run tenuo-claude --help, or pip install -e .. Re-run tenuo-claude init (or refresh) after moving the repo or reinstalling — the hooks pin the launcher path at wiring time. Contributors: CONTRIBUTING.md.

Performance

Authorization is ~1–3 ms per call; the command hook adds ~100–200 ms (mostly process startup). Measure on your machine with tenuo-claude bench after up.

This repo

GitHub: tenuo-ai/claude-governance · PyPI: tenuo-claude-code

PathContents
src/tenuo_claude_code/Package source
templates/Starter tenuo.yaml and credential examples
examples/policies/Ready-made policy templates
demo/Reference project and scripted tour
docs/Implementation details · Troubleshooting
Ver o original no GitHub

Bom para

Relacionados