audit/20_Observability_Metrics.md

Topic 20: Observability & Metrics Architecture

Audit Date: 2026-02-01 Auditor: Agent Antigravity Scope: Monitoring & Telemetry

---

1. Deep Telemetry Engine (telemetry.py)

The system does not just log text; it builds a Digital Fingerprint of the attacker.

• Real Geo-Location: Uses ip-api.com to fetch Country, ISP, and Proxy status.
• Hardware Fingerprinting:
  • Captures Screen Resolution, Timezone, and Hardware Concurrency via the "Silent Beacon" JS in decoy pages.
  • Goal: Distinguish between a Human Scammer (Mobile Device) and a Bot (Headless Server).
• Evidence: TelemetryCollector.track_request() -> _generate_fingerprint().

---

2. Prometheus Metrics Integration

The system exposes standard Prometheus-compatible metrics for dashboards (Grafana).

• Endpoint: get_prometheus_metrics() generates the text payload.
• Key Metrics:
  • sentinel_requests_total: Traffic volume.
  • sentinel_threats_detected_total: Distinct attacker count.
  • sentinel_scam_events_total{type="lottery"}: Breakdown by scam category.

---

3. SIEM / SOC Integration

• Format: JSONL (JSON Lines).
• Compatibility: Designed for direct ingestion into Splunk, Azure Sentinel, or ELK Stack.
• Fields: timestamp, source_ip, risk_score, geo_data, intelligence_count.
• Code: get_siem_export() formats the internal state into a log stream.

---

4. Operational Visibility

• Risk Scoring: Real-time calculation based on:
  • Hosting Provider IP? (+40 Risk)
  • VPN Detected? (+30 Risk)
  • High-Risk Country (NG/CN/RU)? (+30 Risk)
• Result: The Admin Dashboard can show a "Heatmap" of attacks in real-time.