Skip to content

Permission policy YAML schema#

Operator-authored permission rules. Loaded at startup; augments the 4 other rule sources (RBAC, agent allowlist, feature flags, HITL gates).

Empty by default. Compliance profiles ship pre-baked bundles (config/permission_policies_hipaa.yaml, config/permission_policies_rbi.yaml).

Schema#

version: "1.0"
description: "Human-readable policy name"
rules:
  - id: string                         # unique identifier
    description: string                # what the rule does
    when:                              # conditions (all must match — AND)
      tool: string | [string]          # tool name(s) — glob ok
      agent: string | [string]         # agent name(s)
      role: viewer | operator | admin
      args_pattern: string             # regex against JSON-serialised args
      compliance_profile: string
      time_window:                     # optional — only active in window
        days: [monday, tuesday, ...]
        hours: "09-17"                 # ISO time range
    behaviour: allow | deny | ask
    reason: string                     # shown in denial log
    priority: integer                  # default: 0; higher wins within tier

Resolution#

The policy engine resolves in strict order: ALLOW > DENY > ASK > default-allow. Within each tier, higher priority wins.

Example — a role-specific rule:

rules:
  - id: P001
    description: "Only admins may deploy to production"
    when:
      tool: deploy_serving
      role: operator                   # if role is operator...
      args_pattern: '"env"\\s*:\\s*"prod"'  # ...and deploying to prod...
    behaviour: deny                    # ...deny
    reason: "Operator role cannot deploy to prod; admin required"
    priority: 100

Compliance-profile bundled policies#

permission_policies_hipaa.yaml#

version: "1.0"
description: "HIPAA controls — 45 CFR § 164.312"
rules:
  - id: HIPAA-001
    description: "No raw data export"
    when:
      tool: export_raw_data
    behaviour: deny
    reason: "HIPAA: raw PHI export requires separate de-identification workflow"

  - id: HIPAA-002
    description: "Block external web search from PHI-handling agents"
    when:
      tool: web_search
      agent: [data_cleaner, data_profiler, feature_engineer]
    behaviour: deny
    reason: "HIPAA: no external data egress from PHI-handling agents"

  - id: HIPAA-003
    description: "Require approval for model promotion to prod"
    when:
      tool: promote_challenger
      args_pattern: '"env"\\s*:\\s*"prod"'
    behaviour: ask
    reason: "HIPAA § 164.312(a)(1): deliberate access decision required"

permission_policies_rbi.yaml#

version: "1.0"
description: "RBI FREE-AI Sutras — 7-pillar AI governance"
rules:
  - id: RBI-001
    description: "Require fairness audit before deployment (Sutra 4)"
    when:
      tool: deploy_serving
    behaviour: ask
    reason: "RBI FREE-AI Sutra 4: fairness audit required before deployment; operator confirms via approval"

  - id: RBI-002
    description: "Explain-model tool mandatory before promotion (Sutra 7)"
    when:
      tool: promote_challenger
    behaviour: ask
    reason: "RBI FREE-AI Sutra 7: explainability artefact required before champion swap"

  - id: RBI-003
    description: "Model cards mandatory (Sutra 7)"
    when:
      tool: package_model
    behaviour: ask
    reason: "RBI FREE-AI Sutra 7: model card + SHAP required"

Custom + stacking#

Customer-specific policies stack on top of compliance profiles:

# config/permission_policies_acme_bank.yaml
version: "1.0"
description: "Acme Bank internal governance"
rules:
  - id: ACME-001
    description: "No deployments on weekends"
    when:
      tool: deploy_serving
      time_window:
        days: [saturday, sunday]
    behaviour: deny
    reason: "Acme internal: no weekend deployments"
    priority: 200                      # overrides any allow

Reference from pipeline config:

# config/pipelines/acme_fraud.yaml
name: acme_fraud
compliance_profile: rbi_free_ai
additional_policies:
  - permission_policies_acme_bank.yaml

Stricter rule wins (higher priority, or deny > ask > allow within the same priority).

Validating#

swarm config validate

Checks: - YAML parses - All tool, agent, role names exist - args_pattern compiles as a valid regex - No circular references

Audit trail#

Every rule evaluation is logged to run_events with kind: permission_decision — whether allow, deny, or ask. Query:

SELECT rule_source, COUNT(*) AS hits
FROM permission_denials
WHERE rule_source LIKE 'policy:%'
AND ts > date_trunc('month', now())
GROUP BY rule_source
ORDER BY hits DESC;

Shows which policy rules fired most. Tune priority + conditions accordingly.

Next#