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.