Skip to content

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é.

ConceptDeveloper

This page has not been translated yet and is shown in French.

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.

Loading diagram…

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

StatutSignificationFinal
PENDINGLe fichier est reçu et attend son tour dans la file.Non
SCANNINGClamAV examine le fichier.Non
CLEANAucune menace détectée. Vous pouvez accepter le fichier.Oui
INFECTEDUne menace est détectée. Le fichier est en quarantaine ; threatName donne son nom.Oui
ERRORL'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.

Pour aller plus loin