Proxy Audit — Auditoria Contínua de Disciplina de Proxy/VPN (Superadmin)

17.Y Proxy Audit — Auditoria Contínua de Disciplina de Proxy/VPN (Superadmin)#

A auditoria de proxy executa um conjunto fixo de checks a cada 5 minutos para provar o invariante "todo tráfego Meta/WhatsApp sai pelo IP dedicado da instância". Cada execução persiste uma linha em proxy_audit_runs + uma linha por finding em proxy_audit_findings. As metricas Prometheus são atualizadas em sincronia e as regras de alerta padrão (AlertRule) são semeadas no primeiro boot.

Checks executados:

Slug	Descricao	Severidade em caso de falha
`pong_mismatch`	Mismatches ou falhas em `proxy_health_events` na última hora	error
`assigned_ip_unhealthy`	IPs status=assigned com `last_health_ok=false`	error
`instance_without_proxy`	Instâncias CONNECTED sem `proxy_ip_id`	error (pool on) / warn (pool off)
`stale_pong`	IPs assigned sem pong OK nos últimos 11min	error
`unused_proxy_release`	Reclama IPs nunca pareados ociosos >1h, bane os envenenados	ok (housekeeping)
`phantom_decommissioned`	IPs marcados `decommissioned` localmente que ainda aparecem no inventario do Bright Data (slots ainda cobrados apesar do ack 2xx)	error

Estados possíveis de um run:

ok=true, warnings=0 → "all checks ok"
ok=true, warnings>0 → tolerado (ex.: instância legacy sem binding)
ok=false → violação do invariante, qualquer finding com severity=error

GET/v1/admin/proxy-audit/runs#

Lista os runs mais recentes (sem findings). Para o histórico na UI.

Auth: Superadmin

Query:

limit: int, default 50, max 200

Response (200):

json

{
  "data": [
    {
      "id": 1234,
      "trigger": "scheduled",
      "started_at": "2026-04-18T12:00:00Z",
      "finished_at": "2026-04-18T12:00:01Z",
      "duration_ms": 234,
      "ok": true,
      "checks": 6,
      "failures": 0,
      "warnings": 0,
      "summary": "all checks ok"
    }
  ],
  "total": 1,
  "limit": 50
}

GET/v1/admin/proxy-audit/latest#

Retorna o run mais recente COM findings. Quando nenhum run foi executado ainda, responde { "status": "pending_first_run" } (HTTP 200) para o dashboard renderizar o estado vazio.

Auth: Superadmin

Response (200):

json

{
  "id": 1234,
  "trigger": "scheduled",
  "started_at": "2026-04-18T12:00:00Z",
  "finished_at": "2026-04-18T12:00:01Z",
  "duration_ms": 234,
  "ok": false,
  "checks": 6,
  "failures": 1,
  "warnings": 0,
  "summary": "failed: pong_mismatch — 2 pong failures/mismatches in last hour",
  "findings": [
    {
      "check": "pong_mismatch",
      "severity": "error",
      "count": 2,
      "message": "2 pong failures/mismatches in last hour",
      "detail": [
        { "proxy_ip_id": 7, "expected": "1.2.3.4", "observed": "9.9.9.9", "ok": true, "match": false, "at": "2026-04-18T11:55:00Z" }
      ]
    }
  ]
}

GET/v1/admin/proxy-audit/runs/{runId}#

Retorna um run especifico COM findings.

Auth: Superadmin

POST/v1/admin/proxy-audit/run#

Dispara um run sincrono agora mesmo. Response identica a /latest. Registrado em audit_logs (action=proxy_audit.run).

Auth: Superadmin

Metricas Prometheus relacionadas#

Metrica	Tipo	Alerta configurado
`biazap_proxy_audit_runs_total{result,trigger}`	counter	—
`biazap_proxy_audit_failures_total{check,severity}`	counter	via AlertRule `proxy_audit_last_run_ok < 1`
`biazap_proxy_audit_last_run_timestamp_seconds`	gauge	dashboard
`biazap_proxy_audit_last_run_ok`	gauge (0/1)	AlertRule built-in
`biazap_instances_without_proxy_binding`	gauge	AlertRule `> 0`
`biazap_instances_connected_direct_total`	counter	AlertRule `> 0`
`biazap_proxy_health_pong_mismatch_total`	counter	AlertRule `> 0`
`biazap_proxy_decommission_verification_total{result,provider}`	counter	—

Gate no /ready#

Quando o pool está habilitado (BRIGHT_DATA_* configurado), GET /ready retorna 503 degraded se:

o último run tem ok=false, ou
o último run e mais antigo que 15min (auditor travado)

Use o /health para checagem de liveness (nunca bloqueia em proxy state) e /ready como gate de tráfego.