Sophos Email Clawback per API ausführen und prüfen

Mit der Clawback-API zieht man bereits zugestellte Sophos-Email-Nachrichten aus berechtigten Empfängerpostfächern zurück. Der sichere Ablauf besteht immer aus zwei Phasen: den Rückruf einmal anstossen und danach GET /messages/{id}/status abfragen, bis für jeden akzeptierten Empfänger ein Endergebnis vorliegt. Eine 202-Antwort bestätigt nur die Annahme des Auftrags, nicht dessen Erfolg im Postfach.

Voraussetzungen und Grenzen klären

Vor dem ersten Rückruf müssen ein Service Principal, ein gültiger OAuth2-Bearer-Token, die UUID des Ziel-Tenants und dessen regionaler API-Host vorliegen. Der Einstieg in die Email Management API ordnet die Operationsfamilien und den sicheren Lesetest ein. Das geplante Detail-Runbook Authentifizierung und Tenant-Routing für die Sophos Email API beschreibt Token, Tenantauflösung und Regionalhost zusammenhängend.

Für die Beispiele werden diese bereits validierten Variablen übernommen:

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

SOPHOS_API_HOST ist der für den Tenant ermittelte Regionalhost, nicht ein aus der Region erratener Host. SOPHOS_EMAIL_ID ist ein harmloser Beispielwert und muss ersetzt werden. Jeder Request verwendet Authorization: Bearer *** und X-Tenant-ID; Geheimnisse und vollständige Nachrichtendaten gehören nicht in Code, Logs oder Tickets.

Clawback benötigt ausserdem die entsprechende PDP-/Clawback-Berechtigung und eine funktionierende Provider-Anbindung. Nur bereits erfolgreich an berechtigte Postfächer zugestellte Nachrichten und Empfänger können bereinigt werden. Post-Delivery Protection in Sophos Fusion behandelt Verbindung, On demand clawback in der Oberfläche und Auto search and remediate. Diese GUI-Abläufe sind keine API-Requests: Der manuelle UI-Rückruf ist eine separate Bedienart, automatische PDP-Bereinigung hat einen eigenen Auslöser, und keines von beiden ersetzt das API-Status-Polling.

Die richtige x-sophos-email-id beschaffen

Der Pfadparameter {id} ist der Wert des MIME-Headers X-Sophos-Email-ID, nicht die Internet-Message-ID, ein Betreff oder eine beliebige UUID. Sophos dokumentiert ausserdem, dass sich dieser Wert aus verschiedenen Email-Abfrageantworten in Live Discover im Threat Analysis Center ableiten lässt. Das genaue Abfrageschema wird hier nicht erfunden: Man übernimmt das Feld x-sophos-email-id aus belastbarer Nachrichtenevidenz und gleicht vor dem Rückruf mindestens Tenant, Nachricht und betroffene Empfänger ab.

Den Wert ohne Leerzeichen oder Zeilenumbruch in SOPHOS_EMAIL_ID setzen. Bei mehreren Nachrichten wird jede ID zusammen mit ihrem Freigabe- und Fallbezug dokumentiert; eine Liste wird nicht allein anhand ähnlicher Betreffzeilen aufgebaut.

Eine Nachricht zurückrufen

Der belegte Einzelendpunkt lautet POST /messages/{id}/clawback. Ohne recipients versucht Sophos den Rückruf für alle Empfänger der Nachricht. Das ist ein breiterer Eingriff und wird nur gewählt, wenn wirklich alle Empfänger zum Incident gehören. Für einen begrenzten Pilot werden die Zieladressen ausdrücklich angegeben; die Spezifikation erlaubt höchstens 500 Einträge.

Der optionale Wert reason ist gemäss geprüfter API-Spezifikation einer von malware, phishing, spam oder unwanted. Dieses Beispiel begrenzt den Vorgang auf zwei kontrollierte Empfänger:

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

Den POST genau einmal senden und die Antwort geschützt speichern:

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"

Erwartet wird 202. Die Antwort trennt recipients, für die der Auftrag angenommen wurde, von errors mit recipient und error. Diese Annahme wird pro Empfänger protokolliert, ohne die vollständige Antwort ungeschützt abzulegen. Laut Sophos ist der empfängerbegrenzte Einzelaufruf atomar: Ist ein ausgewählter Empfänger nicht clawback-fähig, kann der ganze Request scheitern. Dann den ungeeigneten Empfänger erst nach Prüfung entfernen und einen bewusst neuen Request senden.

Mehrere Nachrichten zurückrufen

Für mehrere Nachrichten dokumentiert der Sophos-Leitfaden POST /messages/clawback mit einer messageIds-Liste. Jede Position ist eine x-sophos-email-id:

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

Der Mehrfachaufruf spart Requests, ersetzt aber nicht die Einzelkontrolle. Die Annahme und anschliessend der Status werden je ID festgehalten. Wenn nur einzelne Empfänger einer Nachricht betroffen sind, verwendet man stattdessen den Einzelendpunkt mit recipients; die dokumentierte Mehrfach-Payload enthält keine Empfängerliste.

Asynchron bis zum Empfänger-Endstatus prüfen

Für jede eingereichte ID lautet der belegte Leseendpunkt GET /messages/{id}/status. Eine Antwort enthält unter items jeweils recipient und status:

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

clawbackProcessing ist ein Zwischenstatus. clawbackSuccessful und clawbackFailed sind die zu dokumentierenden Clawback-Endergebnisse je Empfänger. Die Spezifikation kann auch Zustellzustände wie accepted, quarantined, deliverySuccessful oder deliveryFailed liefern; diese werden nicht als erfundener Clawback-Erfolg umgedeutet.

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"

Mit einem begrenzten Intervall und Jitter erneut abfragen, solange akzeptierte Empfänger noch kein Endergebnis haben. Eine maximale Gesamtdauer und Versuchszahl verhindern Endlosschleifen. Nach Ablauf bleibt das Ergebnis unbekannt, nicht fehlgeschlagen: kein zweiter POST, bevor ein späterer GET oder die Sophos-Fusion-Ansicht geklärt hat, ob der erste Auftrag wirksam wurde.

Teilresultate und Fehler sicher behandeln

Nicht berechtigt oder bereits bereinigt: Nachricht, Domain, Zustellung und Empfänger prüfen. Ein bereits erfolgreich zurückgerufener Empfänger wird nicht durch wiederholte POSTs repariert. Bei einem atomar abgewiesenen Einzelrequest nur nach dieser Prüfung ungeeignete Adressen entfernen.
Gemischte Empfängerstatus: clawbackSuccessful bleibt für erfolgreiche Empfänger gültig, während clawbackFailed separat untersucht wird. Nicht den ganzen Auftrag pauschal als Erfolg melden und erfolgreiche Empfänger nicht erneut bearbeiten.
400: ID, JSON, erlaubten reason und Empfängerliste prüfen. Request nicht unverändert wiederholen.
401 oder 403: Token über den OAuth2-Ablauf erneuern beziehungsweise Rolle, Clawback-Berechtigung und Tenantzuordnung prüfen. Nie Tenant oder Region versuchsweise wechseln.
404: Regionalhost, dokumentierten Pfad und x-sophos-email-id gegen die Nachrichtenevidenz prüfen.
Drosselung (429): dokumentierte Retry-/Rate-Limit-Hinweise beachten und GET-Abfragen mit begrenztem Backoff und Jitter verlangsamen. Einen POST nicht blind erneut senden.
Timeout oder 5xx: Eine serverseitige Annahme kann trotz fehlender Clientantwort erfolgt sein. Zuerst den Status derselben ID abfragen, Versuche und Gesamtdauer begrenzen und nur nach geklärter Wirkung kontrolliert neu einreichen.

Die Abnahme ist vollständig, wenn für jede angeforderte ID der Einreichungsstatus, angenommene und abgewiesene Empfänger sowie jedes terminale Empfängerergebnis festgehalten sind. Als Nachkontrolle kann man Postfach und Post-Delivery-Quarantäne im passenden Tenant prüfen. Die API-Antwort bleibt jedoch die maschinenlesbare Grundlage des Automationslaufs; UI-Clawback, automatische PDP und Berichte sind getrennte Betriebswege.