Specyfikacja kontraktu, jaki musi spełnić każdy konektor Evidence & Resilience Orchestrator: input → normalizacja → evidence. To nie jest ogłoszenie gotowego pakietu — SDK jako wydawany artefakt (npm/CLI/plugin registry) nie istnieje. Istnieją za to działające parsery referencyjne w kodzie serwera (Burp/ZAP/Nessus/Qualys/generic), z których ta specyfikacja jest wyprowadzona.
Każdy parser (istniejący lub przyszły) przyjmuje surowe dane narzędzia (XML/JSON/CSV) i zwraca tablicę znormalizowanych
obiektów finding o stałym kształcie pól. Warstwa Evidence dokleja hash, chain-of-custody i status pewności —
parser nie decyduje o priorytecie incydentu ani nie wykonuje żadnego testu; tylko tłumaczy format.
Parser to czysta funkcja: raw → finding[]. Brak efektów ubocznych, brak zapisu do bazy, brak sieci —
to zadanie warstwy Normalize/Evidence, nie parsera. Poniżej kształt obiektu finding, wspólny dla wszystkich
parserów referencyjnych dzisiaj (wyprowadzony z routes/ip3-parsers.js i routes/ip3-parsers-ext.js).
// Kontrakt (spec, nie pakiet do instalacji) — kształt zwracany przez każdy parser
type Finding = {
title: string, // wymagane; nazwa podatności/ustalenia
severity: 'P0'|'P1'|'P2'|'P3', // znormalizowane z tekstu/skali narzędzia (critical/high/.../riskcode 0-3/1-5)
cve: string | null, // CVE-YYYY-NNNNN lub CWE-NNN, pierwszy dopasowany
cvss: string | null, // surowy score, jeśli źródło go podaje (nie przeliczany)
incident_type: string, // domyślnie 'podatnosc'
description: string, // odkodowany tekst (bez XML/CDATA), skrócony
host: string // adres/hostname/IP celu z raportu narzędzia
};
// Sygnatura funkcji parsera (przykład: Qualys XML, routes/ip3-parsers-ext.js)
function parseQualysXml(xml: string): Finding[]
// Zasada: parser NIE łączy się z siecią, NIE wykonuje testu, NIE zapisuje do DB.
// To zadanie warstwy Normalize (dedup/hash/severity) i Evidence (chain-of-custody).
Finding — wzorem parseGenericCsv (tolerancyjne nazwy nagłówków: title|name|finding|vulnerability|issue).normSev() (tekst critical/high/medium/low + numeryczne skale narzędzia, np. ZAP riskcode 0-3, Qualys 1-5) zamiast pisać własną tabelę od zera.Zgodnie z regułą „bez kodu + testu + endpointu = nie LIVE": poniższe parsery działają w kodzie serwera i mają testy jednostkowe/integracyjne. To nie jest wydany pakiet SDK — to wewnętrzne moduły, z których wyprowadzono kontrakt powyżej.
| Parser | Format wejścia | Moduł (kod) | Test | Status |
|---|---|---|---|---|
| Burp Suite | XML (<issues><issue>) | routes/ip3-parsers.js parseBurpXml | tests/ip3-parsers-ext.unit.js i pokrewne | LIVE v1 |
| OWASP ZAP | JSON + XML (alertitem) | routes/ip3-parsers.js parseZapJson/parseZapXml | unit | LIVE v1 |
| Nessus / Tenable | CSV | routes/ip3-parsers.js parseNessusCsv | unit | LIVE v1 |
| Qualys VMDR | CSV + XML | routes/ip3-parsers-ext.js parseQualysCsv/parseQualysXml | unit | LIVE v1 |
| Generic CSV | CSV (nagłówki elastyczne) | routes/ip3-parsers.js parseGenericCsv | unit | LIVE v1 |
| SARIF (SAST/CI) | JSON (OASIS SARIF) | routes/ip3-sarif.js | tests/ip3-sarif.unit.js | LIVE v1 |
| SBOM (CycloneDX) | JSON | routes/ip3-sbom.js | tests/ip3-sbom.unit.js | LIVE v1 |
| Reverse/malware (YARA/RE) | JSON | routes/ip3-re.js | tests/ip3-re.unit.js | LIVE v1 |
Poniżej dokładnie to, czego brakuje, żeby powyższe moduły stały się publicznie wydawanym SDK zamiast wewnętrznych plików serwera.
| Element | Opis | Priorytet | Status |
|---|---|---|---|
| Pakiet npm/CLI | Samodzielny pakiet do instalacji poza repo serwera, z wersjonowaniem semver. | P1 | ROADMAP |
| Generator szkieletu konektora | CLI ip3 connector init tworzące szkielet parsera + fixture + test z szablonu. | P1 | ROADMAP |
| Plugin registry | Rejestr zewnętrznych konektorów z podpisem/weryfikacją pochodzenia (supply-chain dla samych parserów). | P2 | ROADMAP |
| Walidator kontraktu | Automatyczne sprawdzenie, że zwrócony Finding[] spełnia schemat (typ pól, wymagane title/severity). | P1 | ROADMAP |
| Dokumentacja API referencyjna (typedoc) | Wygenerowana dokumentacja z komentarzy kodu zamiast ręcznie pisanej specyfikacji. | P2 | ROADMAP |
| Konektory push (SIEM/ticketing/BAS) | Splunk, Sentinel, Jira, ServiceNow, MISP/OpenCTI, BAS — patrz /connectors po pełną listę i priorytety. | P0/P1 | ROADMAP |
Parser przyjmuje wynik narzędzia uruchomionego przez klienta w jego środowisku. Nigdy nie inicjuje skanu, nie wysyła pakietów do celu, nie zawiera exploitów.
Fixture testowe = dane demo/syntetyczne, bez rzeczywistych adresów/klientów. Zero payloadów ofensywnych w repo.
Konektor przyjmuje dane wyłącznie w granicach pisemnych Rules of Engagement. Brak RoE = brak przyjęcia źródła.
Nowy parser jest „LIVE" dopiero z kodem + testem jednostkowym + (docelowo) endpointem importu — wcześniej to szkic/ROADMAP, nie funkcja.
Powiązane: pełna lista konektorów i formatów wymiany → /connectors · warstwa normalizacji (dedup/hash/severity) → /normalize · macierz statusów wszystkich elementów → /status-matrix.