Policy Engine

How It Works

The policy engine runs inside the ShieldAgent proxy pipeline, evaluated after authentication and before the security scanner. Every tools/call request is matched against your tenant's rule set. Other MCP methods (tools/list, resources/read, etc.) pass through without policy checks.

Default: implicit deny. If no policy rule matches a given (agentId, toolName) request, the engine denies it. Tools without explicit allow rules are blocked by default — no configuration required to stay safe.

Policy Schema

Each policy binds a tool name to an action and optionally adds conditions that must all be satisfied for the rule to fire.

Actions

Scoping & Precedence

Agent-specific rules (non-null agentId) take priority over tenant-wide rules (agentId: null). Within the same specificity level, deny rules run before allow rules and conditional rules run before unconditional ones.

Condition Types

Conditions are optional predicates on a rule. When multiple conditions are present, all must match (AND logic). If any condition fails, the rule is skipped and evaluation continues to the next rule.

// Deny any bash call where the command contains "rm -rf"
{
  "toolName": "bash",
  "action": "deny",
  "conditions": [
    {
      "type": "param_contains",
      "param": "arguments.command",
      "value": "rm -rf"
    }
  ]
}

// Allow read_file only for paths under /app/data/
{
  "toolName": "read_file",
  "action": "allow",
  "conditions": [
    {
      "type": "param_matches",
      "param": "arguments.path",
      "pattern": "^\/app\/data\/"
    }
  ]
}

// Allow query_database only during business hours (09:00–17:00 UTC)
{
  "toolName": "query_database",
  "action": "allow",
  "conditions": [
    {
      "type": "time_window",
      "allowedHours": [9, 17]
    }
  ]
}

// Cap send_email to 10 calls per minute
{
  "toolName": "send_email",
  "action": "allow",
  "conditions": [
    {
      "type": "rate_limit",
      "maxPerMinute": 10
    }
  ]
}

Shadow Mode

Shadow mode lets you roll out new policies safely. When enabled, the engine evaluates each request as normal but does not block it even if a deny rule matches. The decision is logged to the audit trail with outcome: 'shadow' and a shadowDeny: true flag so you can review impact before enforcing.

Three-Level Cascade

Shadow mode is resolved from most specific to least specific — the first non-null value wins:

Policy Templates

Templates are pre-built rule sets that you can apply to a tenant in one API call. Applying a template creates one policy record per rule, scoped tenant-wide. ShieldAgent ships system templates for common security, compliance, and development scenarios; you can also create custom templates for organization-specific rule sets.

Creating and Applying a Custom Template

# Create a custom template
curl -s -X POST https://api.shieldagent.io/tenants/:tenantId/policy-templates \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Restrict destructive tools",
    "description": "Deny dangerous shell commands for production agents",
    "category": "security",
    "rules": [
      {
        "toolName": "bash",
        "action": "deny",
        "conditions": [{"type": "param_contains", "param": "arguments.command", "value": "rm -rf"}]
      },
      {
        "toolName": "bash",
        "action": "deny",
        "conditions": [{"type": "param_contains", "param": "arguments.command", "value": "DROP TABLE"}]
      }
    ]
  }'

# Apply a template (creates one policy per rule)
curl -s -X POST https://api.shieldagent.io/tenants/:tenantId/policy-templates/:templateId/apply \
  -H 'Authorization: Bearer <token>'

Hot-Reload Architecture

Policy changes take effect without restarting the proxy. The proxy maintains an in-memory compiled rule set per tenant and refreshes it automatically.

API Reference

All policy endpoints require a bearer token. See Authentication for details.

Policies

Policy Templates

Example — Create a policy

curl -s -X POST https://api.shieldagent.io/tenants/:tenantId/policies \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "toolName": "bash",
    "action": "deny",
    "agentId": null,
    "conditions": [
      {
        "type": "param_contains",
        "param": "arguments.command",
        "value": "rm -rf"
      }
    ]
  }'

Required permissions

Audit Trail

Every policy evaluation is appended to the immutable audit trail. Key fields on each event: