Technologie & Algorithmen
Ein tiefer Einblick in die Architektur, die RAG-Pipeline und die mathematisch-technischen Modelle hinter Balou Tools.
Begriffe oder Abkürzungen unklar? → Zum Glossar
Systemarchitektur & High-Level Datenfluss
Balou Tools ist als hochperformante, moderne Developer Diagnostic Platform konzipiert. Die Systemarchitektur trennt strikt das statisch optimierte, reaktive Frontend von einem zustandslosen (stateless) Spring-Boot-Backend. Zur Parallelisierung externer Netzwerkanfragen nutzt das Backend virtuelle Threads.
Architektur-Prinzipien:
- Virtual Threads (Java 25): Ermöglichen es, für jede blockierende I/O-Aktion (DNS-Abfragen, SSL-Handshakes, HTTP-Aufrufe) einen eigenen leichtgewichtigen Thread zu starten. Dadurch wird der klassische Thread-Pool-Flaschenhals eliminiert.
- Privacy-First & Local Execution: Werkzeuge zur Textmanipulation, Hashing, Base64-Codierung, JWT-Decodierung und Generatoren laufen zu 100% clientseitig im Browser des Nutzers. Es findet kein Datentransfer dieser sensiblen Nutzdaten an Server statt.
- Cache-First: Reduktion von Latenzzeiten und API-Kosten durch eine mehrstufige Cache-Infrastruktur (In-Memory Caffeine Cache und verteilter Redis Cache).
Technologie-Stack
Die Komponenten von Balou Tools basieren auf etablierten und zukunftssicheren Core-Technologien mit Fokus auf SEO-Performance, Robustheit und extrem kurzen Ladezeiten.
| Bereich | Technologie | Version | Zweck / Funktion |
|---|---|---|---|
| Frontend | Astro Framework | 6.4.x | Meta-Framework für Static Site Generation (SSG) & SSR, SEO-Optimierung |
| Client-UI | Svelte | 5.55.x | Interaktive, reaktive UI-Inseln unter Verwendung der neuen Runes-API |
| Backend | Spring Boot | 4.0.6 | REST-APIs, Dependency Injection, System-Orchestrierung |
| Sprache | Java / TypeScript | 25 / 6.0 | Virtual Threads, Records, Typsicherheit in Frontend und Backend |
| KI-Integration | Spring AI | 2.0.0-RC1 | Standardisierte Abstraktion für Vektordatenbanken und LLM-Aufrufe |
| Sprachmodell | Google Gemini | API | LLM: gemini-2.5-flash-lite · Embeddings: gemini-embedding-001 |
| Datenbank | PostgreSQL + pgvector | 16+ | Relationaler Datenspeicher & Vektordatenbank (HNSW-Indizes, 768 Dimensionen) |
| Caching | Caffeine & Redis | 7.x | Lokal extrem schneller In-Memory-Cache & verteilter Cache für Skalierung |
KI- & RAG-Pipeline
Die KI-gestützte Fehlerdiagnose basiert auf einer Retrieval-Augmented Generation (RAG) Pipeline. Sie reichert die Rohdaten der Diagnostics-Tools mit spezifischem Kontext aus der internen Balou-Wissensdatenbank an.
≥ 95% wird geprüft, ob eine semantisch identische Frage bereits beantwortet wurde. Bei einem Treffer wird direkt die gecachte Antwort geliefert, ohne das LLM aufzurufen. QueryRewriterService die Anfrage um. Dies optimiert das anschließende Retrieval in der Vektordatenbank. vector_store nach thematisch relevanten Dokument-Chunks. Es werden bis zu 4 Chunks (Top-K = 4) abgerufen, die den Mindest-Ähnlichkeitsschwellenwert (Similarity Threshold = 0.6) überschreiten. gemini-2.5-flash-lite generiert die Antwort, welche zeichenweise per Server-Sent Events (SSE) an das Frontend gestreamt wird. Die Antwort wird strukturiert ausgegeben (Zusammenfassung, Schweregrad, Ursachen, Korrekturschritte, Quellen, Konfidenz-Score). doc/ werden automatisch eingelesen (KnowledgeIngestionService). Ein ChunkingService zerlegt Texte in überlappende Abschnitte, reichert sie mit Metadaten (Kategorie, Tool-Key, Version) an, lässt über gemini-embedding-001 einen 768-dimensionalen Vektor generieren und speichert diesen im PostgreSQL HNSW Vektor-Index ab.Vektor-Suche & Reranking-Algorithmus
Die Roh-Suchergebnisse aus der Datenbank (pgvector Cosinus-Ähnlichkeit) reichen oft nicht aus, um die präzisesten Hilfestellungen zu finden. Daher wendet der VectorSearchService einen Composite-Scoring-Reranking-Algorithmus mit fünf Faktoren an.
Die Faktoren im Detail:
Die mathematische Ähnlichkeit zwischen dem Anfrage-Vektor und dem Dokumenten-Vektor (Wertbereich 0.0 bis 1.0). Voraussetzung für die Berücksichtigung ist ein Wert von ≥ 0.6.
Stimmt die Kategorie des Wissensdatenbank-Chunks (z.B. "SSL") exakt mit dem aktiven Diagnose-Tool überein, erhält der Chunk einen Relevanz-Bonus von 0.2.
Zusätzlich zur Vektor-Ähnlichkeit wird eine lexikalische Suche durchgeführt. Pro Vorkommen wichtiger Schlüsselwörter aus der Anfrage im Chunk wird ein kleiner Bonus aufaddiert.
Passt die Sprache des Chunks (z.B. "de" für Deutsch) zur Benutzeroberfläche des anfragenden Nutzers, wird die Relevanz um 0.1 erhöht.
Im Multi-Tenant SaaS-Betrieb erhalten Dokumente, die dem spezifischen Workspace des Nutzers zugeordnet sind (Tenant Knowledge), einen Priorisierungs-Bonus von 0.1.
Scoring- & Bewertungsmodelle
Die Diagnose-Tools bewerten Zielsysteme mit einem Score (0 bis 100) und leiten daraus eine Note (Grade A bis F) ab. Die Logik ist in der zentralen ScoringEngine gekapselt und basiert auf folgenden Modellen:
1. SSL/TLS Audit (Subtraktives Scoring, Startwert: 100)
Ausgehend von 100 Punkten führen Sicherheitsmängel zu Punktabzügen. Das Endergebnis wird auf den Bereich [0, 100] limitiert (clamped):
| Befund / Schwachstelle | Abzug (Punkte) | Kategorie / Schweregrad |
|---|---|---|
| Zertifikat ungültig (abgelaufen, Hostname-Mismatch) | -100 (Score = 0) | CRITICAL |
| Zertifikatskette nicht vertrauenswürdig (Trust-Store) | -40 | CRITICAL |
| SSLv3 aktiv / Schwache Cipher-Suite (RC4, 3DES, MD5) | -30 | CRITICAL |
| Schwacher RSA/DSA-Schlüssel (< 2048 Bit) oder Signatur (SHA-1) | -30 | CRITICAL |
| TLS 1.0 / TLS 1.1 aktiv oder unvollständige Kette | -20 | WARN |
Restlaufzeit ≤ 14 Tage ≤ 14 (≤ 30 Tage) | -20 (-10) | CRITICAL / WARN |
| Schwache EC-Kurve (< 256 Bit) | -15 | WARN |
| OCSP-Stapling inaktiv / Kein CT-Nachweis (SCT) | -5 | INFO |
Geprüfte Sicherheitsmerkmale
Pro Zertifikat bzw. TLS-Endpunkt werden die folgenden Merkmale erhoben und bewertet:
- Gültigkeit: Ist das Zertifikat zeitlich gültig (nicht abgelaufen / bereits aktiv) und technisch korrekt?
- Hostname-Übereinstimmung: Deckt das Zertifikat (CN / SAN) den aufgerufenen Hostnamen ab?
- Restlaufzeit: Verbleibende Tage bis zum Ablauf inkl. frühzeitiger Erneuerungs-Warnung (≤ 30 / ≤ 14 Tage).
- Zertifikatskette: Vollständigkeit der Kette (vorhandene Intermediate-Zertifikate).
- Vertrauenswürdigkeit: Validierung der Kette gegen den anerkannten System-Trust-Store (Erkennung selbstsignierter / falsch verketteter Zertifikate).
- OCSP-Stapling: Liefert der Server den Widerrufsstatus (OCSP) selbst mit aus?
- Protokollversionen: Erkennung veralteter/unsicherer Versionen (SSLv3, TLS 1.0, TLS 1.1) gegenüber modernen (TLS 1.2 / 1.3).
- Cipher-Suites: Erkennung schwacher Verschlüsselungs-Suites (RC4, 3DES, DES, NULL, EXPORT).
- Schlüsselstärke: Bewertung der Schlüssellänge (RSA/DSA ≥ 2048 Bit, EC-Kurven ≥ 256 Bit).
- Signaturalgorithmus: Erkennung gebrochener Algorithmen (MD5, SHA-1) gegenüber SHA-256+.
- Certificate Transparency: Vorhandensein eingebetteter SCTs (Signed Certificate Timestamps).
2. Security Headers (Subtraktives Scoring, Startwert: 100)
Ausgehend von 100 Punkten führen fehlende oder schwache HTTP-Sicherheitsheader zu Punktabzügen. Die Bewertung erfolgt endpunkt- und kontextbewusst: schemalose Eingaben werden über HTTPS geprüft, und reine Härtungs-Header (Defense-in-Depth) werden als INFO ohne Abzug geführt, damit eine ansonsten saubere Seite nicht abgewertet wird.
| Befund / Sicherheits-Header | Abzug (Punkte) | Kategorie / Schweregrad |
|---|---|---|
Strict-Transport-Security (HSTS) fehlt (über HTTPS) | -25 | CRITICAL |
Content-Security-Policy (CSP) fehlt komplett | -25 | CRITICAL |
| CSP nur im Report-Only-Modus (vorhanden, nicht durchgesetzt) | -5 | WARN |
X-Frame-Options fehlt (Clickjacking-Schutz) | -12 | WARN |
X-Content-Type-Options fehlt (Defense-in-Depth) | 0 | INFO |
Referrer-Policy fehlt (Defense-in-Depth) | 0 | INFO |
Permissions-Policy fehlt (Defense-in-Depth) | 0 | INFO |
| HSTS über reinen HTTP-Endpunkt geprüft (RFC 6797) | 0 | INFO |
Content-Security-Policy-Report-Only gilt als vorhanden (überwacht, aber nicht durchgesetzt) und nicht als „fehlt komplett“. Eine funktionierende HTTP→HTTPS-Weiterleitung wird als bestandener Check positiv vermerkt.3. PageSpeed & Domain-Health Aggregation
- PageSpeed Score: Entspricht dem von der Google PageSpeed Insights API gelieferten Performance-Score (0–100). Bei der parallelen Messung von Mobil- und Desktopansicht wird das arithmetische Mittel gebildet.
- Domain-Health Score (Aggregat): Bildet das ungewichtete arithmetische Mittel aller erfolgreichen Teil-Scores (DNS, SSL, Security Headers, PageSpeed). Fällt ein Teilcheck wegen Timeouts aus, wechselt der Systemstatus auf
PARTIAL, der restliche Mittelwert wird dennoch ausgegeben. - Score-zu-Note Zuordnung: A (90-100) · B (80-89) · C (70-79) · D (60-69) · E (50-59) · F (0-49)
4. DNS-Audit (Sonderregeln, Abzüge & JNDI-Limitierung)
- DMARC-Kompensation (SPF): Weist eine Domain einen SPF-Soft-fail (
~all) auf, ist aber gleichzeitig durch eine restriktive DMARC-Policy (p=rejectoderp=quarantine) geschützt, so wird der standardmäßige Abzug von 10 Punkten ausgesetzt. Der Befund wird alsINFOstattWARNeingestuft, da der Spoofing-Schutz durch DMARC gewährleistet ist. - Angepasste Abzüge für CAA & DNSSEC: Da das Fehlen von CAA-Einträgen oder ein inaktives DNSSEC keine direkten Systemausfälle verursachen, sondern Empfehlungen darstellen, wurde der Abzug für beide Befunde von jeweils 10 auf **5 Punkte** reduziert. Dies trägt dem realen Sicherheitsrisiko besser Rechnung.
- JNDI CAA-Einschränkung: Der DNS-Check verwendet das integrierte Java JNDI-Verzeichnis zur Auflösung. JNDI besitzt in bestimmten Java-Runtimes Einschränkungen bei der Abfrage von CAA-Einträgen (Typ 257), was zu Fehlalarmen ("Kein CAA-Eintrag gefunden") führen kann. Um unberechtigte Punktabzüge aufgrund von JNDI-Fehlern abzufedern, ist der CAA-Abzug auf moderate 5 Punkte begrenzt.
- Propagations-Konsistenz (0 Punkte Abzug): Unterschiede in den IP-Antworten öffentlicher DNS-Resolver (Google, Cloudflare, Quad9) deuten oft auf GeoDNS-Lastverteilung oder CDN Anycast-Dienste hin (wie bei google.com). Dieser Befund zieht **0 Punkte** ab (zuvor -10) und wird als reine
INFOeingestuft, da es sich um eine legitime Netzwerkeigenschaft und keine Fehlkonfiguration handelt.
Sicherheits- & Resilienz-Architektur
Als Diagnosewerkzeug führt Balou Tools im Auftrag des Benutzers Anfragen an beliebige Zielsysteme aus. Dies erfordert tiefgreifende Schutzmaßnahmen zur Absicherung des eigenen Backends und zum Schutz der Privatsphäre.
SSRF-Schutz (Server-Side Request Forgery)
Jede vom Benutzer eingegebene URL und jeder einzelne Weiterleitungsschritt (Redirect Hop) wird durch den UrlSafetyValidator geprüft. Dabei werden alle aufgelösten A/AAAA-Records (IPv4 und IPv6) kontrolliert. Blockiert werden:
- Private IP-Bereiche (RFC 1918, z.B. 10.0.0.0/8, 192.168.0.0/16)
- Loopback-Adressen (IPv4 127.0.0.1, IPv6 ::1)
- Link-Local-Adressen (RFC 3927, z.B. 169.254.0.0/16 inkl. Cloud-Metadaten 169.254.169.254)
- Carrier-Grade-NAT (100.64.0.0/10), reservierte Blöcke (0.0.0.0/8, 240.0.0.0/4) sowie Multicast- und unspezifizierte Adressen (0.0.0.0, ::)
- IPv6 Unique-Local-Adressen (fc00::/7)
- Protokolle außer HTTP/HTTPS sowie Zielports ungleich 80 und 443
DNS-Rebinding- & TOCTOU-Schutz: Da der JDK-HttpClient DNS-Namen selbst auflöst, löst eine zentrale SafeHttpClientFactory den Hostnamen unmittelbar vor jedem ausgehenden Request erneut auf und prüft sämtliche zurückgegebenen Adressen erneut. Automatische Weiterleitungen sind deaktiviert (Redirect.NEVER); jeder Hop wird einzeln validiert. So wird das Zeitfenster geschlossen, in dem ein Angreifer mit kontrolliertem DNS den Eintrag nach der ersten Prüfung auf eine interne Adresse umstellt.
IP-Anonymisierung & Rate Limiting
Zum Schutz vor Missbrauch und Denial-of-Service-Angriffen ist an den Endpunkten ein IP-basiertes Rate-Limiting aktiv. Um datenschutzkonform zu arbeiten (DSGVO/DSG), werden IP-Adressen nicht im Klartext gespeichert. Die IP-Adresse wird mit einem server-seitigen Pepper (RATELIMIT_IP_HASH_SECRET) mittels **HMAC-SHA256** gehasht. Der Zähler verfällt rollierend nach 24 Stunden.
Resilienz- & Timeout-Policy
Um hängende Backend-Threads durch langsame Fremdserver zu verhindern, erzwingt Balou Tools strikte Timeouts: maximal 3 Sekunden für den Verbindungsaufbau (Connect) und 5 Sekunden zum Lesen von Daten (Read). Bei transienten Fehlern wird maximal ein (1) Wiederholungsversuch (Retry) mit kurzem Backoff (200-500 ms) ausgeführt. Detail-Fehlermeldungen werden verdeckt und dem Client wird eine standardisierte Korrelations-ID geliefert.