Visibility is the foundation of defense-in-depth security. ThornGuard writes an asynchronous audit log for every significant action processed through the proxy. These logs are stored in a highly durable, globally distributed Cloudflare D1 (SQLite) database.Documentation Index
Fetch the complete documentation index at: https://qwady.wiki/llms.txt
Use this file to discover all available pages before exploring further.
Database Schema
Every event is recorded in theaudit_logs table with the following schema:
| Column | Type | Description |
|---|---|---|
id | INTEGER | Internal primary key (auto-incrementing). |
log_id | TEXT | Public-facing UUID identifier (crypto.randomUUID()). Used by the dashboard. |
trace_id | TEXT | Correlation ID shared with client-visible x-thornguard-trace-id headers. |
timestamp | DATETIME | UTC timestamp (defaults to CURRENT_TIMESTAMP). |
license_hash | TEXT | A SHA-256 hash of the authenticated ThornGuard license identity associated with the request. |
target_url | TEXT | The upstream server requested (e.g., api.githubcopilot.com). |
rpc_method | TEXT | The specific MCP tool being called (e.g., get_issue). |
action | TEXT | The categorization of the event (see Action Types below). |
details | TEXT | Extended context, errors, or reasons for blocking. |
details_json | TEXT | Structured JSON metadata for richer event context. |
policy_rule_id | TEXT | The matched policy rule identifier when a policy event is involved. |
response_time_ms | INTEGER | Time in milliseconds from request receipt to response completion. |
client_ip | TEXT | Client IP address (captured from CF-Connecting-IP header). |
The
id field is the internal auto-incrementing primary key. The log_id UUID is the public-facing identifier used by the dashboard and API. Older rows may not have a log_id — the dashboard falls back to id in those cases.ThornGuard sanitizes sensitive values such as auth headers, ThornGuard
tokens, upstream bearer tokens, and token-like query params before they are
persisted in ThornGuard-controlled audit records or fanned out to webhook
deliveries.
Action Types
Every audit log entry is classified with one of the followingaction values:
| Action | Description |
|---|---|
PROXY_SUCCESS | Request was successfully scrubbed and proxied to upstream. |
SSE_STREAM_ESTABLISHED | An SSE stream was successfully opened to the client. |
BLOCKED_MALICIOUS | Destructive command intercepted (e.g., rm -rf, sudo). |
BLOCKED_AUTH | Authentication failure — license invalid, missing, or expired. |
BLOCKED_INSECURE_TARGET | Target URL was rejected because it was not HTTPS. |
BLOCKED_ORIGIN | Request origin was rejected by the configured allowlist. |
BLOCKED_SSRF | SSRF attempt blocked — target URL or resolved DNS address was restricted. |
BLOCKED_RATE_LIMIT | Request dropped because the per-license rate limit was exceeded. |
BLOCKED_IP_WHITELIST | Client IP was not in the enterprise IP whitelist. |
BLOCKED_CUSTOM_DOMAIN | Target domain matched a per-license custom blocklist entry. |
BLOCKED_CUSTOM_COMMAND | Command pattern matched a per-license custom command blocklist. |
BLOCKED_POLICY | A structured tenant policy rule blocked the request. |
POLICY_AUDIT | A structured tenant policy rule matched in audit mode. |
BLOCKED_APPROVAL | A tool call was halted pending explicit approval. |
PII_REDACTED | PII or secrets were detected and scrubbed from request or response. Details include the types found (e.g., EMAIL, AWS_KEY). |
CUSTOM_REDACTION_AUDIT | A custom enterprise redaction rule matched in audit mode. |
UPSTREAM_ERROR | The upstream MCP server returned an error (timeout, non-JSON response, etc.). |
TOOL_POISONING_DETECTED | Prompt injection, recommendation poisoning, or hidden characters detected in a tool definition or response. |
TOOL_SCHEMA_DRIFT | A tool’s input or output schema changed from its TOFU-pinned baseline. |
TOOL_COLLISION_DETECTED | Duplicate tool names detected from the same upstream server. |
ANOMALY_DETECTED | Behavioral anomaly flagged by EWMA, drift detection, or Markov sequence analysis. |
RESPONSE_PROCESSING_ERROR | Failed to process or parse upstream response content. |
APPROVAL_ERROR | Approval system temporarily unavailable (DO failure or missing config). |
AUDIT_PURGE | Logs were purged via a GDPR deletion request. |
The dashboard summary cards are action-count summaries for the selected time
range. The
Risk Signals card intentionally includes blocked events plus
redaction, audit, tool-integrity, anomaly, and upstream-error actions that
operators usually want to review together.Querying Logs
Correlation Headers
Successful proxied responses and ThornGuard-generated error responses include:x-thornguard-log-idx-thornguard-trace-id
audit_logs.log_id and audit_logs.trace_id, making it easy to correlate user-visible failures with backend logs and webhook deliveries.
Via the Dashboard
The ThornGuard Dashboard provides a graphical interface for browsing audit logs with filtering by action type, date range, and search — plus 10-second auto-polling for real-time updates. See Dashboard for details.Via the Wrangler CLI
You can also query logs directly using the Wrangler CLI. View the 10 most recent events:Log Retention
ThornGuard supports configurable log retention periods per license tier.- Default retention: 90 days (Individual), 365 days (Enterprise).
- Cleanup schedule: A daily cron job runs at 3:00 AM UTC to delete expired logs.
- Custom retention: Current dashboard controls allow retention changes within your allowed tier limits.
Data Export
Audit logs can be exported from the dashboard Settings page or via the API in multiple formats:| Format | Description | Use Case |
|---|---|---|
| CSV | RFC 4180 comma-separated values | Spreadsheets, general analysis |
| JSON | Standard JSON array | Programmatic access, custom tooling |
| NDJSON | Newline-delimited JSON (one event per line) | Streaming ingest, log aggregators |
| OCSF | Open Cybersecurity Schema Framework 1.3.0 | SIEM platforms (Splunk, Elastic, etc.) |
| CEF | Common Event Format (pipe-delimited) | Syslog-compatible SIEM ingest |
| LEEF | Log Event Extended Format | HP ArcSight and similar platforms |
Compliance Summary
The dashboard Settings page includes a Compliance Report button that generates a JSON summary of your audit posture:- Total events and breakdown by action type
- High-signal event count (blocked requests, redacted data, tool poisoning, anomalies)
- GDPR purge record count
- Audit signing status
- Data retention setting and license tier
- Report generation timestamp
GET /api/compliance/summary.
GDPR Compliance
ThornGuard supports right-to-deletion requests through a one-click audit log purge:- Accessible from the dashboard Settings page under Danger Zone.
- Purging deletes all audit logs associated with your license.
- A final
AUDIT_PURGEaction is logged to maintain a record of the deletion event itself.