diff --git a/docs/concepts/enforcement.md b/docs/concepts/enforcement.md index a2a3464..e1934a3 100644 --- a/docs/concepts/enforcement.md +++ b/docs/concepts/enforcement.md @@ -135,3 +135,13 @@ Server-Timing: capiscio-auth;dur=0.618;desc="CapiscIO Verification" | ✅ Enforce payload integrity (SHA-256 body hash) | ❌ Manage a central registry (coming soon) | | ✅ Block replay attacks (timestamp validation) | ❌ Replace your IAM/SSO (human auth) | | ✅ Work with keys you provision | ❌ Auto-discover external agent keys (coming soon) | + +## Policy-Driven Enforcement + +Beyond identity verification, CapiscIO supports **YAML-based policy configurations** that define trust requirements, access rules, and rate limits. Policies are scoped at three levels: + +- **Organization**: Baseline rules for all agents +- **Group**: Rules for named collections of agents +- **Agent**: Per-agent overrides for fine-grained control + +See [Policy Scoping](policy-scoping.md) for the full scoping model, or [Configure Agent Policy](../how-to/configure-agent-policy.md) for a practical walkthrough. diff --git a/docs/concepts/policy-scoping.md b/docs/concepts/policy-scoping.md new file mode 100644 index 0000000..a6f6c1f --- /dev/null +++ b/docs/concepts/policy-scoping.md @@ -0,0 +1,118 @@ +--- +title: Policy Scoping +description: How CapiscIO's three-level policy scoping model (org → group → agent) enables granular trust and access control. +--- + +# Policy Scoping + +CapiscIO uses a **three-level scoping model** for policy configuration, providing flexible control over agent trust and access at every level of your organization. + +## Scope Levels + +``` +┌─────────────────────────────────────────┐ +│ Org Policy │ Baseline for all agents +│ min_trust_level: DV │ +│ denied_dids: [did:web:blocked.ex] │ +├─────────────┬───────────────────────────┤ +│ Group: PII │ Group: Public │ Named agent collections +│ min_trust: │ min_trust: "" │ +│ OV │ │ +├──────┬──────┼───────────────────────────┤ +│ Agent│Override │ Per-agent overrides +│ EV │ │ +└──────┴──────┴───────────────────────────┘ +``` + +### 1. Organization Scope (Baseline) + +The **org-level policy** is the baseline that applies to every agent in your organization. It defines the minimum trust requirements, default access rules, and rate limits. + +```yaml +# capiscio-policy.yaml (org scope) +version: "1" +min_trust_level: "DV" +denied_dids: + - "did:web:known-bad-actor.example.com" +rate_limits: + - did: "did:web:high-volume.example.com" + rpm: 100 +``` + +### 2. Group Scope (Named Collections) + +**Policy groups** allow you to apply rules to named collections of agents. For example, you might create a "PII Handlers" group with stricter trust requirements, or a "Public APIs" group with more permissive settings. + +Groups have a **precedence** value (lower = higher priority) that determines which group policy takes effect when an agent belongs to multiple groups. + +```yaml +# Group: pii-handlers (precedence: 10) +version: "1" +min_trust_level: "OV" +allowed_dids: + - "did:web:trusted-processor.example.com" +``` + +### 3. Agent Scope (Per-Agent Overrides) + +**Agent-level policies** provide the finest granularity. They override both org and group policies for a specific agent. Use these for agents with unique requirements. + +```yaml +# Agent: critical-payment-processor +version: "1" +min_trust_level: "EV" +operations: + - pattern: "payment.*" + min_trust_level: "EV" + allowed_dids: + - "did:web:payment-gateway.example.com" +``` + +## Resolution Algorithm + +When evaluating a policy decision, CapiscIO resolves the **effective policy** for each agent by merging policies in order: + +1. Start with the **org policy** (baseline) +2. Apply **group policies** in precedence order (lowest precedence number first) +3. Apply **agent-specific overrides** (highest priority) + +The resolution is **deterministic**: given the same set of active policies, the resolved result is always identical. This is critical for audit and debugging. + +### Override Behavior + +- **`min_trust_level`**: Narrower scope wins (agent > group > org) +- **`allowed_dids`**: Intersection (more specific scope restricts further) +- **`denied_dids`**: Union (denied at any scope = denied everywhere) +- **`rate_limits`**: Most specific scope wins per DID +- **`operations`** and **`mcp_tools`**: Most specific scope wins per pattern/tool name + +## Visibility and Auditability + +Every policy resolution produces an **attribution trail** showing which scope contributed which rule. This is accessible via: + +- **Resolved Policy endpoint**: `GET /v1/orgs/{orgId}/policy/agents/{agentId}/resolved` +- **Lineage endpoint**: `GET /v1/orgs/{orgId}/policy/agents/{agentId}/lineage` +- **Policy Context** (SDK): `capiscio policy context` + +The resolved endpoint returns the effective policy for a specific agent. The lineage endpoint returns all policy documents that contributed to the resolution, in precedence order. + +## Trust Levels + +CapiscIO defines six trust levels, each representing increasing assurance about an agent's identity: + +| Level | Name | Meaning | +|-------|------|---------| +| (empty) | None | No trust requirement | +| `SS` | Self-Signed | Agent has a self-signed key | +| `REG` | Registered | Agent is registered in the registry | +| `DV` | Domain Validated | Agent's domain ownership is verified | +| `OV` | Organization Validated | Agent's organization is verified | +| `EV` | Extended Validation | Agent has undergone extended validation | + +Trust levels are hierarchical: `EV > OV > DV > REG > SS > (none)`. + +## Next Steps + +- [Configure Agent Policy](../how-to/configure-agent-policy.md) — YAML config walkthrough +- [Policy API Reference](../reference/policy-api.md) — Phase-one API endpoints +- [CLI Reference](../reference/cli/index.md) — `capiscio policy` commands diff --git a/docs/how-to/configure-agent-policy.md b/docs/how-to/configure-agent-policy.md new file mode 100644 index 0000000..8328323 --- /dev/null +++ b/docs/how-to/configure-agent-policy.md @@ -0,0 +1,221 @@ +--- +title: Configure Agent Policy +description: How to write and deploy YAML-based policy configurations for your CapiscIO agents. +--- + +# Configure Agent Policy + +This guide walks you through writing, validating, and deploying YAML policy configurations. Policy configs define trust requirements, access rules, and rate limits for your agents. + +## Quick Start + +### 1. Create a Policy Config File + +Create a file named `capiscio-policy.yaml` in your project root: + +```yaml +version: "1" +min_trust_level: "DV" +denied_dids: + - "did:web:known-bad-actor.example.com" +``` + +### 2. Validate Locally + +```bash +capiscio policy validate -f capiscio-policy.yaml +``` + +### 3. Deploy to Your Organization + +Use the dashboard UI or the [Policy API](../reference/policy-api.md) to create and approve a policy proposal: + +```bash +# View current policy context +capiscio policy context --registry https://api.capisc.io --api-key $CAPISCIO_API_KEY +``` + +## YAML Schema + +### Version + +Every policy config must specify `version: "1"`. This is the current and only supported version. + +```yaml +version: "1" +``` + +### Minimum Trust Level + +Set a baseline trust requirement for all incoming agent requests: + +```yaml +min_trust_level: "DV" # Require domain validation or higher +``` + +Valid values: `""` (none), `SS`, `REG`, `DV`, `OV`, `EV` + +### DID Access Lists + +Control which agents can interact with your agents by DID: + +```yaml +# Only these agents may call your agents +allowed_dids: + - "did:web:partner-a.example.com" + - "did:web:partner-b.example.com" + +# These agents are always blocked +denied_dids: + - "did:web:known-bad-actor.example.com" +``` + +!!! warning "Mutual Exclusivity" + A DID cannot appear in both `allowed_dids` and `denied_dids`. The validator will reject such configurations. + +### Rate Limits + +Define per-DID rate limits (requests per minute): + +```yaml +rate_limits: + - did: "did:web:high-volume-caller.example.com" + rpm: 100 + - did: "did:web:low-priority.example.com" + rpm: 10 +``` + +Rate limits generate **obligations** in policy decisions — the enforcement point is responsible for applying them. + +### Operation-Scoped Rules + +Apply different trust/access rules to specific operations: + +```yaml +operations: + - pattern: "payment.*" + min_trust_level: "EV" + allowed_dids: + - "did:web:payment-gateway.example.com" + - pattern: "read.*" + min_trust_level: "" # No trust required for reads +``` + +Operations are matched against `input.action.operation` in policy evaluation. + +### MCP Tool-Scoped Rules + +Apply rules to specific MCP tools exposed by your agent: + +```yaml +mcp_tools: + - tool: "database_query" + min_trust_level: "OV" + denied_dids: + - "did:web:untrusted.example.com" + - tool: "file_read" + min_trust_level: "DV" +``` + +MCP tool rules are matched against `input.action.mcp_tool` in policy evaluation. + +## Complete Example + +```yaml +version: "1" +min_trust_level: "DV" + +allowed_dids: + - "did:web:trusted-partner.example.com" + - "did:web:internal-service.example.com" + +denied_dids: + - "did:web:blocked-agent.example.com" + +rate_limits: + - did: "did:web:trusted-partner.example.com" + rpm: 1000 + - did: "did:web:internal-service.example.com" + rpm: 500 + +operations: + - pattern: "payment.*" + min_trust_level: "EV" + allowed_dids: + - "did:web:payment-processor.example.com" + - pattern: "admin.*" + min_trust_level: "OV" + +mcp_tools: + - tool: "database_query" + min_trust_level: "OV" + - tool: "send_email" + min_trust_level: "EV" + allowed_dids: + - "did:web:notification-service.example.com" +``` + +## Validation + +### CLI Validation + +Validate your policy config before deploying: + +```bash +# Default file (capiscio-policy.yaml) +capiscio policy validate + +# Custom file +capiscio policy validate -f my-policy.yaml + +# JSON output for CI integration +capiscio policy validate -f my-policy.yaml --json +``` + +Exit code `0` means valid; non-zero means validation errors. + +### Validation Rules + +The validator checks: + +- **Version**: Must be `"1"` +- **Trust levels**: Must be one of `""`, `SS`, `REG`, `DV`, `OV`, `EV` +- **DID format**: All DIDs must start with `did:` +- **No duplicates**: A DID cannot appear twice in the same list +- **No cross-listing**: A DID cannot be in both `allowed_dids` and `denied_dids` +- **Rate limits**: RPM must be positive +- **Operations**: Pattern must not be empty +- **MCP tools**: Tool name must not be empty + +## Policy Lifecycle + +### 1. Create a Proposal + +Policies go through a proposal workflow: + +``` +Create Proposal → Review → Approve → Active + ↘ Reject (with reason) +``` + +### 2. Approval Activates Policy + +When a proposal is approved, it becomes the active policy. The previously active policy is marked as superseded. + +### 3. Bundle Rebuild + +After activation, the policy bundle is automatically rebuilt. Agents polling the bundle endpoint will pick up the new policy on their next refresh cycle. + +### 4. Enforcement + +Policy enforcement follows the [enforcement mode](../concepts/enforcement.md) configured for your deployment: + +- **EM-OBSERVE**: Violations logged but allowed (default) +- **EM-GUARD**: Violations blocked, PDP-unavailable allowed with warning +- **EM-STRICT**: All violations blocked, including PDP unavailability + +## Next Steps + +- [Policy Scoping](../concepts/policy-scoping.md) — Org/group/agent scoping model +- [Policy API Reference](../reference/policy-api.md) — REST API for policy management +- [CLI Reference](../reference/cli/index.md) — `capiscio policy` commands diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 3462dad..f02e3f9 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -63,6 +63,8 @@ The `capiscio` CLI provides commands for validating Agent Cards, managing crypto | [`badge request`](#badge-request) | Request a badge from CA via PoP protocol (RFC-003) | | [`badge dv`](#badge-dv) | Domain Validation commands (create, status, finalize) | | [`badge keep`](#badge-keep) | Daemon to auto-renew badges | +| [`policy validate`](#policy-validate) | Validate a YAML policy config file | +| [`policy context`](#policy-context) | Fetch policy context from registry | | [`trust`](#trust) | Manage the local trust store | | [`gateway start`](#gateway-start) | Start the security gateway | | [`rpc`](#rpc) | Start the gRPC server for SDK integration | @@ -806,9 +808,123 @@ The pip distribution includes wrapper management commands: --- +## policy validate + +Validate a YAML policy configuration file locally. Checks syntax, schema compliance, and semantic rules without contacting the registry. + +### Usage + +```bash +capiscio policy validate [flags] +``` + +### Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `-f`, `--file` | `string` | `capiscio-policy.yaml` | Path to the YAML policy config file | +| `--json` | `bool` | `false` | Output results as JSON | + +### Examples + +```bash +# Validate default file (capiscio-policy.yaml) +capiscio policy validate + +# Validate a specific file +capiscio policy validate -f my-policy.yaml + +# JSON output for CI pipelines +capiscio policy validate -f policy.yaml --json +``` + +### Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Policy config is valid | +| `1` | Validation errors found | + +### Validation Rules + +The validator checks: + +- Version must be `"1"` +- Trust levels must be valid (`""`, `SS`, `REG`, `DV`, `OV`, `EV`) +- DIDs must start with `did:` +- No duplicate DIDs within lists +- No DIDs in both `allowed_dids` and `denied_dids` +- Rate limit RPM must be positive +- Operation patterns and MCP tool names must not be empty + +--- + +## policy context + +Fetch the policy context from the CapiscIO registry. Returns the org's agents, groups, active policies, and pending proposals in JSON format. + +### Usage + +```bash +capiscio policy context [flags] +``` + +### Flags + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--registry` | `string` | `https://api.capisc.io` | Registry server URL | +| `--api-key` | `string` | *(from env)* | API key for authentication | +| `-o`, `--output` | `string` | *(stdout)* | Write output to file | + +### Environment Variables + +| Variable | Description | +|----------|-------------| +| `CAPISCIO_API_KEY` | Default API key when `--api-key` is not provided | + +### Examples + +```bash +# Fetch context using environment variable +export CAPISCIO_API_KEY=your-api-key +capiscio policy context + +# Specify registry URL explicitly +capiscio policy context --registry https://api.capisc.io --api-key your-key + +# Save to file +capiscio policy context -o policy-context.json +``` + +### Output + +Returns the complete policy context as JSON: + +```json +{ + "org_id": "22222222-2222-2222-2222-222222222222", + "agents": [ + { + "id": "...", + "name": "my-agent", + "did": "did:web:my-agent.example.com", + "trust_level": "DV" + } + ], + "groups": [], + "active_policies": [], + "pending_proposals": [] +} +``` + +--- + ## See Also - [Go API Reference](../go-api.md) - Programmatic usage of capiscio-core - [Getting Started: Validate Your First Agent](../../getting-started/validate/1-intro.md) - [Configuration Reference](../configuration.md) - [Agent Card Schema](../agent-card-schema.md) +- [Policy Config YAML Reference](../policy-config-yaml.md) - Full YAML schema +- [Policy API Reference](../policy-api.md) - REST API endpoints diff --git a/docs/reference/policy-api.md b/docs/reference/policy-api.md new file mode 100644 index 0000000..7ba3997 --- /dev/null +++ b/docs/reference/policy-api.md @@ -0,0 +1,277 @@ +--- +title: Policy API Reference +description: REST API reference for the CapiscIO policy management endpoints. +--- + +# Policy API Reference + +The policy management API provides endpoints for creating, approving, and querying YAML-based policy configurations. All endpoints are scoped to an organization. + +## Authentication + +Policy management endpoints require **user authentication** (via Clerk or test mode headers) and **organization membership**. Write operations (create, approve, reject) require the **admin** role. + +The SDK endpoint (`/v1/sdk/policy-context`) uses **registry key** authentication (`X-Capiscio-Registry-Key` header). + +## Base URL + +All policy management endpoints are under: + +``` +/v1/orgs/{orgId}/policy +``` + +--- + +## Read Endpoints + +These endpoints are accessible to any organization member. + +### Get Active Org Policy + +Returns the currently active org-level policy document. + +``` +GET /v1/orgs/{orgId}/policy/org +``` + +**Response** `200 OK`: + +```json +{ + "id": "550e8400-e29b-41d4-a716-446655440000", + "org_id": "22222222-2222-2222-2222-222222222222", + "scope_type": "org", + "scope_id": "22222222-2222-2222-2222-222222222222", + "state": "active", + "version": 3, + "yaml_content": "version: \"1\"\nmin_trust_level: \"DV\"\n", + "schema_version": "1", + "content_hash": "a1b2c3d4...", + "created_by_user_id": "...", + "created_by_type": "human", + "approved_by_user_id": "...", + "created_at": "2026-03-22T10:00:00Z", + "updated_at": "2026-03-22T10:05:00Z" +} +``` + +**Response** `404 Not Found`: No active org policy exists. + +### Get Org Policy History + +Returns all policy documents (active, superseded, rejected) for the org scope. + +``` +GET /v1/orgs/{orgId}/policy/org/history +``` + +**Response** `200 OK`: Array of policy document objects. + +### List Proposals + +Returns all pending proposal documents for the organization (across all scopes). + +``` +GET /v1/orgs/{orgId}/policy/proposals +``` + +**Response** `200 OK`: Array of policy document objects with `state: "proposal"`. + +### Get Resolved Policy for Agent + +Returns the effective (merged) policy for a specific agent, computed by merging org → group → agent policies. + +``` +GET /v1/orgs/{orgId}/policy/agents/{agentId}/resolved +``` + +**Response** `200 OK`: Resolved policy map. + +### Get Policy Lineage for Agent + +Returns all active policy documents that contribute to the agent's resolved policy, in precedence order. + +``` +GET /v1/orgs/{orgId}/policy/agents/{agentId}/lineage +``` + +**Response** `200 OK`: Array of contributing policy documents with scope attribution. + +--- + +## Write Endpoints + +These endpoints require the **admin** role within the organization. + +### Create Org Policy + +Creates a new policy proposal for the org scope. + +``` +POST /v1/orgs/{orgId}/policy/org +``` + +**Request Body**: + +```json +{ + "yaml_content": "version: \"1\"\nmin_trust_level: \"DV\"\n" +} +``` + +**Response** `201 Created`: The created proposal document. + +**Errors**: + +- `400 Bad Request`: Invalid YAML or validation failure +- `400 Bad Request`: Empty `yaml_content` + +### Update Org Policy + +Creates a new proposal version (same as Create). The version number auto-increments from the current active policy. + +``` +PUT /v1/orgs/{orgId}/policy/org +``` + +Same request/response format as Create. + +### Approve Proposal + +Approves a proposal document, activating it. The previously active document (if any) is superseded. + +``` +POST /v1/orgs/{orgId}/policy/proposals/{proposalId}/approve +``` + +**Response** `200 OK`: The now-active document. + +**Errors**: + +- `404 Not Found`: Proposal not found +- `400 Bad Request`: Document is not in proposal state + +### Reject Proposal + +Rejects a proposal document with a reason. + +``` +POST /v1/orgs/{orgId}/policy/proposals/{proposalId}/reject +``` + +**Request Body**: + +```json +{ + "reason": "This policy is too permissive for production." +} +``` + +**Response** `200 OK`: The rejected document. + +**Errors**: + +- `400 Bad Request`: Reason is required + +### Simulate Policy Decision + +Runs a policy evaluation for a specific agent without side effects. Useful for testing policy changes before deploying. + +``` +POST /v1/orgs/{orgId}/policy/agents/{agentId}/simulate +``` + +**Request Body**: + +```json +{ + "subject": { + "did": "did:web:caller.example.com", + "trust_level": "DV" + }, + "action": { + "operation": "agent.invoke" + }, + "resource": { + "identifier": "target-agent-id" + }, + "context": {}, + "environment": {} +} +``` + +**Response** `200 OK`: + +```json +{ + "decision": "ALLOW", + "decision_id": "sim-abc123", + "obligations": [], + "reason": "Policy evaluation passed", + "ttl": 300 +} +``` + +**Errors**: + +- `400 Bad Request`: PDP not configured or agent not found + +--- + +## SDK Endpoint + +### Get Policy Context + +Aggregate endpoint for SDK/CLI consumption. Returns the complete policy context for the organization. + +``` +GET /v1/sdk/policy-context +``` + +**Authentication**: Registry key (`X-Capiscio-Registry-Key` header). + +**Response** `200 OK`: + +```json +{ + "org_id": "22222222-2222-2222-2222-222222222222", + "agents": [ + { + "id": "...", + "name": "my-agent", + "did": "did:web:my-agent.example.com", + "trust_level": "DV", + "group_ids": ["group-1-id"] + } + ], + "groups": [ + { + "id": "group-1-id", + "name": "production", + "precedence": 10 + } + ], + "active_policies": [ + { + "id": "...", + "scope_type": "org", + "version": 3, + "yaml_content": "..." + } + ], + "pending_proposals": [] +} +``` + +--- + +## Policy Document States + +| State | Description | +|-------|-------------| +| `proposal` | Awaiting review and approval | +| `active` | Currently enforced policy | +| `superseded` | Replaced by a newer active policy | +| `rejected` | Rejected during review | +| `archived` | Manually archived | diff --git a/docs/reference/policy-config-yaml.md b/docs/reference/policy-config-yaml.md new file mode 100644 index 0000000..2bcd01a --- /dev/null +++ b/docs/reference/policy-config-yaml.md @@ -0,0 +1,153 @@ +--- +title: Policy Config YAML Reference +description: Complete reference for the capiscio-policy.yaml schema. +--- + +# Policy Config YAML Reference + +This page documents the complete YAML schema for CapiscIO policy configuration files. + +## Schema Version + +Current schema version: **1** + +## Top-Level Fields + +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `version` | string | **Yes** | — | Must be `"1"` | +| `min_trust_level` | string | No | `""` | Minimum trust level for all requests | +| `allowed_dids` | string[] | No | `[]` | Allowlist of agent DIDs | +| `denied_dids` | string[] | No | `[]` | Denylist of agent DIDs | +| `rate_limits` | RateLimitRule[] | No | `[]` | Per-DID rate limits | +| `operations` | OperationRule[] | No | `[]` | Operation-scoped rules | +| `mcp_tools` | MCPToolRule[] | No | `[]` | MCP tool-scoped rules | + +## Trust Levels + +| Value | Name | Description | +|-------|------|-------------| +| `""` | None | No trust requirement | +| `SS` | Self-Signed | Agent has a self-signed key | +| `REG` | Registered | Agent is registered in the CapiscIO registry | +| `DV` | Domain Validated | Agent's domain ownership is verified | +| `OV` | Organization Validated | Agent's organization is verified | +| `EV` | Extended Validation | Agent has undergone extended validation | + +Trust levels are ordered: `EV > OV > DV > REG > SS > ""` (none). + +## DID Format + +All DID values must conform to the DID syntax: they must start with `did:`. + +Examples: + +- `did:web:agent.example.com` +- `did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK` +- `did:web:registry.capisc.io:agents:my-agent` + +## RateLimitRule + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `did` | string | **Yes** | Agent DID to rate limit (must start with `did:`) | +| `rpm` | integer | **Yes** | Requests per minute (must be > 0) | + +```yaml +rate_limits: + - did: "did:web:caller.example.com" + rpm: 100 +``` + +Rate limits generate **obligations** in policy decisions. The PEP (Policy Enforcement Point) is responsible for tracking and enforcing rate limits. + +## OperationRule + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `pattern` | string | **Yes** | Operation pattern to match (must not be empty) | +| `min_trust_level` | string | No | Trust level override for this operation | +| `allowed_dids` | string[] | No | Allowlist specific to this operation | +| `denied_dids` | string[] | No | Denylist specific to this operation | + +```yaml +operations: + - pattern: "payment.*" + min_trust_level: "EV" + allowed_dids: + - "did:web:payment-processor.example.com" +``` + +The `pattern` field is matched against `input.action.operation` during policy evaluation. + +## MCPToolRule + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `tool` | string | **Yes** | MCP tool name to match (must not be empty) | +| `min_trust_level` | string | No | Trust level override for this tool | +| `allowed_dids` | string[] | No | Allowlist specific to this tool | +| `denied_dids` | string[] | No | Denylist specific to this tool | + +```yaml +mcp_tools: + - tool: "database_query" + min_trust_level: "OV" + - tool: "send_email" + min_trust_level: "EV" + allowed_dids: + - "did:web:notification-service.example.com" +``` + +The `tool` field is matched against `input.action.mcp_tool` during policy evaluation. + +## Validation Rules + +The following rules are enforced during parsing and validation: + +1. **`version`** must be exactly `"1"` +2. **Trust levels** must be one of: `""`, `SS`, `REG`, `DV`, `OV`, `EV` +3. **DID format**: All DID strings must start with `did:` +4. **No duplicate DIDs** within the same list +5. **No cross-listed DIDs**: A DID cannot appear in both `allowed_dids` and `denied_dids` +6. **Rate limit RPM** must be a positive integer +7. **Operation patterns** must not be empty strings +8. **MCP tool names** must not be empty strings + +## Minimal Valid Config + +```yaml +version: "1" +min_trust_level: "" +``` + +## Full Example + +```yaml +version: "1" +min_trust_level: "DV" + +allowed_dids: + - "did:web:trusted-partner.example.com" + +denied_dids: + - "did:web:blocked-agent.example.com" + +rate_limits: + - did: "did:web:trusted-partner.example.com" + rpm: 1000 + +operations: + - pattern: "payment.*" + min_trust_level: "EV" + allowed_dids: + - "did:web:payment-processor.example.com" + - pattern: "admin.*" + min_trust_level: "OV" + +mcp_tools: + - tool: "database_query" + min_trust_level: "OV" + - tool: "send_email" + min_trust_level: "EV" +``` diff --git a/mkdocs.yml b/mkdocs.yml index c0d7b3c..87a682c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -200,6 +200,7 @@ nav: - concepts/validation.md - concepts/scoring.md - Enforcement: concepts/enforcement.md + - Policy Scoping: concepts/policy-scoping.md - MCP Security: - Overview: concepts/mcp-security.md @@ -233,6 +234,8 @@ nav: - Flask: how-to/integrations/flask.md - Express: how-to/integrations/express.md - LangChain: how-to/integrations/langchain.md + - Policy: + - Configure Agent Policy: how-to/configure-agent-policy.md - CI/CD: - Pre-commit Hook: how-to/cicd/pre-commit.md - GitLab CI: how-to/cicd/gitlab-ci.md @@ -259,6 +262,9 @@ nav: - API Reference: reference/server/api.md - Deployment: reference/server/deployment.md - Badge CA: reference/server/badge-ca.md + - Policy: + - Policy Config YAML: reference/policy-config-yaml.md + - Policy API: reference/policy-api.md - Configuration: reference/configuration.md - Agent Card Schema: reference/agent-card-schema.md - Installation: