badBANANA // BEDROHUNGS-OBSERVATORIUM

Ein belegorientiertes Bedrohungsbeobachtungssystem, das den aktuellen Quellenzustand, Ereignisse materieller Änderungen und operative Abruftelemetrie semantisch getrennt hält. Fehlende, veraltete, deaktivierte oder nicht verfügbare Daten bleiben sichtbar fehlend. Die Oberfläche ersetzt niemals Demo-Datensätze oder abgeleitete Zuordnungen.

Die aktuelle Version härtet Belegdaten und den gerätelokalen Bestätigungszustand ab, macht alle wichtigen Lesefehler sichtbar von erfolgreichen Null-Ergebnis-Zuständen unterscheidbar, stabilisiert Korrelationsanfragen und stärkt den Evidenzbereich, begrenzte Untersuchungsfilter, Quelleninterpretation, mobile Bedienelemente und die Exportabrechnung. Jede animierte Replay-Markierung entspricht weiterhin einem gespeicherten NEW-, UPDATED- oder REMOVED-Ereignis; es handelt sich nicht um dekorativen Netzwerkverkehr.

Produktionsansichten

Pulse — quellenübergreifende Beziehungen, Quellengesundheit und Analyse des aktuellen Zustands.

Replay — seitenbegrenzte Rekonstruktion gespeicherter NEW-, UPDATED- und REMOVED-Übergänge.

Weitere Live-Oberflächen umfassen die ungefähre Infrastruktur-Geografie öffentlicher IP-Adressen sowie First-Party-Evidenzansichten von URLhaus / MalwareBazaar. Diese Oberflächen sind in dieser README bewusst nicht durch Platzhalter- oder duplizierte Screenshots dargestellt.

Produktionsaufnahmen sind quellenerhaltende Screenshots des Live-Observatoriums v1.2.0. Sie werden für die Präsentation beschnitten und in der Größe verändert/komprimiert; angezeigte Belege, Zeitstempel, Zähler, IOC-Werte und Oberflächenzustände werden nicht neu generiert oder ersetzt.

Live-Bereitstellung

• Produktion: https://badbanana-threat-observatory.badbanana6969.workers.dev
• Aktueller Quellcode: https://github.com/GnomeMan4201/badBANANA-threat-observatory/tree/main
• Eingefrorener v1.2.0-Quellcode: https://github.com/GnomeMan4201/badBANANA-threat-observatory/tree/release/v1.2.0

Der Produktions-Worker wird von Cloudflare D1 unterstützt. Feed-Anmeldedaten bleiben ausschließlich serverseitige Cloudflare-Worker-Geheimnisse und werden im Browser niemals benötigt.

Versionsstatus

• Version: 1.2.0
• Laufzeitumgebung: Node.js 22.13.0 oder neuer
• Bereitstellung: Next.js auf Cloudflare Workers über vinext und das Cloudflare-Vite-Plugin
• Persistenz: Cloudflare D1 mit explizit gekennzeichneter Isolate-Speicherabstufung
• Prüfung der Produktionsabhängigkeiten: in CI bei hohem Schweregrad erzwungen

Ingestion-Modus

Diese Bereitstellung läuft im demand-driven-Modus. Das Repository zielt nun direkt auf Standard-Cloudflare-Workers ab; geplante Trigger sind in v1.2.0 absichtlich nicht aktiviert, sodass die Anwendung keine kontinuierliche Erfassung beansprucht. Ein zukünftiger Scheduler kann nach separater Korrektheits- und Betriebsverifizierung denselben runIngestionCycle()-Vorgang aufrufen.

Der Browser stellt bei der ersten Nutzung und danach alle fünf Minuten, solange er geöffnet ist, eine explizite begrenzte Wartungsanfrage:

POST /api/ingest
        ↓
runIngestionCycle()
        ↓
configuration → TTL → backoff → D1 lease → fetch → normalize → validate
        ↓
snapshot cache + current observations + material events + cycle statistics

Gewöhnliche Lesevorgänge sind separat und lokal:

GET /api/observations → D1 current state, scoped before pagination
GET /api/search       → D1 current state, scoped before pagination
GET /api/kev          → D1 current CISA catalog
GET /api/events       → D1 material change ledger
GET /api/geo          → local observations + bounded cached IP enrichment

Keine dieser GET-Routen ruft einen Quelladapter auf. Falls dieses Projekt später einen tatsächlich unterstützten Scheduler erhält, kann dieser denselben runIngestionCycle()-Vorgang aufrufen, ohne eine zweite Aktualisierungsimplementierung zu erstellen.

Quellenabdeckung

Die Abdeckung wird pro Quelle angezeigt. Begrenzte APIs werden niemals als vollständige Kataloge dargestellt.

Speichermodell

Die DB-Bindung verwaltet getrennte Datensätze:

• threat_source_cache und threat_source_cache_chunks: der neueste validierte Schnappschuss pro Quelle, gespeichert in generationsgebundenen Blöcken.
• observations: neuester normalisierter aktueller Zustand pro stabiler Quellenidentität. Er bewahrt erste Ingestion, neueste Quellensichtung, letzte materielle Änderung, aktuellen Hash, Revisionsanzahl und neuestes Ingestion-Ergebnis.
• observation_events: bedeutsame NEW-, UPDATED- und vertretbare REMOVED-Belegereignisse. Vorherige und aktuelle normalisierte Nutzlasten, Hashes und deterministische Felddiffs machen frühere Zustände rekonstruierbar.
• source_fetch_log: begrenzte Telemetrie zu Abrufversuchen ohne Antwortkörper oder Anmeldedaten.
• source_ingest_cycles: begrenzte Zähler pro Aktualisierung für abgerufene, gültige, abgelehnte, neue, aktualisierte, unveränderte und entfernte Datensätze.
• source_refresh_lease: kurze, D1-gestützte Leases pro Quelle, die verhindern, dass gleichzeitige Isolate Upstream-Aktualisierungen duplizieren.
• ingestion_runtime: der neueste Gesundheitsstatus des gesamten Ingestion-Zyklus.

Laufzeitschemadefinitionen befinden sich in db/schema.ts. Die Initialisierung fügt einer vorhandenen Observations-Tabelle die neuen Spalten für den aktuellen Zustand hinzu, bevor abhängige Indizes erstellt werden.

Zustands- und Aufbewahrungssemantik

Diese Fragen sind absichtlich unterschiedlich:

1. Was sagt die Quelle jetzt? observations und der validierte Quellenschnappschuss beantworten dies.
2. Was hat badBANANA während dieses Quellenzeitfensters beobachtet? /api/observations?window=... filtert aktuelle Beobachtungen nach dem Upstream-observedAt.
3. Was hat sich zwischen Beobachtungen geändert? observation_events und /api/revisions beantworten dies.

Der aktuelle Zustand wird nicht fälschlich als Sieben-Tage-Verlaufstabelle beschrieben. Das Protokoll materieller Ereignisse wird sieben Tage lang aufbewahrt. Abruf- und Zyklustelemetrie wird zwei Tage lang aufbewahrt und auf 200 Zeilen pro Quelle begrenzt. Aktuelle Beobachtungen ohne Katalogcharakter, die sieben Tage lang nicht erneut aufgetaucht sind, werden entfernt. CISA bleibt aktuell, weil jede erfolgreiche Antwort ein vollständiger Katalog ist; aus diesem Katalog entfernte Zeilen bleiben vor dem Entfernen 30 Tage lang verfügbar. Nur das Fehlen bei CISA kann derzeit ein REMOVED-Ereignis erzeugen, da dessen Adapter einen vollständigen aktuellen Katalog abruft. Das Fehlen in begrenzten ThreatFox-, URLhaus- oder MalwareBazaar-Ergebnissen wird nicht als Löschung behandelt.

Eine unveränderte Sichtung aktualisiert das aktuelle lastObservedInSnapshotAt/lastIngestedAt, erzeugt jedoch kein Ereignis und erhöht revisionCount nicht. lastChangedAt überlebt spätere unveränderte Sichtungen.

CISA-Analystenarbeitsbereich

Die Exploited-Ansicht trennt:

• Aktueller KEV-Katalog: vollständiger validierter aktueller Zustand, unabhängig vom Dashboard-Zeitfenster.
• Kürzlich hinzugefügte KEV-Einträge: Datensätze, deren tagesgranulares CISA-dateAdded in einen expliziten TODAY-, 7D- oder 30D-Bereich fällt. Observatoriumsfenster unter einem Tag werden niemals als CISA-Präzision dargestellt.

Der aktuelle Katalog unterstützt serverseitige Suche, Filter für Anbieter, Produkt, neu hinzugefügt, Ransomware-Zuordnung und Hinzugefügt-Datum sowie undurchsichtige Cursor-Paginierung. Er zeigt CVE, Anbieter, Produkt, Schwachstellenname, Hinzugefügt-Datum, Fälligkeitsdatum, Ransomware-Zuordnung und erforderliche Maßnahme an. Er erfindet keine CVSS-Scores.

Änderungsprotokoll und Revisionen

Inhalts-Hashes decken normalisierte Belegfelder ab, nicht die Observatoriumsbuchhaltung. Ein geänderter Hash erzeugt ein UPDATED-Ereignis mit der vorherigen normalisierten Nutzlast, der neuen normalisierten Nutzlast, vorherigen/neuen Hashes und einem deterministischen Diff über:

• Titel
• Malware-Familie
• Bedrohungstyp
• Vertrauensgrad
• Quelle zuerst/zuletzt gesehen
• Tags
• Referenz
• normalisierte Metadaten-Schlüssel

Der Provenienzbereich fragt /api/revisions?id=... ab und legt aktuellen Hash, letzte materielle Änderung, Revisionsanzahl, gespeicherte Ereignisse und Feld-Diffs offen. Flüchtige Ingestion-Zeitstempel erscheinen nicht in Inhalts-Diffs.

Der Bereich legt außerdem für jeden akzeptierten Datensatz eine versionierte Belegspur offen: akzeptierte normalisierte Felder, optionale Felder, die nicht vorhanden blieben, reine Anzeigetransformationen, die Klassifizierungsgrundlage und die Grundlage der stabilen Identität. Diese Spur beschreibt nur gespeicherte Belege. Abgelehnte Upstream-Werte werden nicht gespeichert und erhalten niemals synthetische Observatoriums-Identitäten. Ablehnungen werden separat als aggregierte Zähler pro Zyklus mit begrenzten Feld- und Grundcodes dargestellt; alte Zyklen, die vor diesem Schema erfasst wurden, werden als ohne Aufschlüsselung gekennzeichnet, anstatt rekonstruiert zu werden.

Letzte Ereignisse zeigt nur materielle Änderungen an. Es werden keine Hunderte unveränderter SEEN-Zeilen nach einer vollständigen CISA-Aktualisierung ausgegeben. Diese Sichtungen werden in Quellenzyklus-Statistiken zusammengefasst.

Gerätelokales Briefing

Die standardmäßige Briefing-Ansicht vergleicht das gespeicherte Protokoll materieller Ereignisse mit einem versionierten Bestätigungs-Cursor, der nur im aktuellen Browser gespeichert ist. Erste Nutzung und geleerter Speicher werden als anfängliche Basislinie gekennzeichnet, nicht als neue Aktivität. Wenn ein gespeicherter Cursor älter ist als das gespeicherte Protokoll, gibt die Oberfläche an, dass ein vollständiges Delta nicht nachgewiesen werden kann.

Bestätigung mutiert oder löscht niemals Serverereignisse. Der Cursor kann für eine bewusste Geräteübertragung als JSON exportiert und importiert werden; er wird nicht als konto-synchronisierter Zustand dargestellt, und die erzeugte Gerätekennung wird niemals an den Server gesendet.

Briefing-Summen beschreiben die aktuell zurückgegebene Protokollseite und sind als angezeigt/seitenbegrenzt gekennzeichnet. Sie werden nicht als Summen für das vollständige gespeicherte Protokoll dargestellt.

Importierte Bestätigungszeitstempel werden vor der Speicherung oder dem Vergleich strikt validiert und auf UTC ISO-8601 kanonisiert. Die Browserspeicherung wird als optional behandelt: blockierter oder fehlgeschlagener lokaler Speicher erzeugt einen kompakten Inline-Fehler und lässt Briefing niemals abstürzen.

Richtliniengebundene Exporte

Die Export-Arbeitsumgebung formatiert die bereits geladene validierte sichtbare Seite als CSV, JSONL, STIX 2.1, defanged Text oder ein Belegmanifest, das die angewendete Richtlinie und verfügbare Datensatz-Hashes enthält. Die aktive lokale Suche und der Quellenbereich werden in den Export übernommen. Eine leere Quellen-Allowlist exportiert null Datensätze. STIX stellt CISA-CVEs als Vulnerability-Objekte und validierte Datei-Hashes—einschließlich MalwareBazaar-SHA-256-Werte—als Indicator-Objekte dar. Ausgewählte, ausgegebene und nicht unterstützte Zählungen sind getrennt; nicht unterstützte Datensätze werden in den Bundle-Metadaten offengelegt, anstatt stillschweigend verworfen zu werden. Der Export führt keine Upstream-Erfassung durch. Fehlendes Vertrauen bleibt fehlend, quellenübergreifende Abweichungen bleiben getrennte Datensätze, und entfernte Protokollereignisse gelangen niemals stillschweigend in Exporte des aktuellen Zustands. Diese Artefakte sind Belegtransporte, keine Firewall-Blockempfehlungen.

Backoff und Nebenläufigkeit

Abgelaufene Quellen verwenden begrenzte Wiederholungsverzögerungen von 1, 2, 5, 15 und 30 Minuten. Ein gültiger größerer Retry-After wird bis zu einer Stunde respektiert. Während des Backoffs wird ein gültiger früherer Schnappschuss als veraltet bereitgestellt; eine leere fehlgeschlagene Quelle bleibt offline.

Vor dem Abruf erwirbt eine berechtigte Quelle eine kurze bedingte D1-Lease. Ein anderes Isolate kann einen nicht abgelaufenen Inhaber nicht ersetzen, sodass nur eine Aktualisierung fortfährt. Wenn D1 nicht verfügbar ist, meldet das System explizit einen abgestuften Nur-Schnappschuss-Modus und eine Isolate-Speicher-Lease; dieser Fallback wird nicht als verteilt beschrieben.

Paginierung

Aktuelle Beobachtungen, quellenspezifische Arbeitsbereiche, lokale Suche, der CISA-Katalog, materielle Ereignisse und Datensatzrevisionen verwenden begrenzte serverseitige Cursor-Abfragen. Quellen- und Art-Einschränkungen werden vor Sortierung und Paginierung angewendet. Cursor kodieren das stabile Sortiertupel, werden auf Länge/Zeichen/Schema validiert und schlagen bei fehlerhafter Formatierung mit HTTP 400 fehl (Fail-Closed). Der Browser erhält niemals den vollständigen Sieben-Tage-Datensatz, nur um lokal zu paginieren.

Referenz- und IOC-Sicherheit

• IOC-URLs sind standardmäßig defanged und werden niemals als Anker gerendert.
• Referenzen müssen als HTTP oder HTTPS geparst werden können.
• Bekannte First-Party-Quellseiten von CISA und abuse.ch dürfen normal geöffnet werden.
• Beliebige Drittanbieter-HTTP(S)-Referenzen werden als extern gekennzeichnet, zeigen ihren Hostnamen an und bieten Nur-Kopieren-Verhalten.
• IPv4-Oktette, IPv6-Struktur, Ports, Domains, URLs und Hashes werden strikt validiert.
• MalwareBazaar bleibt rein Metadaten-basiert; es werden keine Samples heruntergeladen oder bereitgestellt.
• Alle Upstream-URLs werden serverseitig festgelegt; kein API-Proxy leitet benutzergelieferte Ziele weiter.

Ratenbegrenzung

Der API-Begrenzer ist ein In-Memory-Fixed-Window-Zähler, der auf ein Worker-Isolate begrenzt ist. Er wird korrekt als Best-Effort-Isolate-lokaler Schutz gemeldet, nicht als global maßgebliche Cloudflare-Ratenbegrenzung. Gewöhnliche Lesevorgänge sind auf 120 Anfragen pro Minute pro gemeldeter Client-IP begrenzt; Ingestion hat einen separaten Bucket mit sechs Anfragen pro Minute und Geografie einen separaten Bucket mit zwölf Anfragen pro Minute. D1-Schreibvorgänge werden nicht zu jedem Lesevorgang hinzugefügt, nur um diese Kontrolle zu übertreiben.

API

• POST /api/ingest — expliziter bedarfsgesteuerter Wartungszyklus; respektiert TTL, Backoff und D1-Leases.
• GET /api/observations?window=24h&scope=urlhaus&limit=100&cursor=... — paginiertes lokales Fenster des aktuellen Zustands; validierte Bereiche sind all, urlhaus, malwarebazaar und infrastructure.
• GET /api/search?q=indicator&window=24h&scope=urlhaus&limit=100&cursor=... — paginierte bereichsbegrenzte lokale Suche; null Upstream-Aufrufe.
• GET /api/kev?limit=50&q=...&vendor=...&product=...&ransomware=known&addedSince=YYYY-MM-DD&cursor=... — vollständiger aktueller CISA-Katalog.
• GET /api/events?limit=50&cursor=... — Protokoll materieller Ereignisse.
• GET /api/revisions?id=...&limit=50&cursor=... — aktueller Datensatz plus gespeicherte Revisionen.
• GET /api/correlations?id=... — Peers mit exaktem Indikator des aktuellen Zustands auf Datensatzebene.

Umgebung und Bereitstellung

Die lokale Cloudflare-Entwicklung liest ausschließlich serverseitige Anmeldedaten aus .dev.vars. Kopieren Sie .dev.vars.example nach .dev.vars und füllen Sie nur die Feeds aus, die Sie verwenden dürfen:

THREATFOX_AUTH_KEY=
URLHAUS_AUTH_KEY=
MALWAREBAZAAR_AUTH_KEY=

Produktionsanmeldedaten müssen als Cloudflare-Worker-Geheimnisse gespeichert werden, niemals als committeter Quellcode oder GitHub-Variablen, die dem Client zugänglich sind. Die Anwendung greift nur über die Workers-Runtime-Bindungsoberfläche auf sie zu. Sie dürfen niemals in NEXT_PUBLIC_*, Client-Komponenten, HTML, Protokollen, Fixtures oder committeten Dateien erscheinen.

Das Repository zielt direkt auf Standard-Cloudflare-Workers ab. wrangler.jsonc ist die maßgebliche Quelle der Worker-Konfiguration und deklariert eine vorläufige D1-Bindung namens DB. Wrangler 4 stellt diese D1-Ressource bei der ersten authentifizierten Bereitstellung automatisch bereit und hält die Bindung bei späteren Bereitstellungen verknüpft. Es wird keine kontospezifische D1-Kennung committet.

Entwicklungs- und Produktionsbefehle:

npm ci
npm run dev
npm run build
npm run preview
# authenticated Cloudflare session / CI only
npm run deploy

Die GitHub-Actions-Verifizierung läuft bei jedem Pull-Request und Push auf main. Die Produktionsbereitstellung erfolgt bewusst manuell über den Workflow deploy production und erfordert Repository-Geheimnisse namens CLOUDFLARE_API_TOKEN und CLOUDFLARE_ACCOUNT_ID. Dies verhindert, dass ein ungeprüfter Zweig oder eine unvollständige Anmeldedatenkonfiguration automatisch veröffentlicht.

Verifizierung

npm ci
npm audit --omit=dev --audit-level=high
npm audit --audit-level=high
npm test
npm run lint

npm test ist der unterstützte Testeinstiegspunkt: Er führt vor der deterministischen Suite einen vollständigen Produktions-Build aus, damit die Client-Geheimnisisolierung auf Artefaktebene dist/client prüfen kann. Die direkte Ausführung von node --test gegen ein sauberes Checkout lässt dieses erforderliche Build-Artefakt absichtlich aus. Die Tests decken ab: striktes Kalender- und Bestätigungszeitstempel-Parsing, optionale Gerätespeicherung, stabile Korrelationsabhängigkeiten, normalisierte Belege, kanonisches Tag-Hashing, Erstellung materieller Ereignisse, unveränderte Wiederingestion, Erhaltung vorheriger Nutzlasten, Dauerhaftigkeit der letzten Änderung, Feld-Diffs, Ereignisaufbewahrung und Protokolllücken, Belegspuren, Exportrichtlinie bei leerer Quelle, STIX-Darstellung/Zählintegrität, TTL/Backoff-Berechtigung, Aktualisierungs-Leases, serverseitige Scope-vor-Paginierung-Verdrahtung, dedizierte GEO/Recent-KEV-Abfragen, Cursor-Validierung, Lesepfad-Isolation, Quellenabdeckung, externe Referenzrichtlinie, Ratenbegrenzungsgenauigkeit, Quellfehlerisolation und Client-Geheimnisisolierung.

Geografische Anreicherung

Der GEO-Modus zeichnet nur validierte öffentliche IPv4/IPv6-Beobachtungen ein. Eine dedizierte D1-Abfrage wählt berechtigte IP-Datensätze über das angeforderte Fenster des aktuellen Zustands aus, anstatt die generische Observations-Seite wiederzuverwenden. Die Antwort meldet Gesamtzahlen der Kandidatendatensätze und ob ihre Sicherheitsgrenze von 2.000 Datensätzen erreicht wurde. Aufrufer können keine beliebigen Upstream-Ziele oder IP-Listen angeben. GeoJS ist der feste primäre Anbieter und FreeIPAPI der feste Fallback; beliebige Upstream-URLs sind unmöglich. Die Anwendung begrenzt externe Arbeit durch eine Obergrenze von 12 Adressen pro Anfrage, einen 30-Tage-D1-Erfolgscache, einen Fünf-Minuten-Wiederholungscache und einen dedizierten Routenbegrenzer. Jeder eingezeichnete Punkt behält seine tatsächliche Anbieter-Provenienz und kann seinen zugrunde liegenden lokalen Datensatz öffnen.

Lizenz

Veröffentlicht unter der MIT-Lizenz. Siehe LICENSE.

Die Auswahl des GEO-Modus bewirkt, dass der Server jeden validierten öffentlichen IP-Kandidaten zusammen mit gewöhnlichen HTTPS-Anfragemetadaten an GeoJS und dann an FreeIPAPI sendet, wenn ein Fallback erforderlich ist. Diese Anbieter können daher beobachten, welche öffentlichen Adressen abgefragt werden. Private, reservierte, Dokumentations- und vom Client gelieferte Adressen werden niemals gesendet; der Beziehungsmodus führt keine Geolokalisierungsanfragen durch.

Der Replay-Arbeitsbereich rekonstruiert die aktuelle Seite materieller Protokollübergänge in der Detektionszeitreihenfolge des Observatoriums. Die NEW-, UPDATED- und REMOVED-Bewegung wird ausschließlich von gespeicherten Ereignissen gesteuert. Er ist ausdrücklich seitenbegrenzt und beansprucht nicht, einen vollständigen historischen Schnappschuss oder ein Netzwerkverkehrsvolumen zu rekonstruieren.

Das von Natural Earth abgeleitete Paket world-atlas liefert die lokale Basiskarte. Die Karte gruppiert kollokierte IPs, unterstützt Hover-Details und Durchklicken zur Provenienz und meldet geolokalisierte, ausgeschlossene, nicht verfügbare und ausstehende Zählungen. Private, reservierte, Dokumentations-, Multicast- und anderweitig nicht öffentliche Bereiche werden vor jedem Anbieteraufruf ausgeschlossen.

IP-Geolokalisierung wird ausdrücklich als ungefährer Infrastrukturstandort dargestellt. Sie ist keine Akteursposition, kein Ereignisursprung, keine Nationalität, kein Eigentumsbefund und keine Zuordnungsbehauptung. Fehlgeschlagene Anreicherung bleibt abwesend; die Anwendung erzeugt niemals Ersatzkoordinaten.

Die Standardvisualisierung bleibt ein interaktives kraftgerichtetes Feld einzelner Beobachtungen, die mit ihrer Quelle und der ausdrücklich gelieferten Malware-Familie verknüpft sind. Die Leinwand unterstützt Knotenziehen, Feldverschiebung, Zoom, animierten Linkverkehr und direkte Provenienzinspektion. GEO ist eine separate Belegoberfläche mit eigener Provenienz- und Fehlersemantik.