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. Events are written asynchronously by the batch writer — the audit stage always runs, even for blocked requests.

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	cryptographic hash of the raw tool input (for non-PII inputs).
details	Event-specific payload (detection results, policy matched, etc.).
timestamp	ISO 8601 timestamp.
previousHash	Hash of the preceding event — forms the hash chain.
hash	cryptographic hash of this event record (including previousHash).

Tamper-Evident Hash Chain

Each event includes a previousHash field pointing to the cryptographic hash of the prior event. The hash field is then the cryptographic hash of the full event record including previousHash. This forms a cryptographic chain — any retrospective modification of a past event breaks all subsequent hashes and is immediately detectable.

event[n-1]

→ hash →

event[n].previousHash

→ cryptographic hash(event[n]) →

event[n].hash

Chain integrity can be verified at any time via the API or the dashboard's compliance view. The EU AI Act Annex IV evidence report includes a chain verification result.

Querying the Audit Log

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.

bash

# List all blocked tool calls for an agent in the last 24 hours
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.shieldagent.io/tenants/$TENANT_ID/audit-events?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"
  },
  "inputHash": "e3b0c44298fc1c149afb...",
  "timestamp": "2026-04-25T10:00:00.000Z",
  "previousHash": "a3f8b2c1d4e5f6...",
  "hash": "9c12f3e7b8a1d2..."
}

API Endpoints

GET/tenants/:tenantId/audit-events—List audit events with filtering and cursor pagination.

GET/tenants/:tenantId/audit-events/:eventId—Fetch a single event by ID.

GET/tenants/:tenantId/audit-events/verify-chain—Verify the hash chain integrity for a time range.

POST/tenants/:tenantId/audit-events/export—Trigger an on-demand export job to any configured adapter.

Retention Policy

SaaS deployments retain audit events in the hot (searchable) tier for a configurable period. BYOC and On-Prem deployments own their own database and set their own retention policy. Contact us at info@shieldagent.io for specific retention requirements.