Pipeline de sécurité des fichiers : modèle de sécurité

Cette page décrit les garanties de sécurité du pipeline qui analyse chaque fichier avant Docling, l'OCR, le stockage des médias, la transcription et le RAG : quarantaine, ClamAV, YARA-X, verdicts, blocage, règles verrouillées, rôles et preuves. L'installation des moteurs, leurs réglages et la mise à jour des signatures sont dans le guide Sécurité des fichiers. Code : services/control-plane/src/eai/domains/file_security, migration sql/postgres/V199, écran portal/src/screens/file-security.tsx.

English version: en/file-security-pipeline.md

Chaîne obligatoire

upload -> quarantine -> clamav -> yara_x -> validation -> docling -> rag

1. Quarantaine. L'enregistrement quarantined est validé dans sa propre transaction avant toute analyse : un arrêt brutal laisse le fichier en quarantaine, jamais libéré.
2. Contrôles intégrés. Type détecté par le contenu (eai.domains.file_security.checks), types admis, archives (profondeur 3 au plus, 10 000 membres au plus), macros Office, incohérence entre type annoncé et type réel.
3. ClamAV puis YARA-X. Chaque moteur est appelé en HTTPS (EAI_CLAMAV_URLS, EAI_YARAX_URLS, clés Bearer, CA EAI_FILE_SCAN_CA_FILE) à travers la garde de sortie. Plusieurs points d'accès sont essayés à tour de rôle ; un point en échec passe en dernier pendant EAI_FILE_SCAN_ENDPOINT_DOWN_SECONDS.
4. Décision. Le verdict le plus grave l'emporte ; seul clean libère le fichier (released), tout autre verdict bloquant le bloque (blocked).
5. Autorisation d'analyse. Seule une analyse libérée produit une ScanClearance scellée par un secret du processus et liée à l'empreinte exacte des octets. Docling, l'OCR, store_media, les adaptateurs multimédia et la transcription appellent clearance.require avant de lire les octets : un fichier non analysé ne peut pas les atteindre, même par erreur de code.

Aucune transaction n'est ouverte pendant une analyse (une analyse dans une db.tx ouverte lève NestedScan). Ne sont pas des fichiers, donc hors pipeline : les trames audio PCM16 du temps réel, POST /v1/encryption/encrypt (octets chiffrés et renvoyés, jamais lus) et les tests de connecteurs.

Verdicts

Verdict	Signification	État
malware	Signature ClamAV ou règle YARA-X de logiciel malveillant	blocked (toujours)
suspicious	Règle YARA-X ou contrôle intégré suspect	blocked quand la règle bloque
unscannable	Fichier chiffré, limites dépassées, archive cassée, taille au-delà du plafond	blocked (toujours)
policy_violation	Type non admis, archive refusée, macro, type incohérent	blocked
scan_error	Tous les points d'accès d'un moteur ont échoué	blocked (échec fermé)
clean	Aucun constat bloquant	released

Précédence (PRECEDENCE) : malware, suspicious, unscannable, policy_violation, scan_error. Une règle YARA-X en action = "report" est journalisée sans bloquer.

Règles verrouillées et politique du tenant

Les règles verrouillées sont des constantes du code (LOCKED dans eai.domains.file_security.policy), jamais stockées ni modifiables : analyse avant toute ingestion, deux moteurs (clamav, yara_x) exigés, échec fermé, blocage des malwares et des fichiers non inspectables. Une tentative de les changer répond 422 file_security_rule_locked.

Un tenant ne peut que durcir les autres réglages (GET /v1/file-security/policy, PUT /v1/file-security/policy) :

Réglage	Défaut
max_file_bytes	EAI_FILE_SCAN_MAX_BYTES (jamais au-dessus)
allowed_types	tous les types connus sauf executable
allow_archives	true
block_office_macros	true
block_type_mismatch	true
retain_samples	true
quarantine_retention_days	30
max_signature_age_hours	48
stale_signatures	warn (block refuse toute analyse tant que les signatures sont trop anciennes)

Mode d'application

• EAI_FILE_SCAN_MODE=enforce : deux moteurs exigés ; aucun joignable donne 503 (échec fermé). Obligatoire en production : la garde de démarrage refuse un autre mode, une URL de moteur hors https:// et une clé Bearer absente.
• dev (refusé en production) : un moteur non configuré est noté not_configured ; un moteur configuré s'applique exactement comme en enforce.

Fichiers bloqués

• L'échantillon d'un fichier bloqué est gardé chiffré (clé de tenant file-security-quarantine, enveloppe eaienc1) quand retain_samples est vrai ; un fichier libéré ne laisse jamais d'échantillon.
• POST /v1/file-security/scans/{scan_id}/rescan réanalyse l'échantillon retenu dans un nouvel enregistrement (rescan_of) ; il ne libère jamais le dépôt d'origine (409 file_sample_unavailable sans échantillon).
• DELETE /v1/file-security/scans/{scan_id}/sample supprime l'échantillon tout de suite (audité). Le job file_scan_samples_purge du worker supprime les échantillons au-delà de quarantine_retention_days.

Rôles

Opération	Route	Rôles
État des moteurs	GET /v1/file-security/status	tenant_admin, security_officer, auditor
Lire la politique	GET /v1/file-security/policy	tenant_admin, security_officer, auditor
Modifier la politique	PUT /v1/file-security/policy	security_officer, tenant_admin
Analyser sans ingérer	POST /v1/file-security/scans	tout membre du tenant
Lister, lire les analyses	GET /v1/file-security/scans, GET /v1/file-security/scans/{scan_id}	lecteurs : toutes ; autres : leurs propres analyses
Réanalyser, purger l'échantillon	POST /v1/file-security/scans/{scan_id}/rescan, DELETE /v1/file-security/scans/{scan_id}/sample	security_officer, tenant_admin
Statistiques	GET /v1/file-security/stats	lecteurs : toutes ; autres : leurs propres analyses

Preuves et détection

• Chaque analyse est auditée (file_security.scan) avec la source (knowledge, media, multimodal, transcription, connector, channel, api), l'empreinte, le verdict et les raisons.
• Un fichier bloqué lève l'événement de sécurité security.file.blocked (ou security.file.scan_unavailable quand les moteurs n'ont pas répondu) ; le scanner d'audit du SOC le transforme en détection pour les verdicts malware et suspicious (soc-runbook.md).
• Le job file_scan_probe (EAI_WORKER_FILE_SCAN_PROBE_SECONDS) mesure l'état des moteurs et l'âge des signatures.

Composants

Composant	Manifeste	Version épinglée	Licence
ClamAV (clamd, freshclam, passerelle HTTPS)	catalog/components/clamav.yaml	1.4.6	GPL-2.0-only
YARA-X (worker de règles)	catalog/components/yara-x.yaml	1.22.1	BSD-3-Clause

Les deux sont installés par le Navin Manager ; voir le guide Sécurité des fichiers.