USER MANUAL · INSIGHTS

Audit Search

Search, filter, and export the immutable audit trail that records every governance event across your agent fleet.

/audit

Overview#

ClawButler maintains an immutable audit trail of every governance event — agent actions, approval decisions, configuration changes, kill switch activations, connector operations, and more. Every event is timestamped, attributed to an actor, and enriched with structured metadata so you can reconstruct exactly what happened and why.

The Audit Search page is your primary tool for compliance and incident investigation. Full-text search combined with multi-dimensional filters lets you pinpoint specific events in seconds. For formal compliance needs, the Evidence Pack generator (TCC Step 05) bundles related events into a verifiable package with cryptographic integrity, ready for auditors or regulatory review.

Prerequisites#

Prerequisites
  • An active ClawButler system with agents generating events (actions, approvals, config changes, etc.)
  • At least one connector synced so that governance events are being recorded

Expected Results#

Once your system is active and generating events, the Audit Search page provides:

  • -A searchable, paginated event log showing all governance events in reverse chronological order
  • -A filter panel with controls for date range, event type, actor, agent, and risk level
  • -An event detail panel with structured data, related events, and evidence links
  • -Export options for downloading audit data in CSV or JSON format

Web Operations#

Navigate to the Audit Search page from the sidebar under Insights.

Search & Filters

The top of the page provides a full-text search bar and a set of filter controls for narrowing results:

  • -Text search — Free-text search across event descriptions, actor names, and metadata fields
  • -Date range — Start and end date pickers to scope the time window
  • -Event type — Filter by category such as agent_action, approval, config_change, kill_switch, connector_sync, etc.
  • -Actor — Filter by the user or system principal that triggered the event
  • -Agent — Filter events related to a specific agent by name or ID

Event Detail

Click any event row to open the detail panel. It displays the full structured event data including timestamp, event type, actor, target agent, risk level, a human-readable summary, and the raw metadata payload. Related events (e.g., the approval that preceded an action) are linked for easy navigation.

Evidence Pack

For compliance and incident investigation, you can generate an Evidence Pack (TCC Step 05) from a set of filtered events. The pack bundles the selected events with their full metadata, related context, and a cryptographic integrity hash into a downloadable archive. This is designed for auditor handoff and regulatory evidence requirements.

Export

Use the export controls to download the current filtered result set as CSV or JSON. CSV is suitable for spreadsheet analysis; JSON preserves the full structured metadata for programmatic processing. Exports respect all active filters and the current date range.

CLI Operations#

Search audit events with optional type, date, and agent filters

Terminal
$ ap audit search --type <event_type>

Export audit data to CSV or JSON format

Terminal
$ ap audit export --format csv

Mobile Operations#

On mobile, audit events are accessible under the Insights tab. The audit segment provides:

  • -Scrollable event list with type badges, actor, and relative timestamps
  • -Tap any event to view its full detail including metadata and related events
  • -Pull-to-refresh to load the latest events

FAQ#

Q: How long are audit events retained?
A: Audit events are retained indefinitely by default. Self-hosted deployments can configure retention policies at the database level. Cloud users on the Pro plan have unlimited retention; Free plan retains the most recent 90 days.
Q: Can audit events be modified or deleted?
A: No. The audit trail is append-only and immutable by design. Events cannot be edited, backdated, or deleted through the application. This guarantees the integrity of the record for compliance and forensic purposes.
Q: What is the Evidence Pack and when should I use it?
A: The Evidence Pack (TCC Step 05) is a bundled export of related audit events with cryptographic integrity verification. Use it when you need to provide formal evidence for compliance audits, security incident reports, or regulatory inquiries. It includes all event metadata, actor attribution, and a hash chain for tamper detection.
Audit Search — ClawButler User Manual