Sécurité des fichiers : ClamAV et YARA-X avant toute ingestion

Version anglaise : file-security. Décision : ADR-0166. Référence API : control-plane-v1.

Aucun fichier déposé par un utilisateur, un agent ou un connecteur n'atteint Docling, l'OCR, le stockage des médias, la transcription, le RAG ou un modèle avant d'avoir été analysé par ClamAV (antivirus) et YARA-X (règles de détection). Tout est installé et mis à jour localement : aucune signature ni règle n'est lue sur Internet.

1. Pipeline obligatoire

Upload → Quarantaine → ClamAV + YARA-X → Validation → Docling → RAG / IA

Étape	Ce qui se passe
Upload	Une route d'ingestion reçoit les octets du fichier (base64 ou multipart).
Quarantaine	Un enregistrement d'analyse est créé à l'état `quarantined` avant toute lecture du contenu ; un arrêt brutal le laisse en quarantaine, jamais libéré.
ClamAV + YARA-X	Contrôles intégrés (taille, type réel lu dans les octets, fichier chiffré, archive, imbrication), puis les deux moteurs, obligatoires.
Validation	Le verdict et la politique du tenant décident : `released` seulement si tout est propre, sinon `blocked`. Une libération produit une autorisation d'analyse liée au sha256 des octets.
Docling	La conversion, l'OCR, le stockage des médias et la transcription exigent cette autorisation : sans elle, ou pour d'autres octets, ils refusent de s'exécuter.
RAG / IA	Le texte extrait passe encore le filtrage existant (marqueurs d'injection de prompt, texte caché, quarantaine du RAG) : l'antivirus ne protège pas des injections de prompt.

Routes concernées : POST /v1/knowledge-bases/{kb_id}/documents, POST /v1/media, POST /v1/multimodal/vision, POST /v1/multimodal/stt, POST /v1/multimodal/diarize, POST /v1/multimodal/dlp, POST /v1/multimodal/images/edit, POST /v1/multimodal/video/process et POST /v1/gateway/audio/transcriptions. Un fichier bloqué donne 422 file_blocked (details.scan_id, details.verdict, details.reasons) ; aucun moteur joignable donne 503 file_scan_unavailable.

2. Installation par le Navin Manager

Les deux services se trouvent dans la catégorie Sécurité et politiques du catalogue : navin-manager/catalog/services/clamav.yaml et navin-manager/catalog/services/yara-x.yaml.

Service	Rôle	Licence	Modes	Documentation officielle
ClamAV 1.4.6 LTS	Antivirus : virus, chevaux de Troie, macros malveillantes, fichiers infectés, archives	GPL-2.0-only (processus séparé, exception LEX-022)	`standalone`, `replicated` (2 hôtes ou plus)	https://docs.clamav.net/
YARA-X 1.22.1	Détection par règles, signatures et motifs suspects	BSD-3-Clause (exception LEX-023)	`standalone`, `replicated` (2 workers ou plus)	https://virustotal.github.io/yara-x/

Sur chaque hôte ClamAV, clamd n'écoute que sur la boucle locale et une socket locale : son protocole n'a ni TLS ni authentification. Une passerelle HTTPS authentifiée par clé ne transmet que INSTREAM, PING et VERSION. freshclam ne lit que le miroir interne déclaré dans le paramètre mirror_url (https obligatoire, aucune valeur par défaut). Prévoir environ 3 Go de mémoire par hôte pour la base complète. Le worker YARA-X sert ses règles compilées en HTTPS, avec la même autorité de certification que la console du Manager.

ClamAV s'installe par la méthode podman avec l'image officielle docker.io/clamav/clamav:1.4.6 (et une image Python épinglée pour la passerelle), servies par le miroir du Manager : les paquets des distributions n'épinglent pas la version 1.4.6 et leurs unités visent les serveurs publics de mise à jour. YARA-X s'installe par la méthode python (roue yara-x==1.22.1 du miroir). Le paquet hors ligne du Manager accepte les bases de signatures (--clamav-databases) et les règles (--yara-rules), vérifiées par verify-bundle.

Le service navin-enterprise exige les deux liaisons : le Manager rend pour la plateforme les adresses de toutes les instances, les clés et l'autorité de certification, et impose EAI_FILE_SCAN_MODE=enforce.

3. Réglages de la plateforme

Réglage	Rôle
`EAI_FILE_SCAN_MODE`	`enforce` (obligatoire en production, exigé par la garde de démarrage) ou `dev` (développement : un moteur non configuré est noté `not_configured`, un moteur configuré s'applique comme en `enforce`).
`EAI_CLAMAV_URLS`	Passerelles ClamAV séparées par des virgules, toutes en https ; une adresse de répartiteur est aussi acceptée.
`EAI_CLAMAV_API_KEY`	Clé des passerelles ClamAV.
`EAI_YARAX_URLS`	Workers YARA-X séparés par des virgules, tous en https.
`EAI_YARAX_API_KEY`	Clé des workers YARA-X.
`EAI_FILE_SCAN_CA_FILE`	Autorité de certification (PEM) des passerelles et des workers.
`EAI_FILE_SCAN_TIMEOUT_SECONDS`	Délai d'une analyse par moteur (60 s par défaut).
`EAI_FILE_SCAN_MAX_BYTES`	Plafond de taille de la plateforme ; la politique d'un tenant peut seulement le baisser.

4. Verdicts et blocages

Verdict	Cause	Résultat
`clean`	Aucun moteur ni contrôle ne signale le fichier (les signalements des règles en mode `report` sont journalisés)	`released`
`malware`	Signature ClamAV ou règle YARA-X de verdict malware	`blocked`
`suspicious`	Macro Office (`block_office_macros`), PUA, règle YARA-X suspecte	`blocked`
`unscannable`	Fichier ou archive chiffré, limites d'analyse dépassées, exécutable cassé, imbrication excessive	`blocked`
`policy_violation`	Taille, type non autorisé, type déclaré différent du type réel, archive interdite	`blocked`
`scan_error`	Erreur ou délai dépassé sur toutes les instances d'un moteur	`blocked`

La précédence va de malware à clean dans l'ordre du tableau. Les échantillons ne sont conservés que pour les fichiers bloqués, chiffrés au repos, purgés après quarantine_retention_days ; un fichier libéré n'est jamais conservé par ce pipeline.

Les règles de base navin-baseline de YARA-X bloquent par défaut : le fichier de test EICAR, les documents Office avec projet VBA ou macro à exécution automatique, les PDF avec JavaScript déclenché par une action (y compris les formulaires PDF remplissables qui contiennent des scripts de mise en forme), les PDF avec action Launch ou fichier incorporé à exécution automatique, les exécutables Windows incorporés dans un document, les objets OLE piégés des RTF, le HTML smuggling et les scripts qui téléchargent puis exécutent une charge (PowerShell, Windows Script Host, shell). Pour seulement journaliser une famille de fichiers légitimes chez la banque, publier dans le dépôt interne une version des règles où cette règle porte action = "report".

ClamAV lit seulement le début d'un membre de ZIP plus gros que MaxFileSize sans le signaler : la passerelle ClamAV et la plateforme lisent le répertoire central de chaque ZIP (zip, docx, xlsx, pptx, odt...) avant l'analyse et classent unscannable un membre ou un total au-delà des limites (EAI_FILE_SCAN_ARCHIVE_MAX_MEMBER_BYTES, EAI_FILE_SCAN_ARCHIVE_MAX_TOTAL_BYTES), pour qu'aucune partie d'un fichier ne passe sans être analysée.

5. Politique du tenant

GET /v1/file-security/policy donne la politique effective ; PUT /v1/file-security/policy (security_officer, tenant_admin) la modifie et l'audite. Les règles verrouillées ne se modifient pas (422 file_security_rule_locked) : analyse avant toute ingestion, deux moteurs obligatoires, échec fermé, blocage des malwares et des fichiers non inspectables.

{"max_file_bytes": 26214400, "allow_archives": false, "block_office_macros": true,
 "block_type_mismatch": true, "retain_samples": true, "quarantine_retention_days": 30,
 "max_signature_age_hours": 48, "stale_signatures": "block"}

stale_signatures à block bloque toute analyse tant que la base ClamAV la plus ancienne dépasse max_signature_age_hours ; à warn, l'âge est seulement signalé dans l'état et les alertes.

6. Mise à jour contrôlée des signatures et des règles

Depuis la fiche du service dans la console du Navin Manager :

Commande	Service	Effet
`signature_status`	clamav	Version et date des bases installées sur chaque hôte.
`update_signatures`	clamav	freshclam depuis le miroir interne seulement, puis rechargement de clamd.
`import_signatures`	clamav	Import hors ligne d'un répertoire : chaque base est vérifiée par sigtool avant une installation atomique, puis clamd recharge.
`rules_status`	yara-x	Version, sha256 et nombre de règles chargées.
`update_rules`	yara-x	Téléchargement depuis le dépôt interne (`rules_repository_url`, https), contrôle du sha256 attendu, compilation en zone de préparation, bascule atomique ; tout échec garde les règles actives.
`rollback_rules`	yara-x	Retour à la version précédente des règles.

Le miroir interne de signatures se prépare selon https://docs.clamav.net/appendix/CvdPrivateMirror.html. GET /v1/file-security/status montre pour chaque instance la version des signatures, leur âge et la version des règles.

7. Journalisation et alertes

Chaque analyse est un enregistrement (GET /v1/file-security/scans, GET /v1/file-security/scans/{scan_id}) avec le sha256, le type réel, le résultat de chaque moteur et les raisons, et un événement d'audit.
Chaque blocage émet l'événement de sécurité security.file.blocked et une détection du SOC ; une indisponibilité des moteurs émet security.file.scan_unavailable.
Métriques : eai_file_scans_total, eai_file_scan_duration_seconds, eai_file_scan_engine_up, eai_file_scan_signature_age_hours, eai_file_scan_engine_errors_total.
Règles d'alerte livrées par le Manager (navin-manager/catalog/templates/prometheus/rules.yml.j2) : NavinFileMalwareBlocked, NavinFileScanEngineDown, NavinFileScanSignaturesStale, NavinFileScanBlockedSpike.
GET /v1/file-security/stats résume une fenêtre (24 h par défaut) ; POST /v1/file-security/scans/{scan_id}/rescan réanalyse un échantillon conservé sans jamais libérer l'envoi d'origine ; DELETE /v1/file-security/scans/{scan_id}/sample purge l'échantillon.

L'écran Sécurité des fichiers du portail réunit le pipeline, l'état des moteurs, les analyses, les fichiers bloqués, la politique et le test d'un fichier (POST /v1/file-security/scans).

8. Haute disponibilité

Avec deux passerelles ClamAV et deux workers YARA-X ou plus (mode replicated), le client de la plateforme essaie chaque instance à tour de rôle et écarte un court moment une instance en panne : la perte d'un hôte ne bloque pas l'ingestion. La perte de toutes les instances d'un moteur bloque l'ingestion (503), comme voulu. Placer les instances sur des hôtes et des domaines de panne distincts ; les contrôles HA du Manager le vérifient à l'installation.

9. SDK

from enterprise_ai import EnterpriseAI

client = EnterpriseAI()
print(client.file_security.status()["ready"])
scan = client.file_security.scan(open("contrat.pdf", "rb").read(), filename="contrat.pdf")
print(scan["status"], scan["verdict"], scan["reasons"])

Les SDK TypeScript (client.fileSecurity), Java (client.fileSecurity()) et Go (client.FileSecurity) exposent les mêmes méthodes : état, politique, analyse, liste, détail, réanalyse, purge de l'échantillon et statistiques.

10. Procédures

L'écran est Sécurité et gouvernance > Sécurité des fichiers (portal/src/screens/file-security.tsx), ouvert à platform_admin, tenant_admin, security_officer et auditor, avec les onglets Moteurs, Analyses, Fichiers bloqués et Règles.

Vérifier que la plateforme est prête à analyser. Les envois sont refusés tant que les moteurs ne répondent pas (échec fermé) : vérifiez les moteurs avant d'ouvrir l'ingestion aux utilisateurs.

Écran : Sécurité des fichiers > Moteurs. API : GET /v1/file-security/status.

Résultat attendu : le mode est enforce, l'état est Prêt, chaque passerelle ClamAV et chaque worker YARA-X est En ligne et les signatures ne sont pas périmées.

En cas d'échec : « Non configuré » signale un moteur non installé ou une adresse manquante (installez-le avec le Navin Manager) ; « Hors ligne » sur toutes les instances signale que l'ingestion répond 503 file_scan_unavailable ; « Signatures périmées » demande de lancer update_signatures depuis la fiche du service dans le Navin Manager.
Tester un fichier. Le fichier passe la quarantaine, ClamAV, YARA-X et les règles comme un envoi, mais il n'est jamais ingéré.

Écran : Sécurité des fichiers > Tester un fichier, choisissez le fichier, Analyser. API : POST /v1/file-security/scans.

Résultat attendu : le verdict et les motifs ; Ouvrir l'analyse montre le résultat de chaque moteur.

En cas d'échec : 503 file_scan_unavailable (aucun moteur joignable) ; un verdict autre que clean est la réponse attendue pour un fichier dangereux, par exemple le fichier de test EICAR est blocked.
Examiner un fichier bloqué. Un fichier bloqué reste en quarantaine avec son échantillon chiffré quand retain_samples est actif.

Écran : Sécurité des fichiers > Fichiers bloqués, ouvrez l'analyse, puis Réanalyser ou Purger l'échantillon. API : POST /v1/file-security/scans/{scan_id}/rescan, DELETE /v1/file-security/scans/{scan_id}/sample.

Résultat attendu : une réanalyse crée une nouvelle analyse sans jamais libérer l'envoi d'origine ; une purge supprime définitivement l'échantillon, l'enregistrement et son verdict restent.

En cas d'échec : 409 file_sample_unavailable signale qu'aucun échantillon n'est conservé (déjà purgé ou retain_samples désactivé).
Modifier les règles du tenant. Seul un responsable sécurité ou un administrateur du tenant les modifie, et chaque modification est auditée.

Écran : Sécurité des fichiers > Règles, modifiez les règles du tenant, Enregistrer les règles. API : PUT /v1/file-security/policy.

Résultat attendu : « Règles enregistrées. » ; GET /v1/file-security/policy renvoie la nouvelle politique effective.

En cas d'échec : 422 file_security_rule_locked signale une règle verrouillée (analyse avant toute ingestion, moteurs obligatoires, échec fermé, blocage des logiciels malveillants et des fichiers inanalysables) ; 422 invalid_request nomme le champ refusé (details.field), par exemple une valeur hors bornes ou un type inconnu.

11. Dépannage

Statut	Code	Cause	Correction
422	`file_blocked`	le fichier a été bloqué (`details.verdict`, `details.reasons`)	lisez l'analyse `details.scan_id` ; une famille légitime n'est permise que par une version des règles avec `action = "report"`
503	`file_scan_unavailable`	aucune instance d'un moteur ne répond	consultez l'onglet des moteurs, relancez les instances avec le Navin Manager
422	`file_security_rule_locked`	une règle verrouillée a été modifiée	gardez les règles verrouillées, ne modifiez que les règles du tenant
409	`file_sample_unavailable`	aucun échantillon conservé pour cette analyse	renvoyez le fichier
403	`tenant_required`	un appel sans tenant	appelez avec un identifiant de tenant
404	`not_found`	analyse inconnue	vérifiez `scan_id` et le tenant

1. Pipeline obligatoire​

2. Installation par le Navin Manager​

3. Réglages de la plateforme​

4. Verdicts et blocages​

5. Politique du tenant​

6. Mise à jour contrôlée des signatures et des règles​

7. Journalisation et alertes​

8. Haute disponibilité​

9. SDK​

10. Procédures​

11. Dépannage​

12. Étapes suivantes​