> This page is for Agent Handler.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Violations and alerts

> Tour of the Agent Handler Alerts dashboard: timeseries, breakdowns, per-violation drilldowns, and CSV export for compliance.

Every time a security rule matches - whether the action is allow, redact, or block - Agent Handler records a violation. The [Alerts dashboard](https://ah.merge.dev/security/alerts) is where you investigate what's happening, find false positives, and produce evidence for compliance reviews.

This page tours the dashboard. For configuring rules in the first place, see [Standard Entity Rules](/merge-agent-handler/secure/standard-entity-rules) and [Custom Regex Rules](/merge-agent-handler/secure/custom-regex-rules).

## Three views

### Timeseries

A graph of violations over time, filterable by date range and entity. Useful for spotting spikes, verifying that a rule change reduced noise, and pulling a 30-day chart for a security review.

### Breakdown by entity

A table showing total violations per entity type (or per custom rule), broken down by action (allowed / redacted / blocked). Use it to see which rules are doing the most work, spot rules firing constantly (usually a false positive), and size a rule's impact before turning enforcement on - set it to allow, watch for a week, then decide whether to redact or block.

### Per-violation table

Every individual violation, one row each. Each row shows the rule that fired, the matched entity (post-redaction), a link to the [tool call detail](/merge-agent-handler/observe/tool-call-logs), the Registered User, the Tool Pack, the action, and the timestamp. Click a row to open the full tool-call detail with the violation highlighted.

## Filtering

The filter bar across the top of the dashboard supports:

* **Rule** - narrow to one rule.
* **Entity** - narrow to one entity type (across all rules that detect it).
* **Action** - show only allowed, redacted, or blocked.
* **Tool Pack** - narrow to one pack.
* **Registered User** - narrow to one end user.
* **Date range.** Last 7 days by default; custom windows for retrospective audits.

Filters compose. "All blocked credit-card matches on the embedded support Tool Pack in the last 24 hours" is one combined query.

## The investigation flow

1. **Spot something on the timeseries** - a spike, an unexpected baseline.
2. **Drill into the breakdown** to see which rule is responsible.
3. **Click into the per-violation table** filtered to that rule.
4. **Open one violation row** to see the underlying tool call.
5. **Read the tool arguments and result** to understand whether the match was legitimate.
6. **Decide.** False positive? Tighten the rule. Real issue? Investigate the user or update the agent prompt.

Most spikes are explainable in two clicks. The view is built for that loop.

## Acting on findings

* **Rule too aggressive.** Raise the threshold, add negative context keywords (custom regex), or override on the specific Tool Pack where the data is legitimately allowed.
* **Rule too lenient.** Lower the threshold, broaden the pattern, or change the action from allow → redact or redact → block.
* **Agent misbehaving.** A spike isn't always a rule problem. If the model is producing tool calls that shouldn't exist (a prompt-injection symptom, for example), the fix is on the agent side - tighter prompts, [Tool Pack scoping](/merge-agent-handler/build/tools/tool-packs), or [Tool Description Overrides](/merge-agent-handler/build/tools/tool-description-overrides).

## Exporting for compliance

The per-violation table exports as CSV from the **Export** button. The export covers whatever filter you have applied - you can pull "all blocked PII matches in 2026-Q1" for an audit response without writing SQL.

The export includes:

* Violation ID
* Timestamp
* Rule and entity
* Action taken
* Tool call ID (for cross-reference)
* Registered User ID and `origin_user_id`
* Tool Pack ID
* Tool name

For automated forwarding (SIEM, data warehouse), pull the [Tool Call Logs](/merge-agent-handler/observe/tool-call-logs) from the log endpoints and filter for redacted or blocked calls. See [Stream logs to a SIEM](/merge-agent-handler/observe/stream-logs-to-a-siem). The log endpoints are an Enterprise feature.

## Retention

Violations are kept for your organization's [data retention](/merge-agent-handler/observe/audit-trail#data-retention) window. Past it, exported CSVs and the log endpoints (Enterprise) are the path to long-term storage.

## Next

Try a rule against sample input before turning it on for real traffic with the [Rule Tester](/merge-agent-handler/secure/rule-tester).