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
    path_traversal_detection_enabled: true
    max_argument_length: 100000
    custom_allow_bypasses_detectors: false

Built-in Detectors¶

Each detector can be independently enabled or disabled.

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. Built-in types include:

LLM Security Fallback¶

For actions that the rule engine cannot classify with high confidence, an LLM from a different provider family can provide cross-validation:

security:
  llm_fallback:
    enabled: true
    model: "example-medium-001"
    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. No agent (not even the CEO) can escalate privileges programmatically.

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

Valid values: full, semi, supervised, locked.

Automatic demotions happen on: sustained high error rate (one level down), budget exhausted (supervised), security incident (locked). Recovery from auto-downgrade is human-only.

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 managed via the agent's tools.allowed / tools.denied lists:

# Grant a category
curl -X PATCH http://localhost:3001/api/v1/agents/${AGENT_NAME} \
  -H "Content-Type: application/json" \
  -H "Cookie: ${SESSION}" \
  -d '{"tools": {"allowed": ["file_system", "git", "web"], "denied": ["deployment"]}}'

Resolution precedence: denied > allowed > access-level default > deny.

Audit log queries¶

# Last 24h of security evaluations
curl "http://localhost:3001/api/v1/security/audit?since=$(date -u -d '24 hours ago' +%s)" \
  -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: agent_id, tool_name, verdict (ALLOW, DENY, ESCALATE), action_type, since, until.

See Also¶

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