# Schéma ClickHouse — ja4-platform

Ce répertoire contient les 13 fichiers SQL définissant le schéma complet
de la plateforme. Le schéma utilise un **patron double-base** :

- **`ja4_logs`** — ingestion brute et logs HTTP parsés
- **`ja4_processing`** — agrégations, ML, vues, dictionnaires, audit

Les noms de base sont configurables via variables d'environnement
(`CLICKHOUSE_DB_LOGS`, `CLICKHOUSE_DB_PROCESSING`).

## Fichiers SQL

Appliquer dans l'ordre numérique :

| Fichier | Contenu |
|---------|---------|
| `00_database.sql` | Création des bases `ja4_logs` et `ja4_processing` |
| `01_raw_tables.sql` | Table d'ingestion `http_logs_raw` |
| `02_dictionaries.sql` | Dictionnaire `dict_iplocate_asn`, tables `ref_bot_networks`, `bot_ip`, `bot_ja4` |
| `03_anubis_tables.sql` | Tables de règles Anubis (`anubis_ip_rules`, `anubis_asn_rules`) et dictionnaires (`dict_anubis_ip`, `dict_anubis_asn`) |
| `04_mv_http_logs.sql` | Table `http_logs` + vue matérialisée `mv_http_logs` (parse JSON + enrichissement Anubis IP→ASN) |
| `05_aggregation_tables.sql` | Dictionnaires de réputation (`dict_bot_ip`, `dict_bot_ja4`, `dict_browser_ja4`, `dict_asn_reputation`) + tables d'agrégation + MVs |
| `06_ml_tables.sql` | Tables ML (`ml_detected_anomalies`, `ml_all_scores`) + vue `view_ip_recurrence` |
| `07_ai_features_view.sql` | Vue `view_ai_features_1h` (~65+ features ML) |
| `08_users.sql` | Utilisateurs `data_writer` et `analyst` avec permissions |
| `09_audit_table.sql` | Table `audit_logs` pour le journal d'audit SOC |
| `10_perf_indexes.sql` | Index secondaires et projections de performance |
| `11_views.sql` | Vues dashboard (entités, user-agents, force brute, rotation JA4, cascade) |
| `12_thesis_features.sql` | Tables d'agrégation thèse (§5) + vue `view_thesis_features_1h` |

## Déploiement

### Méthode recommandée

Utiliser `deploy_schema.sh` qui applique les 13 fichiers avec substitution
automatique des noms de base :

```bash
./deploy_schema.sh

# Ou avec configuration personnalisée :
CLICKHOUSE_DB_LOGS=my_logs \
CLICKHOUSE_DB_PROCESSING=my_proc \
CLICKHOUSE_HOST=clickhouse-server \
CLICKHOUSE_PASSWORD='secret' \
  ./deploy_schema.sh
```

### Application manuelle

```bash
for f in 0*.sql 1*.sql; do
    clickhouse-client --multiquery < "$f"
done
```

## Prérequis

- **ClickHouse 24.8+** (support `deduplicate_merge_projection_mode`)
- **Fichiers CSV** dans `/var/lib/clickhouse/user_files/` :
  - `iplocate-ip-to-asn.csv` — correspondance IP→ASN (~714K entrées)
  - `bot_ip.csv` — préfixes IP de bots connus (~3,5K CIDR)
  - `bot_ja4.csv` — empreintes JA4 de bots (~31 entrées)
  - `browser_ja4.csv` — empreintes JA4 de navigateurs (~1,2K entrées)
  - `asn_reputation.csv` — labels de réputation ASN (~82K entrées)
- **Mots de passe Anubis** : remplacer `CHANGE_ME` dans `03_anubis_tables.sql`

## Notes

- Toutes les migrations sont **idempotentes** (`IF NOT EXISTS` / `CREATE OR REPLACE`).
- `04_mv_http_logs.sql` est la version **canonique** de la vue matérialisée.
- Les références inter-bases existent : les MVs dans `ja4_processing` lisent
  depuis `ja4_logs.http_logs`.
- Documentation complète : `docs/database/schema.md` et `docs/database/migrations.md`.