Exécuter et vérifier un clawback Sophos Email par API

L’API Clawback retire des messages Sophos Email déjà livrés aux boîtes éligibles. La procédure sûre comporte toujours deux phases : soumettre le rappel une seule fois, puis interroger GET /messages/{id}/status jusqu’à obtenir un résultat final pour chaque destinataire accepté. Une réponse 202 confirme l’acceptation de la tâche, pas son succès dans la boîte.

Établir les prérequis et les limites

Il faut un service principal configuré, un jeton bearer OAuth2 valide, l’UUID du tenant cible et son hôte API régional découvert. L’introduction à l’Email Management API explique les familles d’opérations et le test de lecture sûr. Le runbook prévu Authentification et routage du tenant pour l’API Sophos Email regroupe jeton, résolution du tenant et routage régional.

Les exemples reprennent des variables déjà validées :

EMAIL_API_HOST="${SOPHOS_API_HOST%/}/email/v1"
SOPHOS_EMAIL_ID="15a7f8ea-691c-4f03-862e-3cefb102818e"

SOPHOS_API_HOST est l’hôte régional découvert pour le tenant, jamais un hôte deviné. Remplacez l’exemple inoffensif SOPHOS_EMAIL_ID. Chaque requête utilise Authorization: Bearer *** et X-Tenant-ID ; les secrets et données complètes des messages ne doivent figurer ni dans le code, ni dans les journaux, ni dans les tickets.

Le clawback exige aussi le droit PDP/clawback approprié et une connexion fournisseur opérationnelle. Seuls les messages déjà livrés avec succès à des boîtes éligibles et leurs destinataires éligibles peuvent être remédiés. Post-Delivery Protection dans Sophos Fusion couvre la connexion, On demand clawback dans l’interface et Auto search and remediate. Ces parcours sont distincts de l’API et ne remplacent pas son polling de statut.

Obtenir le bon x-sophos-email-id

Le paramètre {id} est la valeur de l’en-tête MIME X-Sophos-Email-ID, pas l’Internet Message-ID, l’objet ou un UUID quelconque. Sophos indique aussi que cette valeur peut être dérivée de différentes réponses de requêtes Email dans Live Discover du Threat Analysis Center. Ce runbook n’invente pas de schéma : relevez x-sophos-email-id dans une preuve fiable et vérifiez au minimum le tenant, le message et les destinataires touchés.

Placez la valeur sans espace ni saut de ligne dans SOPHOS_EMAIL_ID. Pour plusieurs messages, consignez chaque ID avec son approbation et son dossier ; ne constituez pas une liste à partir d’objets similaires.

Rappeler un message

Le point de terminaison documenté est POST /messages/{id}/clawback. Sans recipients, Sophos tente le rappel pour tous les destinataires. N’utilisez cette portée large que si tous font partie de l’incident. Pour un pilote, indiquez les adresses ; la spécification autorise au maximum 500 entrées.

La valeur facultative reason est malware, phishing, spam ou unwanted :

{
  "reason": "phishing",
  "recipients": [
    "user1@example.com",
    "user2@example.com"
  ]
}

Envoyez le POST exactement une fois et protégez la réponse :

REQUEST_FILE=$(mktemp) || exit 1
RESPONSE_FILE=$(mktemp) || exit 1
trap 'rm -f "$REQUEST_FILE" "$RESPONSE_FILE"' EXIT

cat >"$REQUEST_FILE" <<'JSON'
{
  "reason": "phishing",
  "recipients": ["user1@example.com", "user2@example.com"]
}
JSON

HTTP_STATUS=$(
  printf 'header = "Authorization: Bearer %s"\n' "$SOPHOS_ACCESS_TOKEN" |
  curl --silent --show-error --config - \
    --output "$RESPONSE_FILE" \
    --write-out '%{http_code}' \
    --request POST \
    --header "X-Tenant-ID: $SOPHOS_TENANT_ID" \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-binary "@$REQUEST_FILE" \
    "$EMAIL_API_HOST/messages/$SOPHOS_EMAIL_ID/clawback"
)
printf 'Clawback submission returned HTTP %s\n' "$HTTP_STATUS"

Le résultat attendu est 202. La réponse sépare les recipients acceptés des errors, chacune avec recipient et error. Consignez l’acceptation par destinataire sans exposer toute la réponse. Sophos décrit l’appel unitaire limité aux destinataires comme atomique : un destinataire non éligible peut faire échouer toute la requête. Vérifiez la cause, retirez-le seulement si cela est justifié, puis soumettez une nouvelle requête délibérée.

Rappeler plusieurs messages

Pour plusieurs messages, le guide Sophos documente POST /messages/clawback avec une liste messageIds. Chaque élément est un x-sophos-email-id :

{
  "messageIds": [
    "e4fa988e-76f6-11ee-b962-0242ac120002",
    "eb9df47e-76f6-11ee-b962-0242ac120002",
    "ef790f0276f611eeb9620242ac120002"
  ]
}

L’appel multiple réduit les requêtes, pas les contrôles. Consignez l’acceptation puis le statut de chaque ID. Si seuls certains destinataires d’un message sont concernés, utilisez le point unitaire avec recipients ; la charge multiple documentée ne contient aucune liste de destinataires.

Suivre jusqu’au résultat final par destinataire

Pour chaque ID soumis, utilisez GET /messages/{id}/status. La réponse contient recipient et status sous items :

{
  "items": [
    {"recipient": "user1@example.com", "status": "clawbackSuccessful"},
    {"recipient": "user2@example.com", "status": "clawbackFailed"}
  ]
}

clawbackProcessing est intermédiaire. Consignez clawbackSuccessful ou clawbackFailed comme résultat final par destinataire. Le schéma peut aussi renvoyer accepted, quarantined, deliverySuccessful ou deliveryFailed ; ne les transformez pas en succès de clawback.

HTTP_STATUS=$(
  printf 'header = "Authorization: Bearer %s"\n' "$SOPHOS_ACCESS_TOKEN" |
  curl --silent --show-error --config - \
    --output "$RESPONSE_FILE" \
    --write-out '%{http_code}' \
    --request GET \
    --header "X-Tenant-ID: $SOPHOS_TENANT_ID" \
    --header 'Accept: application/json' \
    "$EMAIL_API_HOST/messages/$SOPHOS_EMAIL_ID/status"
)
printf 'Clawback status returned HTTP %s\n' "$HTTP_STATUS"

Interrogez à intervalle limité avec jitter tant qu’un destinataire accepté n’a pas de résultat final. Limitez les essais et la durée totale. Au délai d’attente, le résultat est inconnu, pas échoué : aucun second POST avant qu’un GET ultérieur ou Sophos Fusion n’ait établi l’effet du premier.

Traiter prudemment les résultats partiels et les erreurs

Non éligible ou déjà remédié : vérifiez message, domaine, livraison et destinataire. Des POST répétés ne réparent pas un succès antérieur. Après un rejet atomique, ne retirez les adresses non éligibles qu’après ce contrôle.
Statuts mixtes : conservez clawbackSuccessful pour les succès et analysez séparément clawbackFailed. Ne déclarez pas toute la tâche réussie et ne retraitez pas les succès.
400 : vérifiez ID, JSON, reason autorisé et destinataires ; ne répétez pas la requête inchangée.
401 ou 403 : renouvelez via OAuth2 ou vérifiez rôle, droit clawback et rattachement au tenant. Ne changez jamais tenant ou région à titre d’essai.
404 : comparez hôte régional, chemin documenté et x-sophos-email-id avec la preuve.
Limitation (429) : respectez les indications documentées, ralentissez les GET avec backoff borné et jitter, et ne répétez jamais aveuglément un POST.
Timeout ou 5xx : l’acceptation serveur a pu avoir lieu. Interrogez d’abord le même ID, limitez essais et durée, puis ne resoumettez qu’après clarification de l’effet.

La recette est complète quand le résultat de soumission, les destinataires acceptés ou rejetés et chaque résultat final sont consignés pour chaque ID. Contrôlez ensuite la boîte et la Post-Delivery Quarantine du bon tenant. La réponse API reste la base lisible par la machine ; clawback UI, PDP automatique et rapports sont des parcours distincts.