k0nsult.cloud / ai-truth / ipIII / api

Referencja API

Kontrakt REST systemu incydentów cyber/AI. Zasób bazowy /api, format JSON, uwierzytelnianie nagłówkiem (Bearer / x-konsult-secret). Autoryzacja per-endpoint zależna od roli (patrz Role i priorytety).

Read-path LIVE. Endpointy odczytu /api/ip3/incidents, /api/ip3/stats, /api/ip3/playbooks realnie działają (dane SIMULATION) — przetestuj je w API Explorer. Kontrakt maszynowy: openapi.json. Rejestr operacyjny /api/incidents i zapis (POST/PATCH) = chronione / produkcyjne (OIDC/mTLS — ROADMAP).

Hub Evidence-first Model danych API Role i priorytety

Status: szkic kontraktu. Endpointy opisują docelowy kontrakt. Implementacja produkcyjna ma status GAP. Wszystkie przykłady request/response są danymi SYMULACJA — ilustrują kształt payloadu, nie realny ruch.

Konwencje

Kody: 200 OK, 201 Created, 202 Accepted (intake async), 400 walidacja, 401/403 autoryzacja, 409 konflikt stanu (np. zamknięcie bez dowodu), 422 naruszenie doktryny evidence-first.
Każda mutacja incydentu zapisuje wpis audytowy; dowody wymagają hash_sha256 tam, gdzie dotyczy materiału binarnego.
Reguła 422: PATCH zmieniający status_lifecycle na closed bez powiązanego validation_ref jest odrzucany.

Zestawienie endpointów

Metoda	Ścieżka	Rola min.	Opis
POST	`/api/incidents`	Reporter	Utwórz incydent (domyślnie `gap`).
GET	`/api/incidents`	Viewer	Lista z filtrami (priority, level, flags, status).
GET	`/api/incidents/:id`	Viewer	Szczegół incydentu z dowodami i działaniami.
PATCH	`/api/incidents/:id`	Analyst	Aktualizacja klasyfikacji/statusu/flag.
POST	`/api/incidents/:id/evidence`	Analyst	Dołącz dowód (kind, hash, confidence, custody).
GET	`/api/incidents/:id/evidence`	Viewer*	Dowody incydentu (filtr visibility wg roli).
POST	`/api/incidents/:id/actions`	Operator	Dodaj krok reakcji z playbooka.
PATCH	`/api/actions/:id`	Operator	Aktualizuj status kroku; HITL approve.
GET	`/api/map/incidents`	Viewer	Dane do Threat Map (geo/sektor/czas).
GET	`/api/stats/incidents`	Viewer	KPI agregaty dla dashboardu.
GET	`/api/playbooks`	Viewer	Indeks playbooków.
GET	`/api/playbooks/:type`	Viewer	Kroki playbooka danego typu.
POST	`/api/intake/osint`	Operator	Zgłoszenie z OSINT (status wejściowy media/public).
POST	`/api/intake/log`	DevSecOps	Zgłoszenie z logu SIEM/EDR (internal).
POST	`/api/agents/:id/quarantine`	AI Safety	Kwarantanna agenta (odbierz uprawnienia).
POST	`/api/agents/:id/restore`	AI Safety	Przywróć agenta po walidacji.
POST	`/api/reports/incidents/:id/export`	Legal/DPO	Eksport raportu do organu (NIS2/RODO/AI Act).

* Viewer* — Public Viewer widzi wyłącznie dowody visibility=public; restricted/internal wymagają roli Analyst+.

POST /api/incidents — utworzenie

Request SYMULACJA:

POST /api/incidents
Content-Type: application/json

{
  "title": "Podejrzenie prompt injection w agencie obsługi",
  "source_type": "form",
  "level": "L2_ai",
  "category": "prompt_injection",
  "detected_at": "2026-07-04T08:12:00Z",
  "agent_id": "b1f2...-agent",
  "impact_integrity": 2,
  "gdpr_personal_data": true
}

Response SYMULACJA:

201 Created

{
  "id": "9c0a...-inc",
  "public_id": "INC-2026-0042",
  "evidence_status": "gap",
  "priority": null,
  "status_lifecycle": "open",
  "sla_due_at": null,
  "flags": { "ai_act_relevant": true, "gdpr_personal_data": true },
  "created_at": "2026-07-04T08:12:03Z"
}

Uwaga doktrynalna. Nowy incydent zawsze rodzi się jako gap z priority=null. Priorytet i awans statusu nadaje dopiero klasyfikacja po dowodzie (Classification Engine).

POST /api/incidents/:id/evidence — dołączenie dowodu

POST /api/incidents/INC-2026-0042/evidence     // SYMULACJA

{
  "kind": "agent_trace",
  "source": "orchestrator-logs",
  "content_ref": "s3://evidence/trace-0042.json",
  "hash_sha256": "3b1f...e9",
  "confidence": 82,
  "visibility": "internal",
  "chain_of_custody": [
    {"ts":"2026-07-04T08:20:00Z","actor":"analyst:kdzik","action":"collected","hash_after":"3b1f...e9"}
  ]
}

--> 201 Created  { "id":"ev-771", "status":"confirmed" }
// agregacja podnosi incidents.evidence_status: gap -> confirmed

PATCH /api/incidents/:id — klasyfikacja i zamknięcie

PATCH /api/incidents/INC-2026-0042              // SYMULACJA
{ "priority": "P1", "severity": 7, "ai_serious_incident": true }
--> 200 OK  { "sla_due_at":"2026-07-05T08:12:03Z", "nis2_relevant":true }

// próba zamknięcia bez dowodu naprawy:
PATCH /api/incidents/INC-2026-0042  { "status_lifecycle":"closed" }
--> 422 Unprocessable Entity
{ "error":"evidence_required",
  "detail":"Zamknięcie wymaga response_action z validation_ref (dowód naprawy)." }

POST /api/agents/:id/quarantine — reakcja na przejęcie

POST /api/agents/b1f2...-agent/quarantine       // SYMULACJA
{ "incident_id":"INC-2026-0042", "reason":"prompt_injection_confirmed",
  "approved_by":"aiso:mpaw" }
--> 200 OK
{ "status":"quarantined","current_score":34,"trust_delta":-66,
  "allowed_tools_effective":[] }

Kwarantanna odbiera efektywne uprawnienia niezależnie od allowed_tools. Przywrócenie (/restore) wymaga roli AI Safety Officer i dowodu walidacji (patrz playbook agent hijack).

POST /api/reports/incidents/:id/export — raport do organu

POST /api/reports/incidents/INC-2026-0042/export   // SYMULACJA
{ "target":"csirt_nask", "regime":"nis2", "phase":"early_warning_24h" }
--> 202 Accepted
{ "report_id":"RPT-0042-1", "regime":"nis2", "phase":"24h",
  "bundle":["incident","evidence(public,restricted)","timeline"],
  "delivery":"edelivery_pending" }

Eksport dobiera zakres wg reżimu: NIS2 (wczesne ostrzeżenie 24h → zgłoszenie 72h → raport końcowy), RODO art. 33 (72h do organu), AI Act art. 73 (poważny incydent). Doręczenie potwierdza UPO/e-Doręczenie, które wraca jako dowód typu upo_edelivery. Szczegóły reżimów: Compliance.

GET /api/stats/incidents — KPI

GET /api/stats/incidents?window=30d              // SYMULACJA
--> 200 OK
{ "total":128, "open_p0_p1":7, "evidence_coverage":0.94,
  "flags":{"ai_serious_incident":3,"nis2_relevant":11,"gdpr_breach":5},
  "mtta_p0_min":131, "mttc_p1_h":18, "_note":"dane demonstracyjne" }

Kontrakt, nie obietnica działania. Ta strona definiuje kształt interfejsu. Dopóki backend nie zostanie wdrożony i przetestowany, każdy endpoint traktuj jako GAP implementacyjny — schemat zgodny z modelem danych.