Eseguire e verificare il clawback Sophos Email tramite API

L’API Clawback rimuove messaggi Sophos Email già consegnati dalle caselle idonee. Il flusso sicuro ha sempre due fasi: inviare il richiamo una sola volta, quindi interrogare GET /messages/{id}/status fino a ottenere un esito terminale per ogni destinatario accettato. Una risposta 202 conferma l’accettazione del job, non il successo nella casella.

Verificare prerequisiti e confini

Servono un service principal configurato, un bearer token OAuth2 valido, l’UUID del tenant target e l’host API regionale individuato. L’introduzione alla Email Management API spiega famiglie operative e test di lettura. Il runbook pianificato Autenticazione e tenant routing per l’API Sophos Email riunisce token, risoluzione tenant e routing regionale.

Gli esempi usano variabili già validate:

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

SOPHOS_API_HOST è l’host regionale scoperto per il tenant, non ipotizzato. Sostituire l’esempio innocuo SOPHOS_EMAIL_ID. Ogni richiesta usa Authorization: Bearer *** e X-Tenant-ID; segreti e dati completi del messaggio non devono entrare in codice, log o ticket.

Il clawback richiede anche il diritto PDP/clawback e una connessione provider funzionante. Sono rimediabili solo messaggi consegnati con successo a caselle idonee e destinatari idonei. Post-Delivery Protection in Sophos Central tratta connessione, On demand clawback nell’interfaccia e Auto search and remediate. Questi flussi UI sono separati dall’API e non ne sostituiscono il polling.

Ottenere il corretto x-sophos-email-id

Il parametro {id} è il valore dell’header MIME X-Sophos-Email-ID, non l’Internet Message-ID, l’oggetto o un UUID qualsiasi. Sophos indica anche che può essere ricavato da varie risposte di query Email in Live Discover nel Threat Analysis Center. Questo runbook non inventa uno schema: prendere x-sophos-email-id da evidenze affidabili e verificare almeno tenant, messaggio e destinatari interessati.

Inserire il valore senza spazi o ritorni a capo in SOPHOS_EMAIL_ID. Per più messaggi, registrare ogni ID con approvazione e caso; non costruire liste dal solo oggetto simile.

Richiamare un messaggio

L’endpoint documentato è POST /messages/{id}/clawback. Senza recipients, Sophos tenta il richiamo per tutti i destinatari. Usare tale ambito solo se tutti appartengono all’incidente. Per un pilota, indicare gli indirizzi; la specifica consente fino a 500 elementi.

Il reason opzionale è malware, phishing, spam oppure unwanted:

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

Inviare il POST una sola volta e proteggere la risposta:

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"

È atteso 202. La risposta separa i recipients accettati dagli errors, ciascuno con recipient ed error. Registrare l’accettazione per destinatario senza esporre tutta la risposta. Sophos definisce atomica la chiamata singola limitata ai destinatari: un destinatario non idoneo può far fallire l’intera richiesta. Verificare la causa, rimuoverlo solo se giustificato e poi inviare una nuova richiesta consapevole.

Richiamare più messaggi

Per più messaggi, Sophos documenta POST /messages/clawback con una lista messageIds. Ogni elemento è un x-sophos-email-id:

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

La chiamata multipla riduce le richieste, non le verifiche. Registrare accettazione e stato per ogni ID. Se sono coinvolti solo alcuni destinatari di un messaggio, usare l’endpoint singolo con recipients; il payload multiplo documentato non include destinatari.

Eseguire il polling fino all’esito terminale

Per ogni ID usare GET /messages/{id}/status. Sotto items compaiono recipient e status:

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

clawbackProcessing è intermedio. Registrare clawbackSuccessful o clawbackFailed come esito terminale per destinatario. Lo schema può restituire anche accepted, quarantined, deliverySuccessful o deliveryFailed; non interpretarli come successo del 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"

Interrogare con intervallo limitato e jitter finché mancano esiti terminali. Limitare tentativi e durata. Al timeout l’esito è sconosciuto, non fallito: nessun secondo POST finché un GET successivo o Sophos Central non chiarisce l’effetto del primo.

Gestire esiti parziali ed errori

Non idoneo o già rimediato: verificare messaggio, dominio, consegna e destinatario. POST ripetuti non riparano un successo precedente. Dopo un rifiuto atomico, rimuovere indirizzi non idonei solo dopo la verifica.
Stati misti: conservare clawbackSuccessful per i successi e analizzare separatamente clawbackFailed. Non dichiarare riuscito tutto il job né rielaborare i successi.
400: controllare ID, JSON, reason ammesso e destinatari; non ripetere invariato.
401 o 403: rinnovare via OAuth2 o verificare ruolo, diritto clawback e tenant. Non cambiare tenant o regione per tentativi.
404: confrontare host regionale, percorso e x-sophos-email-id con l’evidenza.
Throttling (429): rispettare le indicazioni documentate e rallentare i GET con backoff limitato e jitter. Mai ripetere alla cieca un POST.
Timeout o 5xx: il server potrebbe aver accettato. Interrogare prima lo stesso ID, limitare tentativi e durata, e reinviare solo dopo aver chiarito l’effetto.

La validazione è completa quando, per ogni ID, sono registrati invio, destinatari accettati o rifiutati e ogni esito terminale. Come controllo secondario, verificare casella e Post-Delivery Quarantine nel tenant corretto. La risposta API resta la base machine-readable; clawback UI, PDP automatico e report sono percorsi distinti.