Governance

Governance

Clasper Core is a governance plane. Its job is not “to run agents” — it is to decide whether execution is allowed, under what constraints, and to prove what happened.

Trust boundaries: OSS provides local approvals and self-attested evidence. Cloud adds external proof. See OSS vs Cloud.

Core principles

• No silent governance gaps: unknown tool surfaces should not run “by accident”. Use explicit policies (and fallback rules for extensible tool ecosystems).
• Everything is attributable: every execution has an execution_id and trace_id with audit events.
• Adapters are clients: executors never get implicit authority.
• Humans can intervene: overrides require justification and are audited.

Decisioning (pre-execution)

Before execution, Core evaluates:

• RBAC: who/what is requesting execution and what they’re allowed to do.
• Risk: including adapter risk class + capability breadth.
• Cost & budgets: forecast/ceilings and hard limits.
• Overrides / approvals: structured, audited exceptions.

The output is an ExecutionDecision granting a bounded scope (capabilities, cost/steps/time limits) or denying the request.

Execution context signals (v2)

For high-risk capabilities (e.g. shell.exec, broad network access), adapters can include optional context signals in the pre-execution request:

• intent — why the execution is being requested
• context — high-signal flags like external_network, writes_files, elevated_privileges, package_manager
• provenance — source metadata like marketplace vs internal

These fields improve:

• policy matching (more targeted rules; fewer blanket denies)
• risk scoring (better auto-approval vs approval gating decisions)
• approval UX (clearer prompts without exposing raw commands)

Unknown semantics: Policies match only on fields that are present. Missing fields are treated as unknown and do not imply false.

Example policy

policy_id: deny_marketplace_shell_exec_with_network
scope:
  tenant_id: t1
subject:
  type: adapter
conditions:
  capability: shell.exec
  context:
    external_network: true
  provenance:
    source: marketplace
effect:
  decision: deny
explanation: Deny marketplace skills that request shell execution with external network access.

Policy conditions reference (v2)

Clasper Core policy conditions are exact-match checks and only evaluate fields that are present in the request/context:

• If a condition references a field that is missing, it is treated as unknown and the condition does not match.
• Missing booleans do not imply false.

Supported condition keys

• Existing keys: adapter_risk_class, tool, tool_group, skill_state, risk_level, min_cost, max_cost, tenant_id, workspace_id
• Agent identity (for per-agent policies):
  • agent_id (string): matches when the execution request includes this agent identifier
  • agent_role (string): matches when the execution request includes this agent role
• Universal policy engine (actor/action/resource):
  • actor (string): generic actor identifier (falls back to agent_id when present)
  • action (string): e.g. exec, model.generate, data.send
  • resource (string): e.g. command, URL, data source
• Execution-request keys:
  • capability (string): matches when requested_capabilities[] contains the capability
  • intent (string)
  • context.external_network (boolean)
  • context.writes_files (boolean)
  • context.elevated_privileges (boolean)
  • context.package_manager (string)
  • provenance.source (marketplace | internal | git | unknown)
  • provenance.publisher (string)

Captured for audit but not matchable (yet)

• context.targets (array)
• provenance.artifact_hash (string)

Policy testing

Use clasper test [file] to run policy tests from YAML. Tests define sample events (actor, action, resource, context) and expected decisions. The Ops Console Policies view also supports an “Load actor/action/resource” template for dry-run testing.

Policy model + decision explainability (v2.2)

In v2.2, governance decisions are data-driven:

• policies are stored as data (not compiled into code)
• decisions return:
  • matched_policies[]
  • decision_trace[] (machine-readable explanation)
  • explanation (human-facing)
  • risk_score (0–100), risk_level (low/medium/high/critical)
  • policy_bundle_hash (SHA-256 of policy bundle at evaluation time)

This guarantees “no silent denies” — every denial or approval gate is explainable. Decision records are stored and viewable in the trace detail drawer.

Ops management endpoints:

• GET /ops/api/policies
• POST /ops/api/policies
• PATCH /ops/api/policies/:id
• DELETE /ops/api/policies/:id

Approvals (OSS): simulate vs enforce

Clasper Core supports local, self-attested approvals via the Ops Console. You can run in one of two modes:

• CLASPER_APPROVAL_MODE=simulate (default): require_approval gates are AUTO-APPROVED (dev-friendly) and the decision/audit explicitly labels this as a config override.
• CLASPER_APPROVAL_MODE=enforce: require_approval gates create a pending decision and execution pauses until an operator approves/denies.

Back-compat env var (still supported): CLASPER_REQUIRE_APPROVAL_IN_CORE (allow → simulate, block → enforce).

Async approvals (v2.2)

Some decisions cannot be resolved synchronously (high-risk tools, prod environments, unusual cost).

When Core requires approval, POST /api/execution/request returns a pending decision:

• decision: "pending"
• decision_id
• expires_at
• required_role

Adapters must pause execution and either:

• poll GET /api/execution/:executionId (quick “effect” check) or GET /api/decisions/:id, or
• provide a callback URL (optional)

On approval in OSS, the decision is resolved locally (self-attested) via the Ops Console:

• POST /ops/api/decisions/:decisionId/resolve

Adapters then resume by re-calling POST /api/execution/request with the same execution_id (Core returns an allow/deny decision on the retry/resume path).

Note: Decision tokens (/api/decisions/:id/consume) are Cloud-only.

Extensible tool ecosystems (OpenClaw): fallback policies

Some adapters (like OpenClaw) can gain new tools as skills/plugins are installed. In that world, “no matching policy” is a governance footgun.

Recommendation:

• Add a fallback policy in the adapter’s policy pack that matches any tool and yields require_approval (or deny) at a very low precedence.
• Emit an audit/metric when the fallback rule is hit so operators can tighten policy coverage over time.

Governance modes and posture (v2.3)

No-match behavior is controlled by CLASPER_MODE:

• permissive (default): no-match allows
• guarded: no-match requires a fallback policy; if missing, no-match is blocked
• strict: no-match denies

Canonical adapter posture endpoints:

• GET /api/adapter/posture
• GET /api/adapter/policy-posture (compatibility alias)

Posture status is deterministic and shared across API/CLI/tests:

• strict -> ENFORCED
• guarded + fallback present -> ENFORCED
• guarded + fallback missing -> DEGRADED
• permissive -> DISABLED

Create policy from trace

When a trace is blocked because no governing policy matched (only the fallback rule applied), the Ops Console shows a “Create policy from this trace” action. This is a policy-authoring assist, not an execution override:

• Clicking it opens a policy draft panel pre-filled from the trace (tool, scope, explanation seed). The operator must explicitly choose effect (allow / require approval / deny) and precedence; there are no defaults.
• The UI shows a blast-radius warning: “This policy will affect all future executions matching these conditions.”
• This does not approve or replay the blocked action. It only creates a rule for future executions. The blocked trace remains blocked; re-run the tool to exercise the new policy.
• Creating a policy from a trace is recorded in the audit log as policy_created_from_trace.

This workflow keeps authority explicit and reinforces the model: you author rules, not one-off approvals.

Adapter authentication (scoped)

Adapter endpoints require X-Adapter-Token:

• scope includes adapter_id, tenant_id, workspace_id, and allowed_capabilities[]
• tokens are verified using ADAPTER_JWT_SECRET

This is how Core enforces “adapters are clients, never peers”.

Signed telemetry (v2.1)

All ingest endpoints accept signed telemetry envelopes. Core verifies:

• adapter public key
• signature + payload hash
• clock skew

Unsigned payloads are allowed only in warn mode and marked unsigned.

Tool authorization (v2.1)

Before calling sensitive tools, adapters must request authorization:

POST /api/governance/tool/authorize

Core issues a short‑lived, single‑use token bound to the execution, tool, and scope.

Policy engine (v2.1)

Policies are evaluated for tool authorization:

• POST /api/policy/evaluate
• POST /api/policy/dry-run (ops)

Trust status + verifiable exports (v2.2)

Clasper Core attaches a trust status to every trace:

• verified
• verified_with_violations
• unverified
• compromised

For incident response and audits, Core can produce verifiable export bundles:

• POST /ops/api/exports
• npx clasper-core export ... (download bundle for offline use)

Telemetry ingest + idempotency

Telemetry ingest is first-class and idempotent:

• adapters can retry safely
• Core deduplicates ingest events per execution

This prevents “silent execution without receipts” and enables reliable operations in the presence of network failures.

Audit log

Core writes an append-only audit log for key events, including:

• execution decisions (allow/deny/override)
• adapter telemetry ingests (trace/cost/metrics/violations)

Related

• Policy Cookbook — Example policies (safe browser, controlled exec, restricted messaging)
• Adapter Contract
• Operations
• API Reference