Technologie & Algorithmes
Une plongée au cœur de l'architecture, de la pipeline RAG et des modèles technico-mathématiques derrière Balou Tools.
Des termes ou abréviations ne sont pas clairs ? → Vers le glossaire
Architecture système & flux de données de haut niveau
Balou Tools est conçu comme une Developer Diagnostic Platform moderne et performante. L'architecture système sépare strictement le frontend réactif et statiquement optimisé d'un backend Spring Boot sans état (stateless). Pour paralléliser les requêtes réseau externes, le backend utilise des threads virtuels.
Principes d'architecture :
- Threads virtuels (Java 25) : Permettent de lancer un thread léger pour chaque action d'E/S bloquante (requêtes DNS, handshakes SSL, appels HTTP). Cela élimine le goulot d'étranglement classique du pool de threads.
- Priorité à la confidentialité & Exécution locale : Les outils de manipulation de texte, de hachage, d'encodage Base64, de décodage JWT et les générateurs s'exécutent à 100 % côté client dans le navigateur de l'utilisateur. Aucun transfert de ces données sensibles vers le serveur n'a lieu.
- Cache en priorité : Réduction des temps de latence et des coûts d'API grâce à une infrastructure de cache multiniveau (cache Caffeine en mémoire et cache Redis distribué).
Stack technique
Les composants de Balou Tools reposent sur des technologies de base établies et pérennes, axées sur la performance SEO, la robustesse et des temps de chargement extrêmement courts.
| Domaine | Technologie | Version | Objectif / Fonction |
|---|---|---|---|
| Frontend | Astro Framework | 6.4.x | Méta-framework pour la génération de sites statiques (SSG) & SSR, optimisation SEO |
| Client-UI | Svelte | 5.55.x | Îlots d'interface utilisateur interactifs et réactifs utilisant la nouvelle API Runes |
| Backend | Spring Boot | 4.0.6 | API REST, injection de dépendances, orchestration système |
| Sprache | Java / TypeScript | 25 / 6.0 | Threads virtuels, records, sécurité typique dans le frontend et le backend |
| KI-Integration | Spring AI | 2.0.0-RC1 | Abstraction standardisée pour les bases de données vectorielles et les appels de LLM |
| Sprachmodell | Google Gemini | API | LLM : gemini-2.5-flash-lite · Embeddings : gemini-embedding-001 |
| Datenbank | PostgreSQL + pgvector | 16+ | Stockage de données relationnel & base de données vectorielle (indices HNSW, 768 dimensions) |
| Caching | Caffeine & Redis | 7.x | Cache en mémoire local extrêmement rapide & cache distribué pour la mise à l'échelle |
Pipeline IA & RAG
Le diagnostic d'erreurs assisté par l'IA repose sur une pipeline de génération augmentée par récupération (RAG). Elle enrichit les données brutes des outils de diagnostic avec le contexte spécifique de la base de connaissances interne de Balou.
≥ 95%, le système vérifie si une question sémantiquement identique a déjà reçu une réponse. En cas de correspondance, la réponse mise en cache est directement renvoyée, sans appeler le LLM. QueryRewriterService la reformule. Cela permet d'optimiser la récupération ultérieure dans la base de données vectorielle. vector_store. Jusqu'à 4 fragments (Top-K = 4) dépassant le seuil de similarité minimal (Similarity Threshold = 0.6) sont récupérés. gemini-2.5-flash-lite génère la réponse, qui est diffusée caractère par caractère via des événements envoyés par le serveur (SSE) au frontend. La réponse est structurée (résumé, gravité, causes, étapes de correction, sources, score de confiance). doc/ sont automatiquement importés (KnowledgeIngestionService). Un ChunkingService découpe les textes en sections superposées, les enrichit de métadonnées (catégorie, clé d'outil, version), génère un vecteur à 768 dimensions via gemini-embedding-001 et l'enregistre dans l'index vectoriel HNSW de PostgreSQL.Recherche vectorielle & algorithme de reranking
Les résultats de recherche bruts de la base de données (similarité cosinus pgvector) ne suffisent souvent pas à trouver les aides les plus précises. C'est pourquoi le VectorSearchService applique un algorithme de reranking par scoring composite reposant sur cinq facteurs.
Les facteurs en detail :
La similarité mathématique entre le vecteur de requête et le vecteur de document (plage de valeurs de 0,0 à 1,0). Une valeur de ≥ 0,6 est requise pour être pris en compte.
Si la catégorie du fragment de la base de connaissances (par exemple 'SSL') correspond exactement à l'outil de diagnostic actif, le fragment bénéficie d'un bonus de pertinence de 0,2.
En plus de la similarité vectorielle, une recherche lexicale est effectuée. Pour chaque occurrence de mots-clés importants de la requête dans le fragment, un petit bonus est ajouté.
Si la langue du fragment (par exemple 'de' pour l'allemand) correspond à l'interface de l'utilisateur demandeur, la pertinence est augmentée de 0,1.
Dans le cadre d'un fonctionnement SaaS multi-tenant, les documents associés à l'espace de travail spécifique de l'utilisateur (Tenant Knowledge) bénéficient d'un bonus de priorisation de 0,1.
Modèles de scoring & d'évaluation
Les outils de diagnostic évaluent les systèmes cibles avec un score (0 à 100) et en déduisent une note (Grade A à F). La logique est encapsulée dans la ScoringEngine centrale et repose sur les modèles suivants :
1. Audit SSL/TLS (Scoring soustractif, valeur de départ : 100)
À partir d'une base de 100 points, les failles de sécurité entraînent des retraits de points. Le résultat final est limité (clamped) à l'intervalle [0, 100] :
| Constat / Vulnérabilité | Déduction (Points) | Catégorie / Gravité |
|---|---|---|
| Certificat invalide (expiré, non-correspondance du nom d'hôte) | -100 (Score = 0) | CRITICAL |
| Chaîne de certificats non approuvée (Trust Store) | -40 | CRITICAL |
| SSLv3 actif / Suite de chiffrement faible (RC4, 3DES, MD5) | -30 | CRITICAL |
| Clé RSA/DSA faible (< 2048 bits) ou signature faible (SHA-1) | -30 | CRITICAL |
| TLS 1.0 / TLS 1.1 actif ou chaîne incomplète | -20 | WARN |
Durée de validité restante ≤ 14 jours ≤ 14 (≤ 30 jours) | -20 (-10) | CRITICAL / WARN |
| Courbe CE faible (< 256 bits) | -15 | WARN |
| OCSP stapling inactif / Absence de preuve CT (SCT) | -5 | INFO |
Caractéristiques de sécurité vérifiées
Les caractéristiques suivantes sont collectées et évaluées par certificat ou point de terminaison TLS :
- Validité : Le certificat est-il temporellement valide (non expiré / déjà actif) et techniquement correct ?
- Correspondance du nom d'hôte : Le certificat (CN / SAN) couvre-t-il le nom d'hôte appelé ?
- Durée de validité restante : Jours restants avant expiration, y compris l'avertissement de renouvellement anticipé (≤ 30 / ≤ 14 jours).
- Chaîne de certificats : Exhaustivité de la chaîne (certificats intermédiaires présents).
- Approbation : Validation de la chaîne par rapport au magasin de confiance reconnu du système (détection de certificats auto-signés ou mal chaînés).
- OCSP Stapling : Le serveur fournit-il lui-même le statut de révocation (OCSP) ?
- Versions de protocole : Détection des versions obsolètes/inutilisées (SSLv3, TLS 1.0, TLS 1.1) par rapport aux versions modernes (TLS 1.2 / 1.3).
- Suites de chiffrement : Détection de suites de chiffrement faibles (RC4, 3DES, DES, NULL, EXPORT).
- Force de la clé : Évaluation de la longueur de la clé (RSA/DSA ≥ 2048 bits, courbes CE ≥ 256 bits).
- Algorithme de signature : Détection d'algorithmes compromis (MD5, SHA-1) par rapport à SHA-256+.
- Certificate Transparency : Présence de SCT (Signed Certificate Timestamps) intégrés.
2. En-têtes de sécurité (Scoring soustractif, valeur de départ : 100)
À partir d'une base de 100 points, l'absence ou la faiblesse des en-têtes de sécurité HTTP entraîne des retraits de points. L'évaluation est sensible à l'hôte et au contexte : les entrées sans schéma sont testées via HTTPS, et les en-têtes de durcissement purs (défense en profondeur) sont signalés comme INFO sans déduction, afin de ne pas pénaliser un site par ailleurs propre.
| Constat / En-tête de sécurité | Déduction (Points) | Catégorie / Gravité |
|---|---|---|
Strict-Transport-Security (HSTS) manquant (via HTTPS) | -25 | CRITICAL |
Content-Security-Policy (CSP) complètement manquant | -25 | CRITICAL |
| CSP uniquement en mode Report-Only (présent, non appliqué) | -5 | WARN |
X-Frame-Options manquant (protection clickjacking) | -12 | WARN |
X-Content-Type-Options manquant (défense en profondeur) | 0 | INFO |
Referrer-Policy manquant (défense en profondeur) | 0 | INFO |
Permissions-Policy manquant (défense en profondeur) | 0 | INFO |
| HSTS testé sur un point de terminaison HTTP pur (RFC 6797) | 0 | INFO |
Content-Security-Policy-Report-Only présente est considérée comme existante (surveillée mais non appliquée) et non comme « complètement manquante ». Une redirection HTTP→HTTPS fonctionnelle est enregistrée positivement comme un test réussi.3. Agrégation PageSpeed & Domain-Health
- Score PageSpeed : Correspond au score de performance (0–100) fourni par l'API Google PageSpeed Insights. Lors de la mesure parallèle des vues mobile et ordinateur, la moyenne arithmétique est calculée.
- Score Domain-Health (Agrégat) : Calcule la moyenne arithmétique non pondérée de tous les scores partiels réussis (DNS, SSL, Security Headers, PageSpeed). Si un sous-contrôle échoue en raison de délais d'attente, l'état du système passe à
PARTIAL, mais la moyenne restante est tout de même affichée. - Attribution du score à la note : A (90-100) · B (80-89) · C (70-79) · D (60-69) · E (50-59) · F (0-49)
4. Audit DNS (Règles spéciales, déductions & limitation JNDI)
- Compensation DMARC (SPF) : Si un domaine présente un SPF soft-fail (
~all) mais est protégé simultanément par une politique DMARC restrictive (p=rejectoup=quarantine), la déduction standard de 10 points is suspendue. Le constat est classé enINFOau lieu deWARN, car la protection contre l'usurpation (spoofing) est garantie par DMARC. - Déductions ajustées pour CAA & DNSSEC : L'absence d'enregistrements CAA ou un DNSSEC inactif ne provoquant pas de pannes directes du système mais constituant des recommandations, la déduction pour ces deux constats a été ramenée de 10 à **5 points** chacun. Cela correspond mieux au risque de sécurité réel.
- Limitation JNDI CAA : Le contrôle DNS utilise l'annuaire Java JNDI intégré pour la résolution. JNDI présente des limitations dans certains environnements d'exécution Java lors de la requête d'enregistrements CAA (type 257), ce qui peut entraîner de fausses alertes (« Aucun enregistrement CAA trouvé »). Afin d'atténuer les déductions de points injustifiées dues à des erreurs JNDI, la déduction pour CAA est limitée à un niveau modéré de 5 points.
- Cohérence de la propagation (déduction de 0 point) : Les différences dans les réponses IP des résolveurs DNS publics (Google, Cloudflare, Quad9) indiquent souvent une répartition de charge GeoDNS ou des services Anycast de CDN (comme pour google.com). Ce constat n'entraîne **aucune déduction de points** (auparavant -10) et est classé comme simple
INFO, car il s'agit d'une caractéristique réseau légitime et non d'une mauvaise configuration.
Architecture de sécurité & de résilience
En tant qu'outil de diagnostic, Balou Tools exécute des requêtes vers n'importe quel système cible pour le compte de l'utilisateur. Cela nécessite des mesures de protection approfondies pour sécuriser son propre backend et protéger la vie privée de l'utilisateur.
Protection SSRF (Server-Side Request Forgery)
Chaque URL saisie par l'utilisateur et chaque étape de redirection (Redirect Hop) est validée par le UrlSafetyValidator, qui contrôle tous les enregistrements A/AAAA résolus (IPv4 et IPv6). Sont bloqués :
- Plages d'adresses IP privées (RFC 1918, par ex. 10.0.0.0/8, 192.168.0.0/16)
- Adresses de bouclage / loopback (IPv4 127.0.0.1, IPv6 ::1)
- Adresses de liaison locale / link-local (RFC 3927, par ex. 169.254.0.0/16 incl. métadonnées cloud 169.254.169.254)
- Carrier-Grade-NAT (100.64.0.0/10), blocs réservés (0.0.0.0/8, 240.0.0.0/4) ainsi que les adresses multicast et non spécifiées (0.0.0.0, ::)
- Adresses IPv6 uniques locales (fc00::/7)
- Protocoles autres que HTTP/HTTPS ainsi que les ports cibles différents de 80 et 443
Protection contre le DNS-rebinding & TOCTOU : Comme le HttpClient du JDK résout lui-même les noms DNS, une SafeHttpClientFactory centrale ré-résout le nom d'hôte immédiatement avant chaque requête sortante et revérifie toutes les adresses renvoyées. Les redirections automatiques sont désactivées (Redirect.NEVER) ; chaque étape est validée individuellement. Cela ferme la fenêtre pendant laquelle un attaquant contrôlant le DNS pourrait basculer l'enregistrement vers une adresse interne après le premier contrôle.
Anonymisation des IP & limitation du débit
Pour se prémunir contre les abus et les attaques par déni de service, une limitation de débit basée sur l'IP est active sur les points de terminaison. Afin de respecter le règlement sur la protection des données (RGPD/LPD), les adresses IP ne sont pas enregistrées en clair. L'adresse IP est hachée via **HMAC-SHA256** à l'aide d'un pepper côté serveur (RATELIMIT_IP_HASH_SECRET). Le compteur expire de manière glissante après 24 heures.
Politique de résilience & de timeout
Afin d'éviter que les threads du backend ne restent bloqués par des serveurs tiers lents, Balou Tools applique des délais d'attente (timeouts) stricts : maximum 3 secondes pour l'établissement de la connexion (Connect) et 5 secondes pour la lecture des données (Read). En cas d'erreurs transitoires, un seul (1) essai supplémentaire (Retry) avec un court backoff (200-500 ms) est effectué. Les messages d'erreur détaillés sont masqués et une ID de corrélation standardisée est fournie au client.