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

import ShieldAgent from '@shieldagent/sdk';

const client = new ShieldAgent();

// Create a custom template
const template = await client.policyTemplates.create({
  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)
await client.policyTemplates.apply(template.id);

Live Policy Updates

Policy changes take effect automatically — no restart or redeployment needed. When you create, update, or delete a policy in the dashboard or via the API, the change is picked up by the proxy within seconds. For time-sensitive changes (such as adding a new deny rule), you can force an immediate update from the dashboard or API.

Managing Policies in the Dashboard

The dashboard is the recommended way to create, review, and manage policies:

1. 1Go to Policies in the left sidebar to see the full rule list for your tenant.
2. 2Click New Policy to create a rule — set tool name, action, optional agent scope, and conditions.
3. 3Use the search and filter bar to find policies by tool name, action, or agent.
4. 4Click any policy row to edit or delete it. Changes hot-reload to the proxy automatically.
5. 5Go to Settings → Security to toggle shadow mode globally for the tenant.

SDK & Dashboard

All policy operations require authentication. See Authentication for details.

Policies

Policy Templates

Example — Create a policy

import ShieldAgent from '@shieldagent/sdk';

const client = new ShieldAgent();

await client.policies.create({
  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: