Audit Logs
Visibility is the foundation of Zero-Trust. 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.
Database Schema
Section titled “Database Schema”Every event is recorded in the audit_logs table with the following schema:
| Column | Type | Description |
|---|---|---|
id | INTEGER | Primary Key (Auto-incrementing). |
license_hash | TEXT | A SHA-256 hash of the x-thornguard-license used to authenticate 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. |
timestamp | DATETIME | UTC Timestamp (defaults to CURRENT_TIMESTAMP). |
Action Types
Section titled “Action Types”You will commonly see the following action classifications in your logs:
- PROXY_SUCCESS: A JSON-RPC
POSTpayload was successfully scrubbed and proxied. - SSE_STREAM_ESTABLISHED: A successful
GETconnection was established to open the streaming channel. - BLOCKED_AUTH: A request was dropped because the ThornGuard license was invalid, missing, or expired.
- BLOCKED_MALICIOUS: A request was dropped due to Ingress signature matching (e.g.,
rm -rf). - BLOCKED_SSRF: A request was dropped because the target URL was a restricted internal IP.
- UPSTREAM_ERROR: The upstream server timed out (522) or returned a non-JSON HTML error page.
Querying Logs
Section titled “Querying Logs”To view your live audit logs, you can run D1 execute commands via the Wrangler CLI.
View the 10 most recent events
Section titled “View the 10 most recent events”npx wrangler d1 execute thornguard-audit --remote --command="SELECT timestamp, action, rpc_method, details FROM audit_logs ORDER BY id DESC LIMIT 10;"View all blocked malicious attempts
Section titled “View all blocked malicious attempts”npx wrangler d1 execute thornguard-audit --remote --command="SELECT timestamp, target_url, details FROM audit_logs WHERE action = 'BLOCKED_MALICIOUS' ORDER BY id DESC;"(Note: A web-based graphical dashboard for visualizing these logs is available at thornguard.qwady.app.)