Audit Trail & Export

A tamper-evident, hash-chained log of every MCP tool call intercepted by ShieldAgent — with full context, policy decisions, and risk scores. Export to webhooks, Amazon S3, or Syslog for SIEM integration and long-term retention.

What Is Captured

Every request that passes through the ShieldAgent proxy produces an audit event. Every tool call is logged — including blocked requests — so you always have a complete record of agent activity.

Field	Description
id	Unique event ID (aev_…).
agentId	The agent that made the request.
tenantId	Your tenant scope.
eventType	tool_call, tool_drift, injection_detected, dlp_redaction, excessive_agency, policy_violation, etc.
action	allow, block, redact, or human_review.
riskScore	0–100 risk score at the time of the request.
tool	MCP tool name and server ID.
inputHash	Fingerprint of the tool input for integrity verification.
details	Event-specific payload (detection results, policy matched, etc.).
timestamp	ISO 8601 timestamp.

Tamper-Evident Logging

Every audit event is cryptographically linked to the one before it, creating a tamper-evident chain. If any past event is modified, the change is automatically detected. You can verify the integrity of your audit log at any time from the dashboard or API.

The EU AI Act Annex IV evidence report includes the result of this integrity verification, giving you compliance-ready proof that your audit trail has not been altered.

Browsing the Audit Log in the Dashboard

The dashboard provides a searchable, real-time view of all audit events — no API calls needed:

1Go to Audit Trail in the left sidebar.
2Use the filters at the top to narrow by agent, event type, outcome (allow / block / shadow), risk score range, or time window.
3Click any event row to see the full event payload including tool arguments, policy decision, and risk score.
4To verify chain integrity, click Verify Chain — the dashboard runs a hash check over the selected time range.
5To export, click Export and choose a destination (CSV, JSON, or configured SIEM adapter).

Querying via API

The audit log is queryable via REST API with rich filtering options. All filters can be combined.

agentIdFilter by agent.

serverIdFilter by MCP server.

eventTypeFilter by event type (tool_call, injection_detected, …).

actionFilter by outcome (allow, block, redact, human_review).

riskScoreMin / riskScoreMaxFilter by risk score range.

from / toISO 8601 time range.

limit / cursorCursor-based pagination.

typescript

import ShieldAgent from '@shieldagent/sdk';

const client = new ShieldAgent();

// List all blocked tool calls for an agent in the last 24 hours
const events = await client.auditEvents.list({
  agentId: "agt_...",
  action: "block",
  from: "2026-04-24T00:00:00Z",
});

Export Destinations

Configure one or more export adapters to stream audit events to your SIEM or long-term storage. Exports are near-real-time — events are flushed within seconds of being written.

WebhookHTTPS POST

POST each event (or a batch) as JSON to any HTTPS endpoint. Supports custom headers for SIEM authentication (Splunk HEC, Elastic, Datadog). Retries with exponential backoff on 5xx responses.

Setting	Description
Destination URL	Destination endpoint.
Batch size	Events per POST. Default 100.
Custom headers	JSON object of custom headers.

Amazon S3Object Storage

Write events as newline-delimited JSON (NDJSON) to an S3-compatible bucket. Files are partitioned by date (YYYY/MM/DD/HH) and flushed at a configurable interval. Compatible with S3, R2, MinIO, and GCS with HMAC keys.

Setting	Description
Bucket name	Bucket name.
Key prefix	Key prefix. Default: shieldagent/audit/.
Region	AWS region.
Flush interval	Flush interval. Default 60000.

SyslogRFC 5424

Stream events over UDP or TCP in RFC 5424 syslog format. Compatible with rsyslog, syslog-ng, and any SIEM with a syslog input. Each event is serialized as a CEF or JSON-in-syslog message.

Setting	Description
Receiver host	Syslog receiver host.
Receiver port	Receiver port. Default 514.
Protocol	udp or tcp.
Format	json or cef.

Sample Audit Event

json

{
  "id": "aev_01j...",
  "agentId": "agt_01j...",
  "tenantId": "ten_01j...",
  "eventType": "tool_call",
  "action": "block",
  "riskScore": 82,
  "tool": {
    "name": "read_file",
    "serverId": "srv_01j..."
  },
  "details": {
    "policyId": "pol_01j...",
    "policyName": "Block high-risk file reads",
    "reason": "risk_score_threshold"
  },
  "timestamp": "2026-04-25T10:00:00.000Z"
}

SDK & Dashboard

List audit events—Dashboard: Audit Trail page — filter by agent, event type, outcome, risk score, or time range. SDK: client.auditEvents.list({ agentId, eventType, action, from, to })

Fetch a single event—Dashboard: Audit Trail → click any event row. SDK: client.auditEvents.get(eventId)

Verify hash chain integrity—Dashboard: Audit Trail → Verify Chain button. SDK: client.auditEvents.verifyChain({ from, to })

Trigger an on-demand export—Dashboard: Audit Trail → Export button. SDK: client.auditEvents.export({ adapter })

Retention Policy

SaaS deployments retain audit events in the hot (searchable) tier for a configurable period. Long-term archival to S3 or Syslog is available via export adapters. Contact us at info@shieldagent.io for specific retention requirements.