Aller au contenu

Antivirus

Soumettre un fichier au scan antivirus, suivre son statut et recevoir le résultat par webhook signé.

RéférenceDéveloppeur
Voir en Markdown

Le module antivirus analyse les fichiers que vos utilisateurs envoient, avant que votre application ne les accepte. L'analyse est asynchrone : vous soumettez le fichier, puis vous lisez son statut ou vous recevez le résultat sur votre propre URL.

Chaque scan consomme 1 crédit du client, débité à la soumission. L'appel doit porter un client et une application : utilisez le jeton d'un utilisateur de l'application ou une clé API liée à un client.

Cycle de vie d'un scan

Chargement du schéma…

Un fichier déclaré INFECTED est placé en quarantaine. Un fichier identique, déjà déclaré infecté pour le même client et la même application, est déclaré infecté immédiatement.

L'objet Scan

ChampTypeDescription
idUUIDIdentifiant du scan
statuschaînePENDING, SCANNING, CLEAN, INFECTED ou ERROR
filenamechaîneNom d'origine du fichier
fileSizeentierTaille en octets
mimeTypechaîneType déclaré à l'envoi
fileHashchaîne (64)Empreinte SHA-256, calculée pendant le scan
priorityentier, 1 à 10Priorité de traitement, 1 étant la plus haute (défaut 5)
callbackUrlchaîne ou nullURL de rappel
threatNamechaîne ou nullNom de la menace détectée
threatSeveritychaîne ou nullHIGH pour un fichier infecté
scanEngine, signatureVersionchaîne ou nullMoteur et version des signatures
scanDurationMsentier ou nullDurée de l'analyse
errorMessagechaîne ou nullCause d'un statut ERROR
queuedAt, startedAt, completedAtchaîne ISO 8601 ou nullDates de mise en file, de début et de fin

Soumettre un fichier

POST/api/antivirus/scans

Droit requis : antivirus.scan. Corps multipart/form-data.

ChampTypeObligatoireContraintesDescription
filefichieroui100 Mo au plusFichier à analyser
callbackUrlchaînenonHTTPS, adresse publique, 500 caractères au plusURL qui recevra le résultat
callbackSecretchaînenon64 caractères au plusSecret de signature du webhook. Obligatoire pour recevoir le webhook
priorityentiernon1 à 10Défaut 5

Si une politique de scan est définie pour votre client ou votre application, le fichier doit en respecter la taille maximale, les types MIME autorisés et les extensions bloquées. Le type est déterminé d'après le contenu du fichier, pas d'après son nom.

Bash
curl -s -X POST https://api.wakastart.app/api/antivirus/scans \
  -H "x-api-key: sk_test_exemple" \
  -F "file=@ordonnance.pdf" \
  -F "callbackUrl=https://api.mon-app.exemple.fr/webhooks/antivirus" \
  -F "callbackSecret=$ANTIVIRUS_WEBHOOK_SECRET"
TypeScript
const form = new FormData();
form.append("file", new Blob([buffer], { type: "application/pdf" }), "ordonnance.pdf");
form.append("callbackUrl", "https://api.mon-app.exemple.fr/webhooks/antivirus");
form.append("callbackSecret", process.env.ANTIVIRUS_WEBHOOK_SECRET!);

const res = await fetch("https://api.wakastart.app/api/antivirus/scans", {
  method: "POST",
  headers: { "x-api-key": process.env.WAKASTART_API_KEY! },
  body: form,
});
const scan = await res.json(); // scan.status === "PENDING"

Réponse 201

JSON
{
  "id": "8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77",
  "status": "PENDING",
  "filename": "ordonnance.pdf",
  "fileSize": 182344,
  "mimeType": "application/pdf",
  "priority": 5,
  "callbackUrl": "https://api.mon-app.exemple.fr/webhooks/antivirus",
  "queuedAt": "2026-10-23T09:20:00.000Z"
}

Erreurs

StatutMessageCause
400Fichier requisAucun fichier dans le champ file
400Antivirus service errorFichier refusé par la politique (taille, type, extension), secret trop long ou appel sans client ni application
402Antivirus service errorCrédits insuffisants pour le client
413File too largeFichier de plus de 100 Mo
503Antivirus service error ou Antivirus service unavailableService momentanément indisponible ; le scan n'est pas créé

Suivre le statut d'un scan

GET/api/antivirus/scans/{id}/status

Droit requis : antivirus.read. Réponse légère, adaptée à une interrogation régulière.

Bash
curl -s https://api.wakastart.app/api/antivirus/scans/8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77/status \
  -H "x-api-key: sk_test_exemple"

Réponse 200

JSON
{ "id": "8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77", "status": "CLEAN", "filename": "ordonnance.pdf", "completedAt": "2026-10-23T09:20:04.000Z" }

Interrogez toutes les quelques secondes, avec un délai croissant, jusqu'à un statut final : CLEAN, INFECTED ou ERROR.

Lire le détail d'un scan

GET/api/antivirus/scans/{id}

Droit requis : antivirus.read. Réponse : l'objet Scan complet, avec la menace détectée et l'empreinte du fichier. Le secret de rappel n'est jamais renvoyé.

Erreurs (pour les deux lectures) : 400 Validation failed (uuid is expected) ; 404 Antivirus service error si le scan n'existe pas ou appartient à un autre client.

Recevoir le résultat par webhook

Si vous avez fourni callbackUrl et callbackSecret, Wakastart envoie le résultat à votre URL dès la fin du scan, pour les statuts CLEAN et INFECTED. Aucun webhook n'est envoyé pour ERROR : interrogez alors le statut.

Requête reçue :

HTTP
POST /webhooks/antivirus HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: 5f2b1c…e9a0
X-Webhook-Timestamp: 2026-10-23T09:20:04.512Z

{
  "scanId": "8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77",
  "status": "CLEAN",
  "filename": "ordonnance.pdf",
  "fileHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "completedAt": "2026-10-23T09:20:04.000Z"
}
ÉlémentDescription
X-Webhook-SignatureHMAC-SHA256 du corps brut, avec votre callbackSecret, en hexadécimal
X-Webhook-TimestampDate d'envoi ; elle ne fait pas partie de la signature
threatNamePrésent dans le corps quand status vaut INFECTED

Vérifiez la signature sur le corps brut, avant tout traitement :

TypeScript
import { createHmac, timingSafeEqual } from "node:crypto";

export function isValidAntivirusWebhook(rawBody: Buffer, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Répondez 2xx en moins de 10 secondes. En cas d'échec, Wakastart réessaie deux fois (après 1 puis 4 secondes). Traitez le webhook de façon idempotente en vous fondant sur scanId.