Suvra

Core Concepts

Suvra is built on a small set of well-defined primitives. Understanding these makes every other part of the product — policy authoring, approvals, audit, nodes — straightforward.

Actions

An action is the unit of work Suvra evaluates. Every action has a type, params, and an identity context (agent, user, role, environment, labels, and agent registry metadata).

Executable action types:

  • fs.write_file — supports dry_run, captures rollback payload, enforces workspace jail and max_bytes.
  • fs.delete_file — supports dry_run, captures original file bytes/mode for rollback, enforces workspace jail and symlink checks.
  • http.request — GET only, redirects blocked, applies allow-domain and timeout constraints.

Policy / simulation-only action types (fail closed at the executor boundary, never executed):

  • shell.exec — constrained by allow_commands and working_dir_prefix.
  • email.delete — constrained by allow_providers and allow_mailboxes.
  • secrets.read — constrained by allow_names.

Decisions

Every action evaluation produces one of three decisions:

  • allow — the action executes immediately.
  • deny — the action is rejected. No execution, no approval path.
  • needs_approval — execution is paused until a human reviewer approves or denies via the dashboard or API.

When no rule matches, the decision is always deny. Deny-by-default is a hard guarantee, not a configurable setting.

Two-tier policy model

Active runtime evaluation uses exactly two policy layers:

  1. Global policy (SuvraPolicy) applies to every agent.
  2. Agent policy (optional) is bound directly to an agent via agents.policy_id.

Deterministic merge rules:

  • deny overrides needs_approval and allow
  • needs_approval overrides allow
  • Within the same policy, the last matching rule wins
  • Agent-policy matches override global-policy matches

Rules and constraints

Rules come from the Rules Library — 17 category YAML files shipping 64 reusable rules across filesystem, HTTP, shell, secrets, email, database, API, PII, document, transaction, notification, compliance, CRM, storage, calendar, workflow, and code categories.

A rule is {id, effect, type, constraints?}. Supported constraints include:

  • Filesystem: path_prefix, max_bytes, working_dir_prefix
  • HTTP: method, allow_domains, timeout_seconds, host_in, host_prefix
  • Identity / context: agent, user, role, workspace, environment, labels, tenant_id, business_unit, domain
  • Command / provider: allow_commands, allow_providers, allow_mailboxes, allow_names

Identity-aware context

Every action carries identity context that rules can match against:

  • Request-supplied: agent, user, role, environment, workspace_dir, labels
  • Registry-derived (filled from the Agent Registry when agent_id is present): agent_id, risk_tier, approval_profile, runtime_type, owner, purpose, integration

Explicit request values always win; registry metadata fills only missing fields. This is used both for policy matching and for approval integrity hashing.

Approval integrity

When an action needs approval, Suvra stores a record keyed by actor + action_type + params_hash. The params_hash covers the normalized request context (agent, user, role, workspace, environment, tenant, labels) plus registry-aware policy context (agent_id, risk_tier, approval_profile, framework/integration, runtime_type, owner, purpose, status).

Before executing an approved action, Suvra verifies the presented approval matches the exact action context. A modified action paired with a recycled approval ID is rejected.

Rollback capture

Executors capture rollback payloads at execution time:

  • fs.write_file stores the original content (or a delete-on-rollback marker for new files).
  • fs.delete_file stores the deleted file's bytes and mode.

Rollback payloads are persisted to the audit DB and survive process restarts.

Enforcement modes

SUVRA_MODE controls the runtime behavior:

  • strict (default) — full policy enforcement plus approval gating.
  • monitor — policy is evaluated for observability only. Actions execute and audit records decision="monitor" with the would-be policy_decision. No approvals are created.
  • disabled — policy evaluation is skipped. Audit records decision="disabled". No approvals are created.

Executor-level safety (filesystem workspace jail, HTTP method/domain enforcement) applies in all modes. The simulator (/simulate) always runs in strict simulation mode regardless of SUVRA_MODE.

Distributed architecture

Suvra ships with two runtime roles:

  • Control Plane — dashboard, policy admin, approvals, central audit, node registry, published bundle distribution.
  • Enforcement Node — lightweight runtime near agents. Enforces policy locally against a cached last-known-good bundle, forwards approvals and audit events to the Control Plane.

End-to-end flow:

Agent → Enforcement Node → local Policy Engine → Executor → local audit spool
                            ↓
                    Control Plane → approvals, published bundles, central audit

Nodes fail closed when the Control Plane is unreachable: validate may proceed from the cached policy, and execute may proceed only for cached allow decisions. Approval-gated actions never degrade to local implicit allow — the node blocks with OFFLINE_APPROVAL_REQUIRED.

RBAC

Built-in tenant roles:

  • Viewer — read-only
  • Operator — operational actions (e.g., approvals)
  • Policy Admin — policy and rules management
  • Admin — full tenant administration

Permissions cover users.*, roles.assign, policies.*, approvals.*, audit.*, agents.*, nodes.*, billing.*, and settings.write. Every dashboard route enforces server-side authorization and returns HTTP 403 on deny.

Audit-first design

Every validate, execute, approval state transition, simulate, and rollback flow is persisted with:

  • Identity context (agent, user, role, environment, labels, tenant/domain)
  • Matched policy id, version, scope level, status
  • matched_rule_id, reasons, per-constraint checks, structured decision_trace, precedence_trace
  • Rollback payload when available

Audit events are exported via GET /audit.csv and GET /audit.json with stable filter envelopes. See the Audit Explorer docs for the dashboard view.