Enforcement modes
Every decision AgentShield makes is one of three: BLOCK (the action never runs), AUDIT (it runs and is flagged for review) or ALLOW (it runs). The enforcement mode decides whether BLOCK is honoured or downgraded.
| Mode | BLOCK becomes | Who sees it |
|---|---|---|
| enforce | BLOCK. The command or tool call is refused. | The developer sees the refusal and the reason. The audit log records the block. |
| audit-only | AUDIT. The action runs. | The developer sees nothing. The audit log records the event with a would-have-blocked badge and the original decision. |
Rolling out with audit-only
Audit-only is how every monitoring product earns trust: WAFs, EDR and static analysis all ship a monitor mode first. The recommended rollout:
- Set the organisation to audit-only in Settings (admins only).
- Install AgentShield across the team. Nothing changes for anyone.
- After one to two weeks, open the Audit Log and filter to would-have-blocked. Every row is a control proven to be watched, a signal about rule quality, or a false positive to fix.
- Switch to enforce. The rules that would have blocked now block.
Scope and precedence
The organisation toggle applies to every agent and every surface, both IDE hooks and the MCP proxy. Local configuration on a machine always wins:
CLI flag → ~/.agentshield/agentshield.yaml (mode: audit-only | enforce) → organisation setting → enforce
So an engineer can put their own machine into audit-only mode without the cloud, and an organisation cannot silently flip a machine whose owner has pinned the mode locally.
Exporting the evidence
The Audit Log's Export CSV includes timestamp, decision, original_decision, mode, rule_id, source, command, reason, hostname, which is the shape GRC tools such as Drata and Vanta ingest.