API Reference

HookProbe exposes HTTP APIs for monitoring, metrics, and management.

Health Endpoint

GET /health

Check service health.

curl http://localhost:8888/health

Response:

{
  "status": "healthy",
  "uptime_seconds": 86400,
  "components": {
    "agent": "running",
    "napse": "running",
    "xdp": "loaded"
  }
}

Field	Type	Description
status	string	”healthy” or “unhealthy”
uptime_seconds	integer	Seconds since start
components	object	Component status

Metrics Endpoint

GET /metrics

Get current metrics.

curl http://localhost:8888/metrics

Response:

{
  "qsecbit": {
    "score": 0.32,
    "status": "GREEN",
    "components": {
      "threats": {"value": 0.10, "weight": 0.30},
      "mobile": {"value": 0.15, "weight": 0.20},
      "ids": {"value": 0.08, "weight": 0.25},
      "xdp": {"value": 0.12, "weight": 0.15},
      "network": {"value": 0.05, "weight": 0.02},
      "dnsxai": {"value": 0.18, "weight": 0.08}
    }
  },
  "xdp": {
    "packets_total": 1234567,
    "packets_dropped": 4521,
    "pps_current": 12345
  },
  "napse": {
    "alerts_total": 47,
    "alerts_24h": 12
  },
  "dnsxai": {
    "queries_total": 98765,
    "blocks_total": 234,
    "blocks_24h": 45
  },
  "timestamp": "2025-12-07T18:35:00Z"
}

GET /metrics/prometheus

Prometheus format metrics.

curl http://localhost:8888/metrics/prometheus

Response:

# HELP qsecbit_score Current QSecBit score
# TYPE qsecbit_score gauge
qsecbit_score 0.32

# HELP xdp_packets_total Total packets processed
# TYPE xdp_packets_total counter
xdp_packets_total 1234567

# HELP napse_alerts_total Total IDS alerts
# TYPE napse_alerts_total counter
napse_alerts_total 47

Mesh Endpoints

GET /mesh/status

Get mesh connectivity status.

curl http://localhost:8888/mesh/status

Response:

{
  "connected": true,
  "peers": 23,
  "validators": 5,
  "last_sync": "2025-12-07T18:34:00Z",
  "contribution": {
    "microblocks": 1847,
    "alerts_shared": 23
  }
}

GET /mesh/peers

List connected peers.

curl http://localhost:8888/mesh/peers

Response:

{
  "peers": [
    {
      "node_id": "edge-12345",
      "type": "edge",
      "connected_since": "2025-12-07T12:00:00Z",
      "latency_ms": 45
    },
    {
      "node_id": "validator-001",
      "type": "validator",
      "connected_since": "2025-12-07T10:00:00Z",
      "latency_ms": 23
    }
  ]
}

DSM Endpoints

GET /dsm/status

Get DSM ledger status.

curl http://localhost:8888/dsm/status

Response:

{
  "current_epoch": 147,
  "last_checkpoint": "2025-12-07T18:30:00Z",
  "microblocks_pending": 12,
  "validators_online": 5,
  "quorum_met": true
}

GET /dsm/blocks

List recent microblocks.

curl http://localhost:8888/dsm/blocks?limit=10

Response:

{
  "blocks": [
    {
      "hash": "abc123...",
      "seq": 1847,
      "timestamp": "2025-12-07T18:35:00Z",
      "event_type": "ids_alert"
    }
  ]
}

DNS Endpoints

GET /dns/stats

Get dnsXai statistics.

curl http://localhost:8888/dns/stats

Response:

{
  "queries_total": 98765,
  "queries_24h": 5432,
  "blocks_total": 234,
  "blocks_24h": 45,
  "categories": {
    "MALWARE": 12,
    "TRACKING": 156,
    "ADVERTISING": 66
  }
}

GET /dns/recent

Recent blocked domains.

curl http://localhost:8888/dns/recent?limit=10

Response:

{
  "blocks": [
    {
      "domain": "tracker.example.com",
      "timestamp": "2025-12-07T18:34:00Z",
      "category": "TRACKING",
      "confidence": 0.92
    }
  ]
}

Configuration Endpoints

GET /config

Get current configuration (non-sensitive).

curl http://localhost:8888/config

Response:

{
  "tier": "guardian",
  "xdp_enabled": true,
  "xdp_mode": "native",
  "qsecbit_thresholds": {
    "amber": 0.45,
    "red": 0.70
  },
  "mesh_enabled": true
}

Debug Endpoints

Available when debug mode is enabled.

GET /debug/state

Internal state dump.

curl http://localhost:8888/debug/state

GET /debug/connections

Active connections.

curl http://localhost:8888/debug/connections

Error Responses

All endpoints return errors in consistent format:

{
  "error": true,
  "code": "ERR_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2025-12-07T18:35:00Z"
}

Code	HTTP Status	Description
ERR_NOT_FOUND	404	Resource not found
ERR_INTERNAL	500	Internal error
ERR_INVALID	400	Invalid request
ERR_UNAUTHORIZED	401	Authentication required

Authentication

Local endpoints (localhost) don’t require authentication.

For remote access, use API keys:

curl -H "X-API-Key: your-key" http://host:8888/metrics

Rate Limiting

Endpoint	Limit
/health	Unlimited
/metrics	60/min
/mesh/*	30/min
/dsm/*	30/min
/dns/*	30/min
/debug/*	10/min

Threat Intelligence API (Public)

These endpoints are served from hookprobe.com (the landing site) and provide anonymized threat data from the HYDRA IDS pipeline.

GET /api/threats/live/

Returns aggregated threat intelligence from the last 7 days.

{
  "countries": [
    {"country": "CN", "threat_count": 7467, "malicious": 40, "suspicious": 242, "avg_score": 0.217, "lat": 35.86, "lng": 104.19},
    {"country": "NL", "threat_count": 1388, "malicious": 1217, ...}
  ],
  "asns": [
    {"asn_name": "VOLCANO-ENGINE", "country": "CN", "threat_count": 2966, "avg_score": 0.207}
  ],
  "recent": [
    {"timestamp": "2026-03-23 14:50:38", "country": "AD", "asn_name": "DMZHOST", "verdict": "malicious", "action_taken": "escalate", "score": 0.748}
  ],
  "stats": {
    "total_verdicts_7d": 27772,
    "malicious_7d": 7751,
    "unique_ips_7d": 2208,
    "xdp_blocked_7d": 1017696
  }
}

Data source: ClickHouse hydra_verdicts + rdap_cache tables. Cached for 5 minutes.

GET /api/threats/check-ip/?q=QUERY

Check any IP address or ASN against the HYDRA threat database (last 30 days).

Query types:

IP address: ?q=185.93.89.122
ASN name: ?q=DMZHOST
ASN number: ?q=AS13335

{
  "query": "185.93.89.122",
  "type": "ip",
  "found": true,
  "verdict_count": 6,
  "malicious": 3,
  "suspicious": 3,
  "avg_score": 0.688,
  "country": "AE",
  "asn_name": "AMWAJ",
  "ip_type": "datacenter",
  "risk_level": "medium"
}

Risk levels: clean, low, medium, high. Rate limited: 60-second cache.

Next Steps

CLI Reference - Command-line usage
hookprobe-ctl - Hardware detection CLI
AEGIS AI Defense - Agent architecture
Brain & NPU - Inference bridge
Monitoring - Metrics details