docs: rewrite architecture/README, update deployment/development
- architecture.md: complete rewrite (French) with dual-database diagram, 5-phase data flow, full table ownership, triple-voice ML pipeline, 7 dictionaries, 13 SQL files, updated tech stack - README.md: complete rewrite (English) with updated pipeline diagram, services table, scripts section, integration tests, full doc index, Go 1.24.6 workspace - deployment.md: update to 13 SQL files, remove Anubis UA/Country refs, add scripts section, add ensemble env vars (AE_WEIGHT, XGB_WEIGHT), update verification queries and network diagram - development.md: translate to French, add bot-detector 11-module structure, add Python ML deps, add scripts/integration test sections, fix bot-detector run command, add make targets Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
toto
@ -42,7 +42,7 @@ clickhouse-client --query "SELECT version()"
|
||||
|
||||
## Étape 2 — Déploiement du schéma ClickHouse
|
||||
|
||||
Le schéma est géré par **10 fichiers SQL ordonnés** dans `shared/clickhouse/` et un script de déploiement automatisé.
|
||||
Le schéma est géré par **13 fichiers SQL ordonnés** dans `shared/clickhouse/` et un script de déploiement automatisé.
|
||||
|
||||
### Architecture des bases de données
|
||||
|
||||
@ -57,17 +57,21 @@ Le système utilise **deux bases de données** séparées :
|
||||
|
||||
```
|
||||
shared/clickhouse/
|
||||
├── 00_database.sql # Création des deux bases
|
||||
├── 01_raw_tables.sql # ja4_logs.http_logs_raw (ingestion brute, TTL 1 jour)
|
||||
├── 00_database.sql # Création des bases ja4_logs + ja4_processing
|
||||
├── 01_raw_tables.sql # ja4_logs.http_logs_raw (ingestion brute, TTL 2 heures)
|
||||
├── 02_dictionaries.sql # ja4_processing : dict_iplocate_asn, ref_bot_networks, bot_ip, bot_ja4
|
||||
├── 03_anubis_tables.sql # ja4_processing : tables et dictionnaires Anubis (UA, IP, ASN, Country)
|
||||
├── 03_anubis_tables.sql # ja4_processing : anubis_ip_rules, anubis_asn_rules + 2 dicts (IP/CIDR + ASN)
|
||||
├── 04_mv_http_logs.sql # ja4_logs.http_logs + mv_http_logs (parsing JSON → colonnes typées)
|
||||
├── 05_aggregation_tables.sql # ja4_processing : agg_host_ip_ja4_1h, agg_header_fingerprint_1h + MVs
|
||||
├── 05_aggregation_tables.sql # ja4_processing : agg_host_ip_ja4_1h, agg_header_fingerprint_1h + MVs + 4 dicts
|
||||
├── 06_ml_tables.sql # ja4_processing : ml_detected_anomalies, ml_all_scores, view_ip_recurrence
|
||||
├── 07_ai_features_view.sql # ja4_processing : view_ai_features_1h (feature engineering)
|
||||
├── 07_ai_features_view.sql # ja4_processing : view_ai_features_1h (feature engineering ~63 features)
|
||||
├── 08_users.sql # Utilisateurs data_writer et analyst + permissions
|
||||
├── 09_audit_table.sql # ja4_processing : audit_logs (trace SOC, TTL 90 jours)
|
||||
└── deploy_schema.sh # Script de déploiement automatisé
|
||||
├── 10_perf_indexes.sql # Index et projections de performance sur tables existantes
|
||||
├── 11_views.sql # Vues métier du dashboard (bruteforce, rotation, user_agents, entities)
|
||||
├── 12_thesis_features.sql # Tables d'agrégation avancées (path_sequences, request_timing,
|
||||
│ # ip_behavior, resource_cascade) + MVs + vues thèse
|
||||
└── deploy_schema.sh # Script de déploiement automatisé (substitution env vars)
|
||||
```
|
||||
|
||||
### Déploiement avec les noms par défaut
|
||||
@ -109,8 +113,9 @@ clickhouse-client --query "SHOW TABLES FROM ja4_logs"
|
||||
|
||||
# Tables dans ja4_processing
|
||||
clickhouse-client --query "SHOW TABLES FROM ja4_processing"
|
||||
# Attendu : agg_header_fingerprint_1h, agg_host_ip_ja4_1h, anubis_asn_rules,
|
||||
# anubis_country_rules, anubis_ip_rules, anubis_ua_rules, audit_logs,
|
||||
# Attendu : agg_header_fingerprint_1h, agg_host_ip_ja4_1h, agg_ip_behavior_1h,
|
||||
# agg_path_sequences_1h, agg_request_timing_1h, agg_resource_cascade_1h,
|
||||
# anubis_asn_rules, anubis_ip_rules, audit_logs, bot_ip, bot_ja4,
|
||||
# ml_all_scores, ml_detected_anomalies, ref_bot_networks, ...
|
||||
|
||||
# Dictionnaires chargés
|
||||
@ -161,10 +166,9 @@ GRANT INSERT ON ja4_processing.ml_all_scores TO bot_writer;
|
||||
GRANT INSERT ON ja4_processing.ml_detected_anomalies TO bot_writer;
|
||||
|
||||
-- Lectures/écritures : tables Anubis (ja4_processing) — pour fetch_rules.py
|
||||
GRANT SELECT, INSERT, ALTER ON ja4_processing.anubis_ua_rules TO bot_writer;
|
||||
-- Seules les règles IP/CIDR et ASN sont utilisées (UA et Country ont été supprimés)
|
||||
GRANT SELECT, INSERT, ALTER ON ja4_processing.anubis_ip_rules TO bot_writer;
|
||||
GRANT SELECT, INSERT, ALTER ON ja4_processing.anubis_asn_rules TO bot_writer;
|
||||
GRANT SELECT, INSERT, ALTER ON ja4_processing.anubis_country_rules TO bot_writer;
|
||||
GRANT SYSTEM RELOAD DICTIONARY ON *.* TO bot_writer;
|
||||
```
|
||||
|
||||
@ -322,9 +326,12 @@ Variables d'environnement clés :
|
||||
| `CLICKHOUSE_DB_LOGS` | `ja4_logs` | Base de logs |
|
||||
| `CLICKHOUSE_USER` | `admin` | Utilisateur (utiliser `bot_writer` en prod) |
|
||||
| `CLICKHOUSE_PASSWORD` | — | Mot de passe |
|
||||
| `ANOMALY_THRESHOLD` | `-0.05` | Seuil de détection d'anomalies |
|
||||
| `ANOMALY_THRESHOLD` | `-0.05` | Seuil de détection d'anomalies (fallback) |
|
||||
| `CYCLE_INTERVAL_SEC` | `300` | Intervalle entre cycles de détection (secondes) |
|
||||
| `RETRAIN_INTERVAL_HOURS` | `24` | Intervalle de réentraînement du modèle |
|
||||
| `RETRAIN_INTERVAL_HOURS` | `24` | Intervalle de réentraînement des modèles |
|
||||
| `AE_WEIGHT` | `0.30` | Poids de l'Autoencoder dans l'ensemble (α) |
|
||||
| `XGB_WEIGHT` | `0.20` | Poids de XGBoost dans l'ensemble (β) |
|
||||
| `ENABLE_MULTIWINDOW` | `false` | Active les variantes 24h (Complet/Applicatif) |
|
||||
| `HEALTH_PORT` | `8080` | Port du endpoint /health |
|
||||
|
||||
```bash
|
||||
@ -424,29 +431,76 @@ curl -s http://localhost:8000/api/health
|
||||
|
||||
---
|
||||
|
||||
## Scripts utilitaires
|
||||
|
||||
Les scripts dans `scripts/` facilitent l'initialisation et la maintenance de la stack :
|
||||
|
||||
### init-stack.sh — Initialisation complète
|
||||
|
||||
Déploie le schéma SQL, charge les données CSV de référence et vérifie que tous les composants sont opérationnels :
|
||||
|
||||
```bash
|
||||
./scripts/init-stack.sh # init stack de dev
|
||||
./scripts/init-stack.sh --container my-ch-1 # conteneur ClickHouse spécifique
|
||||
./scripts/init-stack.sh --reset # DROP databases, tout recréer
|
||||
./scripts/init-stack.sh --import-prod # init + import données prod
|
||||
```
|
||||
|
||||
### import-prod-data.sh — Import de données de production
|
||||
|
||||
Importe les données exportées au format Native avec décalage temporel automatique :
|
||||
|
||||
```bash
|
||||
./scripts/import-prod-data.sh # décalage auto (max(time) → now)
|
||||
./scripts/import-prod-data.sh --shift 3600 # décalage manuel (secondes)
|
||||
./scripts/import-prod-data.sh --no-truncate # conserver les données existantes
|
||||
```
|
||||
|
||||
### reload-prod-logs.sh — Rechargement depuis la production
|
||||
|
||||
Exporte les `http_logs` de la production et les réimporte dans la base de dev :
|
||||
|
||||
```bash
|
||||
./scripts/reload-prod-logs.sh # décalage auto
|
||||
./scripts/reload-prod-logs.sh --days 7 # exporte les N derniers jours
|
||||
./scripts/reload-prod-logs.sh --cron # mode silencieux (pour crontab)
|
||||
```
|
||||
|
||||
### update-csv-data.sh — Mise à jour des données CSV
|
||||
|
||||
Télécharge et génère tous les fichiers CSV de référence (bot IPs, JA4, ASN) :
|
||||
|
||||
```bash
|
||||
./scripts/update-csv-data.sh # génère tout
|
||||
./scripts/update-csv-data.sh --install-stubs # copie aussi les stubs de test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Schéma réseau récapitulatif
|
||||
|
||||
```
|
||||
┌──────────────┐ Unix socket ┌──────────────┐ ClickHouse ┌──────────────┐
|
||||
│ mod-reqin-log│──── http.socket ─────→│ │ INSERT INTO │ │
|
||||
│ (Apache) │ (source A) │ correlator │───→ ja4_logs. │ ClickHouse │
|
||||
└──────────────┘ │ │ http_logs_raw │ │
|
||||
│ │ │ ┌─────────┐ │
|
||||
┌──────────────┐ Unix socket │ │ MV parse JSON │ │ja4_logs │ │
|
||||
│ sentinel │──── network.socket ──→│ │ ↓ │ │ _raw │ │
|
||||
│ (TLS capture)│ (source B) └──────────────┘ ja4_logs. │ │ _parsed │ │
|
||||
└──────────────┘ http_logs │ └─────────┘ │
|
||||
│ │ │
|
||||
MV agrégation │ ┌─────────┐ │
|
||||
↓ │ │ja4_ │ │
|
||||
┌──────────────┐ SELECT features ┌──────────────┐ ja4_processing. │ │processing│
|
||||
│ bot-detector │←─── view_ai_features ─│ │ agg_*, view_* │ │ _agg │ │
|
||||
│ (ML/Python) │ │ ClickHouse │ │ │ _ml │ │
|
||||
│ │───→ INSERT scores ────→│ │ ml_all_scores │ │ _views │ │
|
||||
└──────────────┘ ml_detected_* └──────────────┘ ml_detected_* │ └─────────┘ │
|
||||
└──────────────┘
|
||||
┌──────────────┐ SELECT * ↑
|
||||
│ dashboard │←─── ja4_processing.* ───────────────────────────┘
|
||||
│ (FastAPI) │←─── ja4_logs.http_logs ─────────────────────────┘
|
||||
┌──────────────┐ Unix socket ┌──────────────┐ ClickHouse ┌──────────────────┐
|
||||
│ mod-reqin-log│──── http.socket ─────→│ │ INSERT INTO │ │
|
||||
│ (Apache C11) │ (source A) │ correlator │───→ ja4_logs. │ ClickHouse │
|
||||
└──────────────┘ │ │ http_logs_raw │ │
|
||||
│ │ │ ┌──────────────┐ │
|
||||
┌──────────────┐ Unix socket │ │ MV parse JSON │ │ ja4_logs │ │
|
||||
│ sentinel │──── network.socket ──→│ │ ↓ │ │ _raw → _logs│ │
|
||||
│ (Go+libpcap) │ (source B) └──────────────┘ ja4_logs. │ └──────────────┘ │
|
||||
└──────────────┘ http_logs │ │
|
||||
│ │ ┌──────────────┐ │
|
||||
6 MVs agrégation│ │ ja4_processing│ │
|
||||
↓ │ │ agg_* (×6) │ │
|
||||
┌──────────────┐ SELECT features ┌──────────────┐ ja4_processing. │ │ ml_* (×2) │ │
|
||||
│ bot-detector │←─── view_ai_features ─│ │ agg_*, view_* │ │ views, dicts│ │
|
||||
│ (Python 3.11)│ view_thesis_feat │ ClickHouse │ │ │ audit_logs │ │
|
||||
│ EIF+AE+XGB │ │ │ ml_all_scores │ └──────────────┘ │
|
||||
│ │───→ INSERT scores ────→│ │ ml_detected_* │ │
|
||||
└──────────────┘ └──────────────┘ └──────────────────┘
|
||||
↑
|
||||
┌──────────────┐ SELECT * │
|
||||
│ dashboard │←─── ja4_processing.ml_*, agg_*, views ────────────────────────────┘
|
||||
│ (FastAPI) │←─── ja4_logs.http_logs ───────────────────────────────────────────┘
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user