Engagement Reports#

InfraGuard generates self-contained engagement reports from the tracking database. Reports summarize redirector activity across domains, showing blocked traffic patterns, filter effectiveness, and an operator audit trail. Available in HTML, JSON, and CSV formats.

Generating Reports#

API Endpoint#

# HTML report (default)
curl -H "Authorization: Bearer $TOKEN" \
  "https://ig:8080/api/reports/export?format=html" -o report.html

# JSON report
curl -H "Authorization: Bearer $TOKEN" \
  "https://ig:8080/api/reports/export?format=json" -o report.json

# CSV report
curl -H "Authorization: Bearer $TOKEN" \
  "https://ig:8080/api/reports/export?format=csv" -o report.csv

Report generation is audit-logged.

Report Contents#

Summary Statistics#

Per-Domain Breakdown#

Each configured domain gets its own section with:

• Total requests handled
• Block/allow/suspect counts
• Top blocked IPs (with request count)
• Most common block reasons

Filter Effectiveness#

Shows how each filter in the pipeline contributed to blocking:

Top Blocked User-Agents#

Lists the most frequently seen User-Agent strings on blocked requests - useful for identifying which scanners or crawlers targeted the infrastructure.

Hourly Volume#

Request volume broken down by hour, showing traffic patterns over the engagement period.

Node List#

All registered redirector nodes with their status, bound domains, and last heartbeat time.

Operator Audit Trail#

Timestamped log of operator actions: configuration changes, heartbeats, manual blocks, report exports.

HTML Report#

The HTML report is fully self-contained - all CSS is inlined, no external dependencies. It renders a grid layout with:

• Summary stats cards at the top
• Per-domain tables with sortable columns
• Filter effectiveness breakdown
• Blocked IP and User-Agent tables

The HTML file can be opened directly in a browser and shared as a standalone artifact.

JSON Report#

The JSON format returns the same data structure used internally by collect_report_data():

{
  "summary": {
    "total": 15420,
    "blocked": 8721,
    "allowed": 5843,
    "suspect": 856,
    "period_start": "2025-03-01T00:00:00Z",
    "period_end": "2025-03-15T23:59:59Z"
  },
  "domains": { ... },
  "top_blocked_ips": [ ... ],
  "top_blocked_uas": [ ... ],
  "filter_reasons": { ... },
  "hourly_volume": [ ... ],
  "nodes": [ ... ],
  "audit_log": [ ... ]
}

CSV Report#

The CSV format exports the request log in a flat table suitable for import into spreadsheet tools or SIEM platforms.