Shadow Mode
Observe, measure, and validate security controls without blocking agent traffic — the safe path to full enforcement.
What Is Shadow Mode?
Shadow mode is a non-blocking evaluation pass. When enabled, the ShieldAgent proxy evaluates every tool call through the full policy engine and security pipeline — but does not block the request even if a deny rule matches. The decision is logged to the audit trail with a shadowDeny: true flag so you can review the impact before committing to enforcement.
Default: shadow mode is on. New tenants and new agents start in shadow mode. This gives you visibility into what would be blocked before any agent traffic is disrupted.
Three-Level Cascade
Shadow mode is resolved from most specific to least specific — the first non-null value wins. This lets you enforce globally while keeping specific agents in observation mode, or vice versa.
| Level | Scope | How to configure |
|---|---|---|
| Tenant default | All agents in the tenant | Settings → Security → Shadow Mode toggle (or API) |
| Per-agent | All MCP server bindings for one agent | PATCH /tenants/:tenantId/agents/:agentId {"shadowMode": false} |
| Per-binding | One agent ↔ one MCP server connection | PATCH /tenants/:tenantId/agents/:agentId/mcp-bindings/:serverId {"shadowMode": false} |
Shadow Events in the Audit Trail
Every shadow deny produces a full audit event so you can quantify the impact before switching to enforcement. Key fields:
| Field | Value |
|---|---|
| outcome | "shadow" — the call was allowed but would have been denied under enforcement |
| shadowDeny | true — policy engine determined this should be blocked |
| matchedRuleId | UUID of the first deny rule that matched; null for implicit deny |
| reason | Human-readable explanation of which rule matched and why |
{
"id": "ae_...",
"agentId": "...",
"toolName": "bash",
"outcome": "shadow",
"shadowDeny": true,
"matchedRuleId": "pol_...",
"reason": "Rule 'deny bash rm -rf' matched on arguments.command",
"timestamp": "2026-04-24T09:15:00.000Z"
}Recommended Rollout
Shadow mode enables a safe, iterative path to full enforcement:
Start globally in shadow mode
The default. Deploy ShieldAgent and let all traffic flow through without blocking. Monitor the audit trail for shadow_deny events to understand what your agents are doing.
Author and test policies
Create deny rules via the dashboard or API. Because shadow mode is on, no traffic is disrupted. Use the audit trail to verify the rules match the intended tool calls.
Enforce per-agent as you validate
Once you are confident an agent's policies are correct, flip that agent to enforce mode: PATCH /agents/:id {"shadowMode": false}. Other agents remain in shadow mode.
Enforce globally when all agents are clean
Disable shadow mode at the tenant level in Settings → Security. Policy denials now block tool calls. Shadow mode can be re-enabled for specific agents at any time.
Monitoring Shadow Denies
Use the audit log to quantify impact before enforcing. Filter by outcome=shadow to see all shadow events, then group by matchedRuleId to see which rules fire most often.
# List shadow deny events for a tenant (last 24h)
curl -s 'https://api.shieldagent.io/tenants/:tenantId/audit-events?outcome=shadow&limit=100' \
-H 'Authorization: Bearer <token>'
# Check shadow mode status for an agent
curl -s 'https://api.shieldagent.io/tenants/:tenantId/agents/:agentId' \
-H 'Authorization: Bearer <token>' | jq '.shadowMode'