Metadata-Version: 2.4
Name: suvra
Version: 26.3.1
Summary: The action layer for AI agents — control, record, compound.
Author-email: Suvra <sales@suvra.io>
License-Expression: Apache-2.0
Project-URL: Homepage, https://suvra.io
Keywords: ai-agents,agent-security,llm,guardrails,firewall,mcp,claude-code,codex,policy-enforcement,audit,ai-governance,tool-use
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: python-multipart>=0.0.31
Requires-Dist: cryptography>=48.0.1
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: respx>=0.22.0; extra == "dev"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.2.0; extra == "postgres"
Provides-Extra: ai
Requires-Dist: chromadb>=0.5.0; extra == "ai"
Requires-Dist: sentence-transformers>=3.0.0; extra == "ai"
Requires-Dist: datasets>=2.19.0; extra == "ai"
Requires-Dist: instructor>=1.0.0; extra == "ai"
Requires-Dist: polars>=0.20.0; extra == "ai"
Requires-Dist: opentelemetry-api>=1.24.0; extra == "ai"
Requires-Dist: opentelemetry-sdk>=1.24.0; extra == "ai"
Requires-Dist: opentelemetry-exporter-otlp>=1.24.0; extra == "ai"
Dynamic: license-file

# Suvra

> Suvra — the action layer for AI agents.
> Control what they do, remember everything they did, and get smarter every time they do it.

![Status](https://img.shields.io/badge/status-active-success)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-Apache--2.0-blue)

Suvra intercepts every dangerous action your AI agent takes — `rm -rf`, `DROP TABLE`,
force-pushes, prod deploys, secret-file access — blocks the catastrophic ones by default,
routes the risky ones to a human for approval in Slack, and keeps a deterministic audit
trail. One line to install. No YAML required to get value.

## Why

Suvra stops your agents from destroying things. Autonomous coding and ops agents are now routinely given real shell, database, and cloud
access — and they occasionally use it to catastrophic effect, including a widely-reported
incident where a coding agent wiped a production database during a code freeze, agents
that have deleted files and entire inboxes while "cleaning up," and runaway tool-call
loops that fire the same destructive command hundreds of times before anyone notices.
Suvra sits between your agent and the real world so the first time it tries something
like that, it gets blocked instead of executed.

## Quickstart (under 5 minutes)

```bash
pip install suvra
```

Watch it block catastrophic actions in a scripted demo:

```bash
suvra demo                      # watch it block catastrophic actions
```

Protect Claude Code with a `PreToolUse` hook:

```bash
suvra init claude-code          # protect Claude Code with a PreToolUse hook
```

Put a firewall in front of any MCP server:

```bash
suvra mcp wrap -- npx -y @modelcontextprotocol/server-filesystem .   # firewall any MCP server
```

That's it — no Docker, no Postgres, no bootstrap tokens, no policy file required to get
value on day one.

## What it catches

Suvra ships a deterministic, zero-config classifier that runs before any policy engine.
It is a regex/parser-based classifier — not an LLM, not a network call — so decisions are
sub-millisecond and reproducible.

| Class of action | Examples | Default outcome |
|---|---|---|
| Destructive shell | `rm -rf`, `mkfs`, `dd of=/dev/*`, fork bombs, `chmod -R 777`, `curl \| bash` | Blocked |
| Destructive SQL | `DROP TABLE`, `TRUNCATE`, `DELETE`/`UPDATE` without `WHERE` (incl. via `psql`/`mysql -e`) | Blocked |
| Force-push / history rewrite | `git push --force` to protected branches, `git reset --hard` | Blocked |
| Infra destroy | `kubectl delete`, `terraform destroy` / `-auto-approve` | Blocked |
| Secret-file access | `.env`, private keys, credential files | Gated for approval |
| Mass deletes | Bulk file/record deletion above a safe threshold | Gated for approval |

Everything else is deferred to policy (or allowed, if no policy is configured). When a
policy file is present, the built-in classifier and your policy both run, and the more
restrictive decision wins — the classifier is a floor, not a ceiling.

Deterministic guarantees:

- No LLM in the decision path.
- No network calls to reach a decision.
- Sub-millisecond evaluation.
- Every decision is explainable — you can see exactly which rule fired and why.

## Human approvals

Actions classified as `risky` (or matched by a `needs_approval` policy rule) don't get
silently blocked — they pause and wait for a human.

1. The agent's action is paused and an approval request is created.
2. If `SUVRA_APPROVAL_WEBHOOK_URL` is set, Suvra posts a notification to that URL.
3. Set `SUVRA_APPROVAL_WEBHOOK_FORMAT=slack` to get a formatted Slack Block Kit message
   (action summary, reason, and a link to approve/deny) instead of a raw JSON payload.
4. Set `SUVRA_DASHBOARD_URL` so the notification links straight to the approval in your
   dashboard.
5. An approver clicks approve or deny from Slack or the dashboard; the agent's action
   resumes (or stays blocked) based on that decision.

```bash
export SUVRA_APPROVAL_WEBHOOK_URL="https://hooks.slack.com/services/..."
export SUVRA_APPROVAL_WEBHOOK_FORMAT=slack
export SUVRA_DASHBOARD_URL="https://suvra.example.com"
```

<!-- TODO: dashboard screenshot — approvals inbox showing a pending Slack-notified request -->

See [docs/WEBHOOKS.md](docs/WEBHOOKS.md) for the full payload shape and signature
verification.

## Beyond zero-config: the policy engine

Zero-config catches the catastrophic cases everyone agrees on. When you need more than
that, Suvra has a full deny-by-default policy engine underneath:

- Deny-by-default YAML policies, evaluated deterministically with no LLM in the path.
- A 69-rule built-in library spanning filesystem, shell, database, secrets, email, HTTP,
  and more enterprise-specific categories.
- A simulator so you can dry-run a policy change against real actions before it's live.
- A structured, explainable audit trail for every decision — which rule matched, why, and
  what the alternative would have been.

See [docs/QUICKSTART.md](docs/QUICKSTART.md) to write your first policy and
[docs/SUVRA_CONTEXT.md](docs/SUVRA_CONTEXT.md) for the full policy/rule reference.

## Control. Record. Compound.

Because Suvra sits in the action path — not observing your agents from outside —
every action your agents take becomes an asset. Three pillars, and every dashboard
module belongs to exactly one:

- **Control** — block catastrophic actions, gate risky ones for a human, allow safe
  ones through. This is the firewall: the zero-config classifier, the policy engine,
  the rules library and simulator, human approvals, and agent registration all live
  here.
- **Record** — nothing passes through invisibly. Every decision lands in the Audit
  Explorer with a full explainable trace; the same trail rolls up into SOC 2, NIST AI
  RMF, and ISO 27001 Compliance reports, and into Memory for durable, queryable
  agent knowledge.
- **Compound** — the record becomes signal. Evals track denial-rate drift over your
  agents' real decisions, the Learning Loop turns every blocked action and pending
  review into a lesson with per-agent and per-action patterns, and Analytics rolls
  pass/deny rates, action distribution, and cost-to-outcome up over time.

Runtime, Gateway, and Nodes are how this scales — policy-gated agent-to-agent
delegation, a workflow engine and MCP server registry (early access today), and
distributed enforcement near your agents — infrastructure underneath the three
pillars, not a fourth one.

Run `suvra serve` and open `http://127.0.0.1:8000/dashboard` to see all of it locally.

## Framework integrations

Frameworks are never installed as a dependency of Suvra — install the framework you use,
then import the matching wrapper.

| Framework | Module | One-liner |
|---|---|---|
| Claude Code | CLI (`suvra init claude-code`) | Installs a `PreToolUse` hook into `.claude/settings.json` |
| Claude Agent SDK | [`suvra.integrations.anthropic`](suvra/integrations/anthropic.py) | `suvra_hook(suvra)` as a `PreToolUse` `HookMatcher` |
| OpenClaw | [`suvra.integrations.openclaw`](suvra/integrations/openclaw.py) | `OpenClawGuard(suvra)` wraps the OpenClaw runtime |
| OpenAI Codex | CLI (`suvra init codex`) | Installs a `PreToolUse` hook into `.codex/hooks.json` |
| Hermes | CLI (`suvra init hermes`) | Merges a `pre_tool_call` shell hook into `~/.hermes/config.yaml` |
| Any MCP server | `suvra mcp wrap -- <cmd>` | Wraps any stdio MCP server; gates `tools/call` through the firewall |

Full usage examples for each: [docs/QUICKSTART.md](docs/QUICKSTART.md) and
[docs/SUVRA_CONTEXT.md](docs/SUVRA_CONTEXT.md).

## Pricing

| | Free | Team — $199/mo | Enterprise |
|---|---|---|---|
| Agents | 1 | Up to 10 | Custom |
| CLI + local firewall | Yes | Yes | Yes |
| Slack approvals | — | Yes | Yes |
| Shared control plane | — | Yes | Yes |
| Full audit export | — | Yes | Yes |
| SSO / RBAC / compliance reports | — | — | Yes |

Suvra is [Apache-2.0](LICENSE) licensed — free and open source, including production use.
Paid tiers aren't a license requirement; they're the hosted control plane and
Team/Enterprise features (Slack approvals, shared control plane, compliance reports,
SSO/RBAC, enforcement nodes, support). Full breakdown in [docs/PRICING.md](docs/PRICING.md).

## Enterprise

- Control plane plus enforcement nodes deployed near your agents, with RBAC and
  SSO-ready identity so access maps to how your org is actually structured.
- SOC 2, NIST, and ISO 27001 compliance report packs generated straight from the audit
  trail your agents already produce.
- Offline, fail-closed enforcement nodes keep protecting agents even when the control
  plane is unreachable — cached policy, no silent "allow if uncertain" fallback.

Enterprise installs use the same PyPI package as the quickstart above, with the
`postgres` extra, plus the repo's Docker Compose file for the full stack:

```bash
pip install "suvra[postgres]"
# or, for the full stack (Postgres-ready image + persistent volume):
docker compose up -d --build
```

Full deployment topology (Postgres, Caddy/reverse proxy, control plane + enforcement
nodes), HA guidance, and rollout steps: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).
Contact `sales@suvra.io` for enterprise licensing and onboarding.
