Skip to content

Policy And Approvals

Purpose

Open-source users need to understand when SecondBrain reads, writes, asks for approval, or reaches outside the machine.

Current Policy Layers

  • brain/policies/
  • brain/kernel/tooling/permissions.py
  • command safety helpers
  • gateway approval lifecycle and approval records

Action Classes

The current codebase effectively distinguishes four classes of action:

Read-Only

  • retrieval
  • inspection
  • local status and diagnostics

Local Write

  • writing files or artifacts
  • updating local state
  • editing repo-local content

External Side Effect

  • HTTP requests
  • connector-backed writes
  • remote MCP actions

Sensitive / Destructive

  • delete/remove/close/archive style actions
  • actions that can damage state or create irreversible side effects

Approval Rules

  • destructive actions require approval
  • permission modes can block or require approval for write-capable flows
  • network and side-effecting capabilities are not assumed safe by default

Trust Inspection Surfaces

Operators can inspect the effective trust posture without invoking external services:

  • sb privacy audit reports local data roots, permission/approval mode, provider key locations, web/connector/MCP settings, approval ledgers, pending governed actions, consent counts, and configured agent tool sets.
  • sb privacy audit --json is the machine-readable contract for UI and CI trust checks. --fail-on-risk and --fail-on-warn turn findings into a non-zero exit code.
  • sb explain-permissions explains approval-mode aliases and action classes for the effective runtime mode.
  • Agent Cockpit consumes the same trust audit and permission-explanation payloads through the local serve API so operators can inspect posture, findings, data roots, network surface, and pending governed work next to live agent sessions.
  • sb permissions --check <capability> remains the targeted policy evaluation command for a single capability plus argument payload.

Filesystem Boundaries

Filesystem access is controlled by runtime settings and policy/config layers. For public quickstarts, prefer repo-local writable directories rather than implicit home-directory state.

Network Boundaries

Networked capabilities are optional. The repo should remain useful without enabling them.

Public 0.3.0 Defaults

  • conservative default posture
  • explicit local state path
  • demo workflows that stay local
  • no silent fallthrough into side-effecting modes