Cycle de vie d'une analyse
Les statuts d'un scan antivirus, leurs transitions, les nouvelles tentatives automatiques et le moment où un crédit est consommé.
Une analyse antivirus est un traitement asynchrone : l'API vous répond avant que ClamAV ait examiné le fichier. Le statut du scan vous dit où en est le traitement, et seul un statut final vous autorise à décider du sort du fichier.
Définition
Un scan est l'enregistrement que Wakastart crée à chaque fichier envoyé à POST /api/antivirus/scans. Il porte un identifiant UUID, le nom et la taille du fichier, son statut et, une fois l'analyse finie, le verdict.
Un scan appartient au client et à l'application de l'appelant. Tout utilisateur ou toute clé du même client disposant du droit Voir le module antivirus peut le consulter.
Pourquoi c'est asynchrone
Analyser un fichier prend de quelques centaines de millisecondes à plusieurs secondes selon sa taille et sa structure (une archive est examinée fichier par fichier). Répondre tout de suite évite de bloquer la requête de votre serveur, et donc celle de votre utilisateur, pendant l'analyse. Une file d'attente absorbe aussi les pics d'envoi.
Comment ça marche
Les statuts
| Statut | Signification | Final |
|---|---|---|
PENDING | Le fichier est reçu et attend son tour dans la file. | Non |
SCANNING | ClamAV examine le fichier. | Non |
CLEAN | Aucune menace détectée. Vous pouvez accepter le fichier. | Oui |
INFECTED | Une menace est détectée. Le fichier est en quarantaine ; threatName donne son nom. | Oui |
ERROR | L'analyse a échoué pour une raison technique. errorMessage en donne la cause. | Après trois tentatives |
Les nouvelles tentatives
Un incident technique (moteur momentanément injoignable, délai de 30 secondes dépassé) fait passer le scan en ERROR. Wakastart relance alors l'analyse automatiquement, jusqu'à trois tentatives au total, avec un délai croissant entre elles (5 s, puis 10 s). Entre deux tentatives, vous pouvez donc voir ERROR puis de nouveau SCANNING.
Un scan resté en ERROR après la troisième tentative est définitif. Il ne déclenche pas de webhook : seule l'interrogation de l'API vous le signale.
La file d'attente et la priorité
Chaque scan porte une priorité de 1 à 10, 5 par défaut. 1 est la priorité la plus haute : un scan de priorité 1 passe devant ceux de priorité 5. Trois analyses tournent en parallèle ; les autres attendent leur tour.
Le cache d'empreinte
Wakastart calcule l'empreinte SHA-256 de chaque fichier. Si un fichier de même empreinte a déjà été déclaré INFECTED pour le même client et la même application, le nouveau scan est déclaré INFECTED sans repasser par le moteur. Le champ threatName reprend alors le nom de la menace connue.
La consommation de crédits
Chaque envoi consomme 1 crédit, débité sur le solde du client à la réception de la demande, avant l'analyse. Le crédit est consommé quel que soit le verdict : CLEAN, INFECTED ou ERROR. Sans crédit disponible, l'API refuse l'envoi avec une erreur 402.
Exemples
- Une plateforme de recrutement reçoit des CV. Son serveur envoie chaque CV avec un webhook, enregistre le fichier comme « en cours de vérification », puis le rend visible aux recruteurs à la réception du verdict
CLEAN. - Un import nocturne de 2 000 pièces jointes envoie les fichiers en priorité 8, pour laisser passer devant lui les téléversements des utilisateurs connectés, envoyés en priorité 5.
- Un justificatif d'identité attendu en direct par un conseiller est envoyé en priorité 1.