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.
Shadow Mode Scope
Shadow mode can be configured at three levels, giving you fine-grained control over which parts of your fleet are observing versus enforcing. A more specific setting always takes priority over a broader one.
- Per-connection:Control shadow mode for a single agent-to-server connection.
- Per-agent:Control shadow mode for all connections of a specific agent.
- Tenant-wide:Set the default shadow mode for your entire tenant.
| Level | Scope | How to configure |
|---|---|---|
| Tenant default | All agents in the tenant | Dashboard: Settings → Security → Shadow Mode toggle. |
| Per-agent | All MCP server bindings for one agent | Dashboard: Agents → [agent] → Settings → Shadow Mode toggle. |
| Per-binding | One agent ↔ one MCP server connection | Dashboard: Agents → [agent] → MCP Servers → [server] → Shadow Mode toggle. |
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 in the dashboard: Agents → [agent] → Settings → Shadow Mode toggle off. Other agents remain in shadow mode.
Enforce globally when all agents are clean
Disable shadow mode at the tenant level: Dashboard: Settings → Security → Shadow Mode toggle off. 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)
const shadowEvents = await client.auditEvents.list({
outcome: 'shadow',
limit: 100,
});
// Check shadow mode status for an agent
const agent = await client.agents.get(agentId);
console.log(agent.shadowMode);