ligbox-ops-platform/specs/009-ops-audit-overview/contracts/audit-api.md

Contract: Audit API

Base: https://api.ops.ligbox.com.br (ou LAN http://10.10.10.122:8080)

GET /api/v1/audit/overview

Lista tenants registados com saúde agregada.

Response 200

{
  "generated_at": "2026-06-08T18:00:00Z",
  "tenants": [
    {
      "tenant_id": 1,
      "name": "VM112 Ligbox Onboard",
      "ip": "10.10.10.112",
      "status": "degraded",
      "score": { "pass": 6, "warn": 1, "fail": 1, "total": 8 },
      "domains_count": 2,
      "last_audit_at": "2026-06-08T17:55:00Z",
      "top_issues": [
        { "domain": "exemplo.com", "check_id": "dns_dkim", "status": "fail", "message": "TXT not found" }
      ]
    }
  ]
}

Status values

healthy | degraded | critical | unknown

---

GET /api/v1/audit/tenants/{tenant_id}/scorecard

Query: domain (required)

Response 200

{
  "tenant_id": 1,
  "domain": "exemplo.com",
  "checked_at": "2026-06-08T17:55:00Z",
  "overall_status": "degraded",
  "checks": [
    {
      "check_id": "carbonio",
      "label": "Carbonio domain",
      "status": "pass",
      "message": "Domain exists in Carbonio",
      "evidence": { "exists": true },
      "checked_at": "2026-06-08T17:55:01Z"
    },
    {
      "check_id": "nginx_vhost",
      "label": "carbonio-nginx vhost",
      "status": "pass",
      "message": "Vhost configured for mail.exemplo.com",
      "evidence": {},
      "checked_at": "2026-06-08T17:55:02Z"
    },
    {
      "check_id": "cert_le",
      "label": "Let's Encrypt certificate",
      "status": "warn",
      "message": "Expires in 21 days",
      "evidence": { "expires_at": "2026-06-29T12:00:00Z" },
      "checked_at": "2026-06-08T17:55:03Z"
    },
    {
      "check_id": "dns_mx",
      "label": "MX record",
      "status": "pass",
      "message": "MX points to mail.exemplo.com",
      "evidence": { "records": ["10 mail.exemplo.com"] },
      "checked_at": "2026-06-08T17:55:04Z"
    },
    {
      "check_id": "dns_spf",
      "label": "SPF",
      "status": "pass",
      "message": "SPF record present",
      "evidence": {},
      "checked_at": "2026-06-08T17:55:05Z"
    },
    {
      "check_id": "dns_dkim",
      "label": "DKIM",
      "status": "fail",
      "message": "default._domainkey TXT not found",
      "evidence": {},
      "checked_at": "2026-06-08T17:55:06Z"
    },
    {
      "check_id": "dns_dmarc",
      "label": "DMARC",
      "status": "pass",
      "message": "DMARC record present",
      "evidence": {},
      "checked_at": "2026-06-08T17:55:07Z"
    },
    {
      "check_id": "webmail_http",
      "label": "Webmail HTTPS",
      "status": "pass",
      "message": "HTTP 200",
      "evidence": { "url": "https://mail.exemplo.com/", "status_code": 200 },
      "checked_at": "2026-06-08T17:55:08Z"
    }
  ]
}

---

POST /api/v1/audit/run/{tenant_id}

Trigger manual audit (ops debugging).

Query: domain (required)

Response 202

{
  "status": "queued",
  "tenant_id": 1,
  "domain": "exemplo.com"
}

---

Check IDs (canonical)

carbonio, nginx_vhost, cert_le, dns_mx, dns_spf, dns_dkim, dns_dmarc, webmail_http

Check status values

pass | warn | fail | error | skip