Przejdz do tresci
Avanet

Uruchamianie i weryfikacja clawback Sophos Email przez API

Sophos Email

API Clawback usuwa już dostarczone wiadomości Sophos Email z kwalifikujących się skrzynek. Bezpieczny proces ma dwie fazy: jednokrotne wysłanie zlecenia, a następnie odpytywanie GET /messages/{id}/status, aż każdy zaakceptowany odbiorca uzyska wynik końcowy. Odpowiedź 202 potwierdza przyjęcie zadania, nie powodzenie w skrzynce.

Potwierdzenie wymagań i granic

Potrzebne są skonfigurowany service principal, ważny token bearer OAuth2, UUID docelowego tenanta i wykryty regionalny host API. Wprowadzenie do Email Management API opisuje rodziny operacji i bezpieczny test odczytu. Planowany runbook Uwierzytelnianie i routing tenanta dla API Sophos Email łączy token, wybór tenanta i region.

Przykłady używają wcześniej zweryfikowanych zmiennych:

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

SOPHOS_API_HOST to host regionalny wykryty dla tenanta, nie odgadnięty. Zastąp nieszkodliwy SOPHOS_EMAIL_ID. Każde żądanie używa Authorization: Bearer *** i X-Tenant-ID; sekrety i pełne dane wiadomości nie mogą trafić do kodu, logów ani zgłoszeń.

Clawback wymaga też właściwego uprawnienia PDP/clawback i działającego połączenia z dostawcą. Naprawić można tylko wiadomości poprawnie dostarczone do kwalifikujących się skrzynek i kwalifikujących się odbiorców. Post-Delivery Protection w Sophos Fusion opisuje połączenie, On demand clawback w UI oraz Auto search and remediate. To odrębne ścieżki i nie zastępują odpytywania statusu API.

Uzyskanie właściwego x-sophos-email-id

Parametr {id} jest wartością nagłówka MIME X-Sophos-Email-ID, a nie internetowym Message-ID, tematem ani dowolnym UUID. Sophos podaje też, że wartość można uzyskać z różnych odpowiedzi zapytań Email w Live Discover w Threat Analysis Center. Nie tworzymy tu nieudokumentowanego schematu: pobierz x-sophos-email-id z wiarygodnych dowodów i zweryfikuj co najmniej tenanta, wiadomość oraz odbiorców.

Wstaw wartość do SOPHOS_EMAIL_ID bez spacji i końca wiersza. Dla wielu wiadomości zapisz każdy ID z zatwierdzeniem i sprawą; nie buduj listy tylko z podobnych tematów.

Wycofanie jednej wiadomości

Udokumentowany endpoint to POST /messages/{id}/clawback. Bez recipients Sophos podejmuje próbę dla wszystkich odbiorców. Użyj tak szerokiego zakresu tylko wtedy, gdy wszyscy należą do incydentu. W pilotażu podaj adresy; specyfikacja dopuszcza maksymalnie 500 pozycji.

Opcjonalny reason to malware, phishing, spam albo unwanted:

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

Wyślij POST dokładnie raz i zabezpiecz odpowiedź:

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"

Oczekiwany jest 202. Odpowiedź rozdziela zaakceptowane recipients od errors, każde z recipient i error. Zapisz akceptację per odbiorca bez ujawniania całości. Sophos określa pojedyncze żądanie z odbiorcami jako atomowe: jeden niekwalifikujący się odbiorca może odrzucić całość. Sprawdź przyczynę, usuń go tylko z uzasadnieniem i wyślij jedno świadome nowe żądanie.

Wycofanie wielu wiadomości

Dla wielu wiadomości Sophos dokumentuje POST /messages/clawback z listą messageIds. Każda pozycja to x-sophos-email-id:

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

Wywołanie zbiorcze zmniejsza liczbę żądań, nie kontroli. Zapisz akceptację i status każdego ID. Gdy dotyczy to tylko części odbiorców jednej wiadomości, użyj endpointu pojedynczego z recipients; udokumentowany payload zbiorczy nie zawiera odbiorców.

Polling do wyniku końcowego odbiorcy

Dla każdego ID użyj GET /messages/{id}/status. W items znajdują się recipient i status:

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

clawbackProcessing jest stanem pośrednim. Zapisz clawbackSuccessful lub clawbackFailed jako wynik końcowy odbiorcy. Schemat może też zwrócić accepted, quarantined, deliverySuccessful albo deliveryFailed; nie interpretuj ich jako sukces 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"

Odpytuj z ograniczonym interwałem i jitterem, dopóki brakuje wyników końcowych. Ogranicz próby i czas. Po timeout wynik jest nieznany, a nie nieudany: nie wysyłaj drugiego POST, dopóki późniejszy GET lub Sophos Fusion nie wyjaśni skutku pierwszego.

Bezpieczna obsługa wyników częściowych i błędów

  • Niekwalifikujący się lub już naprawiony: sprawdź wiadomość, domenę, dostarczenie i odbiorcę. Powtarzanie POST nie naprawia wcześniejszego sukcesu. Po atomowym odrzuceniu usuń adres dopiero po kontroli.
  • Mieszane statusy: zachowaj clawbackSuccessful dla sukcesów, a clawbackFailed badaj osobno. Nie zgłaszaj całości jako sukcesu ani nie przetwarzaj sukcesów ponownie.
  • 400: sprawdź ID, JSON, dozwolony reason i odbiorców; nie powtarzaj bez zmian.
  • 401 lub 403: odnów przez OAuth2 albo sprawdź rolę, uprawnienie clawback i tenanta. Nie zmieniaj testowo tenanta ani regionu.
  • 404: porównaj host regionalny, ścieżkę i x-sophos-email-id z dowodami.
  • Throttling (429): respektuj udokumentowane wskazówki i spowolnij GET przez ograniczony backoff z jitterem. Nie powtarzaj POST w ciemno.
  • Timeout lub 5xx: serwer mógł przyjąć zadanie. Najpierw sprawdź ten sam ID, ogranicz próby i czas, ponów dopiero po ustaleniu skutku.

Weryfikacja kończy się po zapisaniu dla każdego ID wyniku wysłania, zaakceptowanych i odrzuconych odbiorców oraz każdego wyniku końcowego. Dodatkowo sprawdź skrzynkę i Post-Delivery Quarantine właściwego tenanta. Odpowiedź API pozostaje podstawą maszynową; clawback UI, automatyczny PDP i raporty są oddzielne.