Executar e verificar clawback do Sophos Email pela API

A API Clawback remove mensagens Sophos Email já entregues de caixas elegíveis. O fluxo seguro tem duas fases: enviar o clawback uma única vez e consultar GET /messages/{id}/status até cada destinatário aceite ter um resultado terminal. Uma resposta 202 confirma a aceitação do trabalho, não o sucesso na caixa.

Confirmar pré-requisitos e limites

São necessários um service principal configurado, um bearer token OAuth2 válido, o UUID do tenant alvo e o respetivo host regional descoberto. A introdução à Email Management API explica famílias de operações e o teste de leitura seguro. O runbook planeado Autenticação e encaminhamento de tenant para a API Sophos Email reúne token, resolução do tenant e região.

Os exemplos usam variáveis já validadas:

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

SOPHOS_API_HOST é o host regional descoberto, não inferido. Substitua o exemplo inofensivo SOPHOS_EMAIL_ID. Cada pedido usa Authorization: Bearer *** e X-Tenant-ID; segredos e dados completos de mensagens não devem entrar em código, logs ou tickets.

O clawback também exige o direito PDP/clawback e uma ligação funcional ao fornecedor. Só mensagens entregues com êxito a caixas elegíveis, e destinatários elegíveis, podem ser remediados. Post-Delivery Protection no Sophos Fusion cobre a ligação, On demand clawback na interface e Auto search and remediate. Estes fluxos são distintos da API e não substituem o polling do estado.

Obter o x-sophos-email-id correto

O parâmetro {id} é o valor do cabeçalho MIME X-Sophos-Email-ID, não o Message-ID da Internet, o assunto ou um UUID arbitrário. A Sophos indica ainda que pode ser obtido de diferentes respostas de consultas Email no Live Discover do Threat Analysis Center. Este runbook não inventa um esquema: recolha x-sophos-email-id de evidência fiável e confirme, no mínimo, tenant, mensagem e destinatários afetados.

Defina SOPHOS_EMAIL_ID sem espaços nem quebras de linha. Para várias mensagens, registe cada ID com aprovação e caso; não crie uma lista apenas por assuntos semelhantes.

Recolher uma mensagem

O endpoint documentado é POST /messages/{id}/clawback. Sem recipients, a Sophos tenta todos os destinatários. Use esse âmbito apenas quando todos pertencerem ao incidente. Num piloto, indique os endereços; a especificação permite até 500 entradas.

O reason opcional é malware, phishing, spam ou unwanted:

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

Envie o POST exatamente uma vez e proteja a resposta:

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"

Espera-se 202. A resposta separa recipients aceites de errors, cada um com recipient e error. Registe a aceitação por destinatário sem expor a resposta completa. A Sophos descreve a chamada individual limitada a destinatários como atómica: um destinatário não elegível pode fazer falhar todo o pedido. Verifique a causa, remova-o apenas com justificação e envie então um novo pedido deliberado.

Recolher várias mensagens

Para várias mensagens, a Sophos documenta POST /messages/clawback com uma lista messageIds. Cada item é um x-sophos-email-id:

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

A chamada múltipla reduz pedidos, não verificações. Registe a aceitação e o estado de cada ID. Se apenas alguns destinatários de uma mensagem forem afetados, use o endpoint individual com recipients; o payload múltiplo documentado não inclui destinatários.

Consultar até ao resultado terminal por destinatário

Para cada ID, use GET /messages/{id}/status. Em items surgem recipient e status:

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

clawbackProcessing é intermédio. Registe clawbackSuccessful ou clawbackFailed como resultado terminal de cada destinatário. O esquema também pode devolver accepted, quarantined, deliverySuccessful ou deliveryFailed; não os interprete como sucesso do 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"

Consulte com intervalo limitado e jitter enquanto faltarem resultados terminais. Limite tentativas e duração total. Num timeout, o resultado é desconhecido, não falhado: não envie outro POST até um GET posterior ou o Sophos Fusion esclarecer o efeito do primeiro.

Tratar resultados parciais e erros em segurança

Não elegível ou já remediado: verifique mensagem, domínio, entrega e destinatário. Repetir POST não corrige um sucesso anterior. Após rejeição atómica, retire endereços não elegíveis apenas depois da verificação.
Estados mistos: preserve clawbackSuccessful para sucessos e investigue clawbackFailed separadamente. Não marque todo o trabalho como bem-sucedido nem reprocesse sucessos.
400: verifique ID, JSON, reason permitido e destinatários; não repita sem alterações.
401 ou 403: renove por OAuth2 ou verifique função, permissão clawback e tenant. Nunca troque tenant ou região como experiência.
404: compare host regional, caminho documentado e x-sophos-email-id com a evidência.
Throttling (429): respeite indicações documentadas e abrande os GET com backoff limitado e jitter. Nunca repita um POST às cegas.
Timeout ou 5xx: o servidor pode ter aceite. Consulte primeiro o mesmo ID, limite tentativas e duração e só reenvie depois de conhecer o efeito.

A validação termina quando ficam registados o resultado do envio, destinatários aceites e rejeitados e cada resultado terminal de cada ID. Como controlo adicional, verifique a caixa e a Post-Delivery Quarantine no tenant correto. A resposta API continua a ser a base legível pela máquina; clawback na UI, PDP automático e relatórios são vias separadas.