Security Policies¶

Every tool invocation in SynthOrg passes through the SecOps security pipeline. This guide covers how to configure autonomy levels, approval workflows, custom policies, and output scanning. For the internal architecture of the security subsystem, see the Security reference.

Autonomy Levels¶

Autonomy levels control which actions require human approval. Set the company-wide level in config.autonomy.level, with optional per-agent overrides:

config:
  autonomy:
    level: semi

agents:
  - role: "Junior Developer"
    autonomy_level: supervised  # more restrictive than company default
  - role: "CEO"
    autonomy_level: full        # less restrictive than company default

Tool Access Levels¶

Tool access categories map to the ToolAccessLevel an agent's identity carries:

Levels form a hierarchy where each includes all categories from lower levels.

Security Configuration¶

The security section controls the SecOps rule engine, output scanning, and audit logging:

security:
  enabled: true
  audit_enabled: true
  post_tool_scanning_enabled: true
  output_scan_policy_type: autonomy_tiered
  hard_deny_action_types:
    - "deploy:production"
    - "db:admin"
    - "org:fire"
  auto_approve_action_types:
    - "code:read"
    - "docs:write"

Security Fields¶

Rule Engine¶

The rule engine runs synchronous checks against every tool invocation:

security:
  rule_engine:
    credential_patterns_enabled: true
    data_leak_detection_enabled: true
    destructive_op_detection_enabled: true
    mcp_destructive_op_detection_enabled: true
    path_traversal_detection_enabled: true
    max_argument_length: 100000
    custom_allow_bypasses_detectors: false

Built-in Detectors¶

Each detector defaults to on and can be independently disabled. The policy validator runs ahead of all of them and is not optional.

Custom Security Policies¶

Define custom rules to allow, deny, or escalate specific action types:

security:
  custom_policies:
    - name: "block-external-comms"
      description: "Prevent agents from sending external communications"
      action_types:
        - "comms:external"
      verdict: deny
      risk_level: high
      enabled: true
    - name: "escalate-deploys"
      description: "Escalate staging deployments for review"
      action_types:
        - "deploy:staging"
      verdict: escalate
      risk_level: medium

Policy Rule Fields¶

Action Types¶

Action types follow a category:action format. The built-in taxonomy is ActionType in src/synthorg/security/autonomy/enums.py:

LLM Security Fallback¶

For actions that the rule engine cannot classify with high confidence, an LLM can provide cross-validation. Reaching for a different provider family than the judged agent is the point of the mechanism: a jailbreak that works on one family should not also carry its reviewer.

That is now the operator's choice to make and the system's to report on, not something it arranges. Nothing auto-selects a cross-family model, because auto-selecting one means picking a connection nobody chose. The evaluator dispatches on security.llm_evaluator_model, an explicit (provider, model) pair, and when that pair shares the judged agent's vendor family the evaluation logs security.llm_eval.same_family at WARNING on every call. Leaving the pair unset leaves the evaluation off.

security:
  llm_fallback:
    enabled: true
    timeout_seconds: 10.0
    max_input_tokens: 2000
    on_error: escalate
    reason_visibility: generic
    argument_truncation: per_value

Output Scanning¶

After tool execution, the output scanner checks for leaked secrets and PII:

security:
  output_scan_policy_type: autonomy_tiered

Autonomy & Permissions (Runtime Operations)¶

This section covers runtime operations on the autonomy and tool-permission surface: promoting an agent, setting a department-level or per-initiative override, granting (or revoking) tool categories per-agent, and querying the audit trail.

Promote or demote an agent's autonomy¶

Human-only, on a dedicated endpoint guarded by require_ceo_or_manager. The request body carries a mandatory reason (at least three non-whitespace characters), which lands on the audit trail and, where the configured change strategy requires one, on the approval item the request opens rather than applying at once.

curl -X POST http://localhost:3001/api/v1/agents/${AGENT_ID}/autonomy \
  -H "Content-Type: application/json" \
  -H "Cookie: ${SESSION}" \
  -d '{"level": "semi", "reason": "Handing routine deploys back after a clean fortnight"}'

Valid levels: full, semi, supervised, locked. GET on the same path reads the effective level back. The path parameter is the agent's stable id, not its name.

PATCH /api/v1/agents/{agent_id} also accepts an autonomy_level, but that edits the org configuration rather than performing a runtime autonomy change, and it takes no reason.

Nothing demotes an agent automatically. You set the level and you are the only one who changes it, in either direction. The situations that might have triggered an automatic demotion already have their own controls: a run that reaches its cost ceiling parks itself and waits for you, and an action the security gate refuses is refused at the gate.

Set a department-level override¶

Resolution chain: per-agent > per-initiative > per-department > company default. To set a department-wide override:

curl -X PATCH http://localhost:3001/api/v1/departments/${DEPT_NAME} \
  -H "Content-Type: application/json" \
  -H "Cookie: ${SESSION}" \
  -d '{"autonomy_level": "supervised"}'

Clear with {"autonomy_level": null} to remove the department override. Resolution then falls to the company default, unless a more-specific per-initiative or per-agent override still applies.

Set a project's autonomy mode¶

Scopes an oversight mode to one initiative, resolved below a per-agent override and above the department/company default:

curl -X PATCH http://localhost:3001/api/v1/projects/${PROJECT_ID}/autonomy-mode \
  -H "Content-Type: application/json" \
  -H "Cookie: ${SESSION}" \
  -d '{"mode": "supervised"}'

Clear with {"mode": null} to inherit the department/company default. Setting full (gate-off pass-through) disables the per-action gate for the initiative's agents and is a CEO-only deliberate opt-in, so it requires {"mode": "full", "confirm": true} and is audited at WARNING. The write is version-guarded; pass expected_version to have a concurrent edit surface a 409 instead of clobbering.

Tool permission management¶

Per-agent tool permissions are declared on the identity, in the company configuration, and applied at bootstrap. There is no REST or MCP write surface for them: PATCH /api/v1/agents/{agent_id} forbids unknown fields and carries no tools key, so a request shaped like one is rejected rather than silently ignored.

agents:
  - role: "Junior Developer"
    tools:
      access_level: standard
      allowed: ["file_system", "git", "web"]
      denied: ["deployment"]
      denied_categories: ["deploy"]
      mcp_capabilities: ["tasks:read"]

denied_categories exists because a name list goes stale the moment a tool joins the category: an identity that must not reach a whole class of tool says so by category and stays correct as the category grows.

Resolution runs in order and stops at the first match: a name in denied is denied, then a name in allowed is allowed, then a custom access level denies everything it did not name, then category gating decides (which is where denied_categories applies), and anything unmatched is denied. Because the name lists are consulted before category gating, one entry in allowed readmits a single tool from an otherwise withheld category. Name matching is case-insensitive.

Audit log queries¶

since and until take ISO 8601 timestamps, not Unix epochs, and verdict is lowercase.

# The last day of security evaluations
curl "http://localhost:3001/api/v1/security/audit?since=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)" \
  -H "Cookie: ${SESSION}" | jq

# Filter by agent + action type
curl "http://localhost:3001/api/v1/security/audit?agent_id=${AGENT_ID}&action_type=code:create" \
  -H "Cookie: ${SESSION}" | jq

# Filter by verdict
curl "http://localhost:3001/api/v1/security/audit?verdict=deny" \
  -H "Cookie: ${SESSION}" | jq '.data[] | {agent_id, action_type, tool_name, reason, timestamp}'

Supported filters, all AND-combined, results newest-first: agent_id, tool_name, action_type (which must match category:action), verdict (allow, deny, escalate, output_scan), since, and until. The response is cursor-paginated via cursor and limit. Two further filters, jsonb_contains and jsonb_key_exists, run containment and key-existence queries against the matched_rules column and need a PostgreSQL backend; on SQLite they answer 422.

See Also¶

• Company Configuration: full configuration reference
• Security: security architecture reference
• Design: Security & Approval: security design specification