K0NSULT // ai-truth/ipIII
k0nsult.cloud / ai-truth / ipIII / orchestrator / dev-api-reference

Dev / API Reference — co ipIII realnie udostępnia programiście

Ta strona jest przeznaczona dla developera/integratora, nie dla zarządu. Opisuje faktyczny stan kodu w repozytorium K0NSULT (API, konektory, moduły backendu, MCP) — nie architekturę docelową. Każdy element ma status LIVE (publiczny read-path), LIVE (auth-gated) (wymaga tokena), MVP, SIMULATION lub ROADMAP. Doktryna: claim ≤ proof — jeśli endpoint tu nie występuje, nie zakładaj że istnieje.

Zakres tej strony. Techniczna referencja API/konektorów/modułów. Dla decyzji biznesowej/regulacyjnej użyj CISO board pack lub rejestru ograniczeń. Ta strona nie stanowi SLA ani gwarancji dostępności — kontrakt referencyjny, nie umowa.
60 endpointów opisanych · 24 moduły backendu · 4 warstwy feature-flag · 1 MCP connector (ogólny, nie ipIII-scoped)

Trzon: import findingów (13 formatów) → normalizacja → ip3_incidents + ip3_evidence (PostgreSQL) → workflow remediacji z SLA → evidence-package (hash+chain-of-custody, opcjonalny podpis) → eksport do ticketingu/audytu. Warstwa v1 (/api/ip3/v1) ma realną persystencję i JWT/RBAC; warstwa demo (/api/ip3) jest efemerycznym mirrorem w pamięci do testów integracyjnych bez bazy.

PRZEPŁYW: import (MEDIA_SIGNAL)incydent+evidenceworkflow (assign/transition)close (wymaga CONFIRMED)evidence-packageticket/audit export

1. API read-path (SIMULATION, publiczne) — bez logowania

Endpointy montowane bezpośrednio w server.js. Dane demonstracyjne/syntetyczne, oznaczone jawnie source:"simulation" lub "reference". Nie wymagają tokena — służą do podglądu kontraktu i budowy widoków publicznych (dashboard, hub).

EndpointMetodaOpisStatus
/api/ip3/incidentsGETLista incydentów demo, filtr severity/status/group, agregaty by_severity/gap_pct.LIVE source: simulation
/api/ip3/incidents/:idGETSzczegóły pojedynczego incydentu demo.LIVE source: simulation
/api/ip3/statsGETAgregaty by_severity/by_group/by_evidence_status, gap_pct.LIVE source: simulation
/api/ip3/playbooksGETKuratorowana biblioteka referencyjna wzorców reagowania (12 grup incydentów).LIVE source: reference
/api/ip3/playbooks/:typeGETSzczegóły playbooka po typie incydentu + link do strony.LIVE
/ai-truth/ipIII/status.jsonGETStatus modułu, doktryna, statusy dowodowe, moduły koncepcyjne.LIVE
/ai-truth/ipIII/pages.jsonGETRejestr wszystkich stron ipIII (PL+EN) ze statusem produktu per strona.LIVE
/ai-truth/ipIII/openapi.jsonGETKontrakt OpenAPI 3.1 (referencyjny, nie SLA) — read-path + wybrane v1.LIVE
/ai-truth/ipIII/sitemap.xmlGETSitemap wyłącznie stron indeksowalnych (status LIVE/MVP steruje wpisem).LIVE
/ai-truth/ipIII/seo-policy.jsonGETPolityka SEO/GEO modułu (co indeksowane, co noindex i dlaczego).LIVE
/ai-truth/ipIII/llms.txtGETManifest dla modeli/agentów (GEO) — zakres modułu ipIII.LIVE
/llms.txtGETManifest GEO na poziomie całego portalu k0nsult.cloud.LIVE
/ai-truth/ipIII/samplesGETLista publicznych przykładów syntetycznych (bez logowania).LIVE
/ai-truth/ipIII/samples/:fileGETPobranie przykładu (Burp/Nessus demo, evidence-package demo, board-pack demo PDF, Postman collection).LIVE whitelist plików

2. API v1 (auth-gated JWT/OIDC) — /api/ip3/v1

Warstwa profesjonalna: realna persystencja PostgreSQL, JWT (lub OIDC/JWKS za flagą IP3_OIDC), RBAC (operator/analyst/auditor/admin), rate-limit, request_id na każdej odpowiedzi, audit log w bazie. Bez DATABASE_URL zwraca 503 (nie udaje persystencji). Router: routes/ip3-api-pro.js (850 linii).

2.1 Auth / tenancy status

EndpointMetodaOpisRolaStatus
/auth/loginPOSTLogin email+hasło (scrypt) → JWT 1h.LIVE (auth-gated)
/auth/meGETZwraca principal (sub, role, org) z tokena.dowolna rolaLIVE
/auth/oidc-statusGETDiagnostyka trybu OIDC (off/shadow/on), bez sekretów.publicznyLIVE
/tenancy-statusGETDiagnostyka izolacji multi-tenant (flaga IP3_TENANT_SCOPE).publicznyLIVE
/orgsGETLista organizacji.dowolna rolaLIVE

2.2 Incydenty (CRUD + evidence)

EndpointMetodaOpisRolaStatus
/incidentsGETLista z filtrem severity/status, scoping tenant.dowolna rolaLIVE
/incidents/:idGETSzczegóły + evidence powiązane, BOLA-safe (404 zamiast 403 dla obcego tenant).dowolna rolaLIVE
/incidentsPOSTUtworzenie incydentu ręcznie (title/group/type/severity wymagane).operator/analyst/adminLIVE
/incidents/:idPATCHEdycja title/description/severity. response_status/evidence_status celowo zablokowane tu (obejście reguły claim≤proof).operator/analyst/adminLIVE
/incidents/:id/evidencePOSTDodanie dowodu (hash z contentu lub podany), ustawia evidence_status=CONFIRMED przy pierwszym potwierdzonym.operator/analyst/adminLIVE
/incidents/:id/closePOSTZamknięcie — wymaga ≥1 evidence CONFIRMED (reguła close-with-evidence), inaczej 422.operator/analyst/adminLIVE
/incidents/:id/reopenPOSTPonowne otwarcie incydentu.operator/analyst/adminLIVE

2.3 Kontekst decyzyjny (legal / TTP / coverage / controls)

EndpointMetodaOpisRolaStatus
/incidents/:id/legal-triggersGETLegal Trigger Engine: incydent → obowiązki DORA/NIS2/RODO/AI Act + zegary. Decision-support, nie porada prawna.operator/analyst/auditor/adminLIVE
/incidents/:id/ttpGETMapowanie na techniki MITRE ATT&CK (heurystyka, kuratorowana podmapa).operator/analyst/auditor/adminLIVE
/incidents/:id/coverageGETEvidence Coverage Score — 6 wymiarów pokrycia dowodowego. NIE ocena bezpieczeństwa.operator/analyst/auditor/adminLIVE
/incidents/:id/controlsGETMapowanie evidence→control (ISO27001/NIST-CSF/CIS/DORA/NIS2), heurystyka po typie/CWE/severity.dowolna rolaLIVE

2.4 Workflow remediacji + ticketing

EndpointMetodaOpisRolaStatus
/incidents/:id/assignPOSTPrzypisanie ownera + SLA (P0=24h/P1=72h/P2=168h/P3=720h, nadpisywalne).operator/analyst/adminLIVE
/incidents/:id/transitionPOSTLifecycle open→triaged→assigned→fixing→retest. closed wyłącznie przez /close.operator/analyst/adminLIVE
/incidents/:id/ticketGETBuilder payloadu Jira/GitHub/webhook. ?send=true włącza realną wysyłkę (za flagą transportu).builder: operator/analyst/auditor/admin; wysyłka: operator/adminLIVE (builder) / transport za flagą
/connectors/transport-statusGETStatus flag transportu (GitHub/Jira/webhook) — bez ujawniania sekretów.operator/analyst/auditor/adminLIVE

2.5 Importy / konektory (opis szczegółowy w sekcji 3)

Wszystkie poniżej zwracają 201 z connector_run (incidents_created, deduplicated) i tworzą incydent+evidence ze statusem MEDIA_SIGNAL — sygnał narzędzia, nie dowód naprawy. Dedup po hashu treści (idempotentny re-import). Rola: operator/analyst/admin.

EndpointFormat wejściaStatus
POST /imports/genericJSON {source_tool, findings[]}LIVE
POST /imports/burpBurp Suite XMLLIVE
POST /imports/zapOWASP ZAP JSON lub XMLLIVE
POST /imports/nessusNessus/Tenable CSVLIVE
POST /imports/csvGeneric CSV (title,severity,cve,cvss,type,host)LIVE
POST /imports/qualysQualys VM CSV lub XMLLIVE
POST /imports/reYARA JSON / radare2 / generic RE (post-RoE)LIVE
POST /imports/defectdojoEksport DefectDojo (results[] / findings[] / tablica)LIVE
POST /imports/sarifSARIF 2.1 (CodeQL/Semgrep/GHAS)LIVE
POST /imports/sbomSBOM CycloneDX/SPDX (vulnerabilities)LIVE
POST /imports/secretsGitleaks/TruffleHog/GH secret scanning (redakcja wartości)LIVE
POST /imports/cloudProwler/ScoutSuite/Checkov/Trivy (tylko status FAIL)LIVE
POST /tools/dedupDeduplikacja cross-tool po fingerprincie (title|cve|host)LIVE

2.6 Statystyki / audyt

EndpointMetodaOpisRolaStatus
/statsGETAgregaty by_severity/by_status/gap z żywej bazy.dowolna rolaLIVE
/auditGETOstatnie 200 zdarzeń audytowych.auditor/adminLIVE
/audit/exportGETEksport audytu CSV/JSON (ostatnie 1000).auditor/adminLIVE
/audit/chain/verifyGETWeryfikacja spójności hash-chain audytu. 501 gdy IP3_AUDIT_CHAIN=off.auditor/adminLIVE za flagą shadow/on
/_healthGETStatus warstwy v1 (czy DB podłączona).publicznyLIVE

2.7 Raporty (evidence-package / podpis)

EndpointMetodaOpisRolaStatus
/reports/evidence-package/:idGETBoard pack: incydent+evidence+audit_trail+manifest+package_sha256+chain-of-custody. ?format=pdf → realny PDF. ?sign=true → podpis HMAC jeśli skonfigurowany klucz.operator/analyst/auditor/adminLIVE
/reports/verify-signaturePOSTWeryfikacja podpisu pakietu (stały czas, HMAC).auditor/adminLIVE

2.8 Engagements (DORA/TIBER white-team-log)

EndpointMetodaOpisRolaStatus
/engagementsPOST / GETUtworzenie/lista engagementów (scope, crown-jewels, RoE, framework domyślnie TIBER-EU).POST: operator/admin · GET: dowolna rolaLIVE
/engagements/:idGETSzczegóły + rejestr dowodów (evidence_register).dowolna rolaLIVE
/engagements/:id/logPOSTWpis white-team-log / evidence-register / phase / finding.operator/analyst/adminLIVE
/engagements/:id/final-reportPOSTRaport końcowy — wymaga ≥1 wpisu evidence-register (claim≤proof), inaczej 422.operator/adminLIVE
/engagements/:id/report-packageGETPakiet raportu TLPT: timeline+register+final+manifest+package_sha256. ?format=pdf dostępny.operator/analyst/auditor/adminLIVE
Warstwa demo (/api/ip3, routes/ip3-demo-api.js). Osobny router mirror-uje pełny kontrakt §6 (auth/incidents/findings-imports/evidence/retest/legal/dora/tiber/reports) w pamięci procesu (bez PostgreSQL, bez trwałości między restartami). Przydatny do integracji/testów klienta bez zakładania konta v1 — dane zawsze oznaczone source:"simulation". Montowany po endpointach read-path (pierwszeństwo inline GET-ów), więc nie nadpisuje ich. Status: SIMULATION, produkcyjny odpowiednik = warstwa v1 opisana wyżej.

3. Konektory / parsery — format wejścia i status

Wspólna zasada: parser = LIVE (realny kod, bez zależności npm, testowany), transport wysyłkowy do systemów zewnętrznych (Jira/GitHub/webhook) = builder LIVE, realna wysyłka sieciowa za flagą (potrójna bramka: ?send=true + IP3_<SYSTEM>_TRANSPORT=on + sekrety klienta w fly secrets). Domyślnie transport = off, zero egress.

KonektorModułWejścieStatus parsera
Burp Suiteip3-parsers.jsXMLLIVE
OWASP ZAPip3-parsers.jsJSON / XMLLIVE
Nessus / Tenableip3-parsers.jsCSVLIVE
Generic CSVip3-parsers.jsCSV z nagłówkamiLIVE
Qualys VMip3-parsers-ext.jsCSV / XMLLIVE
DefectDojoip3-defectdojo.jsJSON (results[]/findings[]/tablica)LIVE
SARIF (CodeQL/Semgrep/GHAS)ip3-sarif.jsSARIF 2.1 JSONLIVE
SBOM (CycloneDX/SPDX)ip3-sbom.jsJSONLIVE
Secret scanning (Gitleaks/TruffleHog/GH)ip3-secrets.jsJSON/NDJSON, redakcja wartościLIVE
Cloud posture (Prowler/ScoutSuite/Checkov/Trivy)ip3-cloud-posture.jsJSON, tylko FAILLIVE
Reverse engineering (YARA/radare2)ip3-re.jsYARA JSON / generic RE JSONLIVE defensywnie, po RoE
Dedup cross-toolip3-dedup.jstablica findingówLIVE
Transport GitHub Issuesip3-transport.jspayload z ip3-ticketing.jsbuilder LIVE / wysyłka za flagą IP3_GITHUB_TRANSPORT
Transport Jiraip3-transport.jspayload z ip3-ticketing.jsbuilder LIVE / wysyłka za flagą IP3_JIRA_TRANSPORT
Transport webhookip3-transport.jsJSON ip3.incident.v1builder LIVE / wysyłka za flagą IP3_WEBHOOK_TRANSPORT

Każdy import = MEDIA_SIGNAL (sygnał narzędzia), nigdy dowód naprawy. Zamknięcie incydentu zawsze wymaga osobnego kroku z evidence CONFIRMED — parser tego nie omija.

4. Moduły backendu (routes/ip3-*.js)

ModułRolaStatus
ip3-api-pro.jsGłówny router v1 — auth/RBAC/rate-limit/audit + montaż wszystkich sekcji poniżej.LIVE
ip3-demo-api.jsMirror kontraktu §6 w pamięci (bez DB) — testy integracyjne klienta.SIMULATION
ip3-parsers.jsParsery Burp/ZAP/Nessus/generic CSV.LIVE
ip3-parsers-ext.jsRozszerzenie — parser Qualys (CSV/XML).LIVE
ip3-sarif.jsParser SARIF 2.1.LIVE
ip3-sbom.jsParser SBOM CycloneDX/SPDX (CRA-alignment).LIVE
ip3-secrets.jsParser skanerów sekretów, redakcja wartości.LIVE
ip3-cloud-posture.jsParser postury chmury (Prowler/ScoutSuite/Checkov/Trivy).LIVE
ip3-defectdojo.jsParser eksportu DefectDojo (most AppSec).LIVE
ip3-re.jsParser findingów RE/malware (YARA/radare2/generic).LIVE
ip3-dedup.jsSilnik deduplikacji cross-tool (fingerprint title|cve|host).LIVE
ip3-enrich.jsWzbogacanie CVE offline (CVSS/KEV/EPSS hint ze statycznego seedu).LIVE offline-seed
ip3-mitre.jsKuratorowana podmapa MITRE ATT&CK + heurystyka mapowania.LIVE
ip3-control-map.jsMapowanie evidence→control (ISO27001/NIST-CSF/CIS/DORA/NIS2).LIVE
ip3-legal.jsLegal Trigger Engine (obowiązki + zegary). Decision-support.LIVE
ip3-ticketing.jsBuildery payloadów Jira/GitHub Issues (nie wysyłają).LIVE
ip3-transport.jsRealny transport (GitHub/Jira/webhook) za potrójną bramką flag.LIVE wysyłka: ROADMAP domyślnie off
ip3-oidc.jsWalidacja OIDC (RS256+JWKS), tryb off/shadow/on.MVP shadow na staging
ip3-tenancy.jsIzolacja multi-tenant warstwa 1 (scoping org_id), tryb off/on.MVP warstwa 1 z 2 (RLS = ROADMAP)
ip3-audit-chain.jsNiezmienny (tamper-evident) log audytowy jako hash-chain, tryb off/shadow/on.MVP shadow na staging
ip3-audit-export.jsFormatter audit log → CSV/JSON (czysta funkcja, bez DB).LIVE
ip3-pdf.jsBezzależnościowy generator PDF (Helvetica, paginacja) — board pack.LIVE
ip3-input-guards.jsBiblioteka guardów wejścia (CSV/formula injection, XXE, oversize). Nie wpięta do routera — dostępna jako moduł.ADDITIVE, wiring = ROADMAP
ip3-schema.jsGeneratory JSON-LD (breadcrumb/FAQ/Article) dla SEO stron ipIII.LIVE
ip3-seo.jsSitemap/seo-policy/llms.txt — kanon pages.json steruje indeksacją.LIVE

5. Warstwy backend za flagami (F1–F4)

Każda warstwa jest additive (nowa tabela/pole obok istniejących, zero zmian domyślnego zachowania) i sterowana zmienną środowiskową z trzema trybami: off (dziś domyślnie na prod) → shadow (loguje/waliduje równolegle, nie zmienia dostępu) → on (egzekwuje).

WarstwaFlaga (env)Co robiStan dziś
F1 — OIDCIP3_OIDCWalidacja tokenu OIDC (RS256+JWKS) obok JWT lokalnego; docelowo Keycloak/IdP zewnętrzny.shadow — staging
F2 — hash-chain + podpisIP3_AUDIT_CHAIN, IP3_SIGNING_KEYTamper-evident log audytowy (modyfikacja wykrywalna, nie „nieusuwalna"); opcjonalny podpis HMAC pakietu evidence.shadow — prod bez klucza: sygnatura niedostępna, jawna nota
F3 — tenancy warstwa 1IP3_TENANT_SCOPEScoping zapytań po org_id w warstwie aplikacji (app-level). Warstwa 2 (PostgreSQL RLS) = ROADMAP.off/on — staging (w1)
F4 — transportIP3_GITHUB_TRANSPORT, IP3_JIRA_TRANSPORT, IP3_WEBHOOK_TRANSPORTRealna wysyłka ticketów (GitHub Issues/Jira/webhook) — potrójna bramka: intencja + flaga + sekrety.off domyślnie — staging test

Sekrety wymagane do działania warstwy v1: JWT_SECRET (fail-closed bez niego — brak fallbacku na znany sekret), DATABASE_URL (PostgreSQL), opcjonalnie IP3_SEED_PASS (tworzy konta demo tylko gdy ustawiony jawnie).

6. MCP (Model Context Protocol)

Uczciwie: dziś nie ma dedykowanego /api/ip3/mcp. Istnieje jeden ogólny connector MCP na poziomie całego węzła K0NSULT pod adresem /mcp (nie w namespace ipIII). Zestaw narzędzi ipIII-scoped (list_incidents/stats/playbooks/doctrine) nie istnieje jeszcze w kodzie — to ROADMAP, nie funkcja LIVE.

6.1 Co jest LIVE dziś: /mcp (ogólny connector, read-only)

Streamable HTTP / JSON-RPC 2.0, bez autoryzacji, dane z żywej bazy (rejestr agentów K0NSULT, nie dane ipIII). Zaimplementowane w server.js.

Metoda JSON-RPCNarzędzie (tool)OpisStatus
initializeHandshake protokołu (protocolVersion 2024-11-05).LIVE
tools/listZwraca listę 3 narzędzi poniżej.LIVE
tools/callk0nsult_statusLiczba agentów w rejestrze (live z bazy) + znacznik czasu.LIVE
tools/calllist_agentsLista agentów (nazwa/model/provider/poziom ryzyka), limit domyślnie 50/max 250.LIVE
tools/callquery_agentsFiltr agentów po nazwie/modelu/providerze/poziomie ryzyka.LIVE

Jak podpiąć jako serwer MCP (np. Mistral le Chat / Claude Desktop) dziś: dodaj serwer typu Streamable HTTP pod adresem https://k0nsult.cloud/mcp (metoda POST, brak nagłówka autoryzacji wymaganego). To connector rejestru agentów K0NSULT — nie ma dostępu do incydentów/evidence ipIII.

POST https://k0nsult.cloud/mcp
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

6.2 ROADMAP: MCP scoped do ipIII

Zestaw narzędzi tego samego wzorca (list_incidents, stats, playbooks, doctrine) zasilany z /api/ip3/incidents i /api/ip3/stats (read-path, SIMULATION) jest zaplanowany, ale nieobecny w kodzie. Nie mylić z osobną, planowaną stroną MCP/Tool Poisoning Scanner (F9 AI-security — inwentaryzacja i wykrywanie zatruwania narzędzi MCP u agentów klienta, inny cel: kontrola bezpieczeństwa agentów AI, nie connector danych ipIII). Obie linie są odrębne i nie należy ich mylić.

7. Rejestry maszynowe

RejestrURLCelStatus
Strony modułu/ai-truth/ipIII/pages.jsonWszystkie strony PL+EN ze statusem produktu (LIVE/DANE/MVP/ROADMAP/SIMULATION/NOINDEX).LIVE
Kontrakt API/ai-truth/ipIII/openapi.jsonOpenAPI 3.1 referencyjny — read-path + wybrane v1, z jawnym x-status per operacja.LIVE
Sitemap/ai-truth/ipIII/sitemap.xmlWyłącznie strony indeksowalne — kanon pages.json steruje wpisem.LIVE
Manifest GEO (moduł)/ai-truth/ipIII/llms.txtOpis dla modeli/agentów czytających portal — zakres ipIII.LIVE
Manifest GEO (portal)/llms.txtOpis całego węzła k0nsult.cloud.LIVE
Polityka SEO/ai-truth/ipIII/seo-policy.jsonCo indeksowane, co noindex i uzasadnienie (ROADMAP/SIMULATION nigdy w sitemap).LIVE

Szybki start dla integratora

1. Uwierzytelnij się: POST /api/ip3/v1/auth/login z email+hasłem konta demo (wymaga IP3_SEED_PASS ustawionego przez operatora środowiska) → JWT ważny 1h.
2. Zaimportuj raport skanera: POST /api/ip3/v1/imports/<narzędzie> (np. burp, sarif, defectdojo) z nagłówkiem Authorization: Bearer <token>.
3. Dodaj dowód potwierdzający naprawę: POST /incidents/:id/evidence, następnie zamknij: POST /incidents/:id/close (blokowane bez evidence CONFIRMED).
4. Wygeneruj board pack: GET /reports/evidence-package/:id?format=pdf — hash package_sha256 w nagłówku X-Package-Sha256.
curl -s https://k0nsult.cloud/api/ip3/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"operator@ip3.demo","password":"<IP3_SEED_PASS>"}'

curl -s https://k0nsult.cloud/api/ip3/v1/reports/evidence-package/IP3-2026-0001 \
  -H "Authorization: Bearer <token>"
Ta strona nie zastępuje kontraktu OpenAPI. Dla maszynowego parsowania użyj /openapi.json. Ta strona jest czytelnym indeksem dla człowieka — developera oceniającego integrację, nie SLA ani dokumentem prawnym.
Granica etyczna i prawna. ipIII jest narzędziem obrony i zgodności (GRC/blue). Konektory importują wyniki narzędzi już posiadanych przez klienta (Burp/ZAP/Nessus/Qualys/SARIF/SBOM/DefectDojo/RE) — nie wykonują skanów ani exploitacji. Legal Trigger Engine oraz mapowania obowiązków to wsparcie decyzji, nie porada prawna; kwalifikacja przez radcę/kancelarię przed wysyłką do organu.

Powiązane: pełna roadmapa 7 sprintów z dowodami → /roadmap-dev · rejestr znanych ograniczeń → /known-limitations · macierz statusów wszystkich elementów → /status-matrix · interaktywny eksplorator API → /api-explorer.