Sophos Email-clawback via de API uitvoeren en controleren

De Clawback API verwijdert reeds geleverde Sophos Email-berichten uit geschikte mailboxen. De veilige werkwijze heeft twee fasen: dien de clawback één keer in en vraag daarna GET /messages/{id}/status op totdat elke geaccepteerde ontvanger een eindresultaat heeft. Een 202 bevestigt alleen acceptatie van de taak, niet het succes in de mailbox.

Vereisten en grenzen vaststellen

U hebt een geconfigureerde service principal, een geldige OAuth2-bearertoken, de UUID van de doeltenant en diens ontdekte regionale API-host nodig. De introductie van de Email Management API beschrijft de operation families en veilige leestest. Het geplande runbook Authenticatie en tenantroutering voor de Sophos Email API brengt token, tenantresolutie en regionale routering samen.

De voorbeelden gebruiken reeds gevalideerde variabelen:

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

SOPHOS_API_HOST is de voor de tenant ontdekte regionale host, niet een gegokte host. Vervang de onschuldige SOPHOS_EMAIL_ID. Elke aanvraag gebruikt Authorization: Bearer *** en X-Tenant-ID; geheimen en volledige berichtgegevens horen niet in code, logs of tickets.

Clawback vereist ook de juiste PDP/clawback-aanspraak en een werkende providerverbinding. Alleen succesvol aan geschikte mailboxen geleverde berichten en geschikte ontvangers kunnen worden hersteld. Post-Delivery Protection in Sophos Fusion behandelt de verbinding, On demand clawback in de UI en Auto search and remediate. Deze UI-routes staan los van de API en vervangen API-statuspolling niet.

De juiste x-sophos-email-id verkrijgen

De padparameter {id} is de waarde van de MIME-header X-Sophos-Email-ID, niet de internet-Message-ID, het onderwerp of een willekeurige UUID. Sophos vermeldt ook dat deze waarde kan worden afgeleid uit diverse Email-queryresultaten in Live Discover van Threat Analysis Center. Dit runbook verzint geen queryschema: haal x-sophos-email-id uit betrouwbaar berichtbewijs en controleer minimaal tenant, bericht en betrokken ontvangers.

Plaats de waarde zonder spaties of regeleinden in SOPHOS_EMAIL_ID. Leg bij meerdere berichten elke ID vast met goedkeuring en case; maak geen lijst op basis van vergelijkbare onderwerpen.

Eén bericht terughalen

Het gedocumenteerde endpoint is POST /messages/{id}/clawback. Zonder recipients probeert Sophos alle ontvangers van het bericht. Gebruik die brede scope alleen wanneer iedereen bij het incident hoort. Geef voor een pilot de adressen op; de specificatie staat maximaal 500 items toe.

De optionele reason is malware, phishing, spam of unwanted:

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

Verstuur de POST precies één keer en bescherm het antwoord:

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"

Verwacht 202. Het antwoord scheidt geaccepteerde recipients van errors, elk met recipient en error. Leg acceptatie per ontvanger vast zonder het hele antwoord bloot te leggen. Sophos noemt de tot ontvangers beperkte enkelvoudige aanvraag atomair: één ongeschikte ontvanger kan alles laten mislukken. Controleer de oorzaak, verwijder de ontvanger alleen indien gerechtvaardigd en dien bewust één nieuwe aanvraag in.

Meerdere berichten terughalen

Sophos documenteert POST /messages/clawback met een lijst messageIds. Elk item is een x-sophos-email-id:

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

De bulkcall bespaart aanvragen, niet controles. Leg acceptatie en status per ID vast. Zijn slechts enkele ontvangers van één bericht betrokken, gebruik dan het enkelvoudige endpoint met recipients; de gedocumenteerde bulkpayload bevat geen ontvangerslijst.

Pollen tot een eindresultaat per ontvanger

Gebruik voor elke ID GET /messages/{id}/status. Onder items staan recipient en status:

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

clawbackProcessing is tussentijds. Registreer clawbackSuccessful of clawbackFailed als terminaal resultaat per ontvanger. Het schema kan ook accepted, quarantined, deliverySuccessful of deliveryFailed geven; interpreteer die niet als clawbacksucces.

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"

Poll met een begrensd interval en jitter zolang eindresultaten ontbreken. Beperk pogingen en totale duur. Bij een time-out is het resultaat onbekend, niet mislukt: verstuur geen tweede POST voordat een latere GET of Sophos Fusion het effect heeft vastgesteld.

Deelresultaten en fouten veilig behandelen

Ongeschikt of al hersteld: controleer bericht, domein, levering en ontvanger. Herhaalde POSTs repareren geen eerder succes. Verwijder bij atomaire afwijzing pas na controle ongeschikte adressen.
Gemengde statussen: behoud clawbackSuccessful voor successen en onderzoek clawbackFailed apart. Meld niet alles als geslaagd en verwerk successen niet opnieuw.
400: controleer ID, JSON, toegestane reason en ontvangers; herhaal niet ongewijzigd.
401 of 403: vernieuw via OAuth2 of controleer rol, clawbackrecht en tenanttoewijzing. Wissel nooit als proef van tenant of regio.
404: vergelijk regionale host, gedocumenteerd pad en x-sophos-email-id met het bewijs.
Throttling (429): volg gedocumenteerde aanwijzingen en vertraag GETs met begrensde backoff en jitter. Herhaal nooit blind een POST.
Time-out of 5xx: serveracceptatie kan al hebben plaatsgevonden. Vraag eerst dezelfde ID op, begrens duur en pogingen en dien pas opnieuw in nadat het effect bekend is.

De controle is voltooid wanneer indieningsresultaat, geaccepteerde en afgewezen ontvangers en elk terminaal resultaat per ID zijn vastgelegd. Controleer aanvullend mailbox en Post-Delivery Quarantine in de juiste tenant. De API-respons blijft de machineleesbare basis; UI-clawback, automatische PDP en rapporten zijn afzonderlijke routes.