Automatizar com segurança a Sophos Fusion Endpoint API

A Sophos Fusion Endpoint API é a API de tenant para recursos Endpoint e de servidor. Inventaria dispositivos e, consoante o endpoint e a permissão, pode gerir análises, isolamento, grupos, Policies, exclusões, Tags e atribuições de software. A escrita afeta a proteção; para inventário basta uma identidade Read-Only.

O caminho rápido e seguro é: usar uma API Credential com a função mínima, obter um Token através do OAuth2 Client Credentials Flow, descobrir Tenant ID e host regional, testar primeiro GET /endpoint/v1/endpoints e processar todas as páginas e erros.

Limite com o Sophos Fusion Admin e outras APIs

Criar, guardar, rodar e eliminar Service Principals é uma tarefa comum do Sophos Fusion Admin. O processo completo está em Gerir as credenciais da API Sophos Fusion em segurança e não é duplicado aqui.

Listas de tenants de Partner e Organization, Alerts, Audit Events, Account Health, Cases e Live Discover também não pertencem automaticamente à Endpoint API. O Sophos Fusion (anteriormente Sophos Central) fornece APIs separadas com funções e limites próprios. Este artigo cobre apenas pedidos sob o caminho regional /endpoint/v1.

Autenticação e contexto do pedido

O artigo de referência ligado define exclusivamente o contrato do pedido e da resposta do token, whoami, listas de tenants de Partner/Enterprise, validação do host e tratamento de segredos. Reutilizar sem alteração SOPHOS_ACCESS_TOKEN, SOPHOS_TENANT_ID e SOPHOS_API_HOST. scope=token não substitui autorização: função Service Principal, acesso ao tenant, licença e permissão Endpoint continuam a aplicar-se; Partner Assistance ou Enterprise Admin Management deve permitir o tenant de destino.

Fazer um pedido de leitura inofensivo

O exemplo não inventa token nem dados de tenant. Espera três valores do processo próprio de obtenção de credenciais e identificação do tenant e do host regional e guarda a primeira página num ficheiro local:

: "${SOPHOS_ACCESS_TOKEN:?Bearer token is missing}"
: "${SOPHOS_TENANT_ID:?Tenant ID is missing}"
: "${SOPHOS_API_HOST:?Regional API host is missing}"
umask 077

curl --fail-with-body --silent --show-error --get \
  "${SOPHOS_API_HOST}/endpoint/v1/endpoints" \
  --header "X-Tenant-ID: ${SOPHOS_TENANT_ID}" \
  --data-urlencode "pageSize=50" \
  --output endpoints-page.json \
  --config - <<EOF
header = "Authorization: Bearer ${SOPHOS_ACCESS_TOKEN}"
EOF

Obtenha SOPHOS_API_HOST sem alterações de whoami ou da lista de tenants. O token deve chegar ao processo a partir de um repositório seguro de segredos, nunca do script, histórico da shell, argumentos da linha de comandos, tickets ou registos de depuração. A configuração fornecida pela entrada padrão impede que o cabeçalho Bearer expandido apareça na lista de argumentos do curl; umask 077 limita as permissões do novo ficheiro de saída. --fail-with-body torna um erro HTTP visível, mas o ficheiro continua a ser inventário potencialmente sensível.

Um estado HTTP de sucesso confirma apenas o pedido. Depois, valide o JSON, o tenant esperado e a presença dos dispositivos necessários. Não se apresenta uma resposta fictícia que possa ser confundida com um resultado observado.

Escolher conscientemente os caminhos Endpoint

O Endpoint v1 inclui, entre outros, estes caminhos:

• GET /endpoint/v1/endpoints e GET /endpoint/v1/endpoints/{endpointId} para inventário e detalhes;
• POST /endpoint/v1/endpoints/{endpointId}/scans para pedir uma análise;
• POST /endpoint/v1/endpoints/tamper-protection para alterações seletivas de Tamper Protection em até 200 dispositivos;
• POST /endpoint/v1/endpoints/reset-health para repor o estado de saúde e os alertas em até 500 dispositivos suportados;
• /endpoint/v1/endpoint-groups para grupos Computer e Server;
• /endpoint/v1/policies para Policies Endpoint, Server e Device Encryption;
• POST /endpoint/v1/tags/assignment para atribuir Tags;
• endpoints para isolamento, itens permitidos ou bloqueados, exclusões, Web Control, pacotes de software e migrações Endpoint.

Utilize o método HTTP e o caminho completo indicados acima, sem os substituir por caminhos antigos com nomes semelhantes. Antes de escrever, verifique schema, função e permissão, limites de plataforma e licença, Status Codes e Rate Limit específico da operação.

Alterar Tamper Protection e o estado de saúde de forma seletiva com pedidos em lote

As duas operações em lote complementam as chamadas Endpoint v1 existentes; não obrigam a uma migração. Ambas utilizam o host regional identificado, o token Bearer, o X-Tenant-ID do tenant de destino e Content-Type: application/json. A permissão necessária para ambas é endpoint-state:update. Uma identidade só de leitura não basta; verificar previamente se a função do Service Principal inclui esta permissão no tenant de destino.

Tamper Protection: O corpo JSON de POST /endpoint/v1/endpoints/tamper-protection contém ids com 1–200 UUID de endpoints únicos e pelo menos um dos campos booleanos enabled ou regeneratePassword. enabled: true solicita a ativação; enabled: false, a desativação. regeneratePassword: true solicita novas palavras-passe dos dispositivos. O esquema utiliza anyOf, não oneOf: permite também enviar ambos os campos em conjunto. Para garantir a rastreabilidade das alterações de manutenção, planear, ainda assim, separadamente as mudanças de estado e a regeneração das palavras-passe, enviando apenas os campos pretendidos. A regeneração de palavras-passe não é um override local de quatro horas nem uma palavra-passe comum a todos os dispositivos.

Antes de desativar a proteção: Utilizar apenas o conjunto de ID aprovado e registar, para cada dispositivo, o estado inicial, o fim da manutenção e a pessoa responsável. A desativação pela API não tem uma reativação automática após quatro horas documentada. Depois da manutenção, solicitar a ativação exatamente dos dispositivos desativados e verificar o efeito. Os métodos de manutenção locais e por dispositivo continuam muitas vezes a ser a melhor opção para dispositivos individuais.

Consultar primeiro GET /endpoint/v1/endpoints/{endpointId}?view=full e incluir apenas dispositivos com tamperProtectionSupported: true confirmado; um valor em falta não constitui autorização. O âmbito Windows/Linux da reposição do estado de saúde não confirma o suporte dessas plataformas por Tamper Protection. Verificar a opção global com GET /endpoint/v1/settings/tamper-protection: se estiver desativada, ativar dispositivos individuais não repõe a proteção. GET /endpoint/v1/endpoints/{endpointId}/tamper-protection devolve o estado pretendido enabled, mas também password e, quando aplicável, previousPasswords. Não registar esta resposta na íntegra. As palavras-passe não devem constar de tickets nem de registos de depuração; uma rotação não pode ser anulada voltando a escrever a palavra-passe antiga.

Reset Health: POST /endpoint/v1/endpoints/reset-health espera um corpo JSON com o campo obrigatório ids: 1–500 UUID de endpoints únicos. São suportados computadores Windows, servidores Windows e Linux, mas não macOS.

Antes da reposição: A operação coloca o estado de saúde a verde e elimina todos os alertas dos endpoints afetados. Guardar previamente os resultados relevantes, os detalhes dos alertas e as provas de auditoria fora da vista que será esvaziada, e obter autorização explícita para a eliminação. A reposição não elimina malware nem repara um serviço de proteção avariado. Um estado verde após esta intervenção não prova que a causa tenha sido resolvida; o contrato da operação não disponibiliza uma função de anulação para recuperar os alertas eliminados.

Depois de um pedido piloto aprovado, consultar novamente os detalhes dos dispositivos, verificar o estado de saúde e os alertas no Sophos Fusion e confirmar separadamente o funcionamento real da proteção. Investigar os novos alertas em vez de os ocultar com reposições repetidas.

Aceite não significa executado

Para ambas as operações em lote, HTTP 202 significa apenas que o pedido foi processado e a aceitação avaliada por ID. items contém os pedidos aceites com id, status: requested e requestedAt; errors contém os pedidos rejeitados com id, errorCode e errorMessage. requestedAt não é uma data de conclusão. Cruzar cada ID enviado com estes resultados; correspondências em falta ou contraditórias continuam por esclarecer, mesmo que o estado HTTP indique sucesso.

Os códigos de erro são notFound, notSupported, conflict, permissionDenied e internalError. Para os quatro primeiros, corrigir primeiro o ID/tenant, o suporte do dispositivo, o estado ou a permissão, conforme aplicável. Nem mesmo internalError autoriza o reenvio de todo o lote. Em caso de erros HTTP, analisar a resposta de erro; um 202 pode conter simultaneamente ID aceites e rejeitados.

Confirmar depois o efeito separadamente: após um contacto bem-sucedido do dispositivo, consultar os detalhes do endpoint com view=full e, para Tamper Protection, também as definições, verificando depois a proteção localmente. Avaliar lastSeenAt, tamperProtectionEnabled ou, consoante a operação, health.overall, health.threats e health.services. A simples leitura de um estado pretendido não confirma a sua aplicação num dispositivo offline. Definir um intervalo de verificação limitado e um tempo máximo global; sem confirmação, documentar a execução como pendente e investigar a conectividade do dispositivo ou os erros.

Após um timeout ou uma interrupção da ligação, um pedido de escrita pode já ter sido aceite. Não o repetir cegamente: cruzar primeiro o estado e as provas disponíveis por ID. Caso contrário, outra rotação de palavras-passe ou reposição de alertas poderá alterar estados entretanto criados. Autorizar uma nova tentativa apenas para subconjuntos cuja rejeição esteja comprovada e que seja seguro repetir após a correção; reservar os ID por esclarecer para verificação manual.

Grupos, Tags, software e Policies

Os grupos controlam atribuições de políticas e permanecem na hierarquia do tenant. As etiquetas complementam inventário e pesquisa. Uma chave de etiqueta tem 1–40 caracteres e um valor 0–40, ambos sem dois-pontos. Um endpoint permite no máximo 15 etiquetas e cada chave só pode ter um valor nesse endpoint. Um pedido aceita até 1 000 UUID e pode devolver erros parciais por Endpoint; o cliente deve, por isso, avaliar cada estado de Endpoint devolvido.

Em Device Software, Protection, Encryption e ZTNA são categorias distintas. Os computadores suportam as três; os servidores, neste fluxo, apenas Protection. Cada bloco computer ou server aceita até 1 000 IDs. Os ID de software válidos dependem do Endpoint, catálogo e licença. Use apenas IDs devolvidos por uma leitura anterior desse Endpoint exato; não aplique All, None nem IDs presumidos sem validação.

Nas políticas, guarde tipo, definições, atribuições e prioridade antes da alteração. As políticas de base e as políticas adicionais não suportam as mesmas operações. Altere apenas os campos que o objeto atual do tenant apresente como graváveis e não bloqueados. Um PATCH contém apenas chaves verificadas; um objeto completo antigo não deve substituir definições adicionadas posteriormente.

Pagination, limites e tratamento de erros

As listas de endpoints usam paginação por chave: primeira página sem pageFromKey, seguintes com pages.nextKey da resposta anterior. Outros recursos usam números de página. O máximo de pageSize varia: 50 por defeito para Endpoints e 500 no máximo para grupos de endpoints. Siga o esquema concreto e termine apenas quando não houver chave ou página seguinte.

Limites globais das Sophos Fusion APIs:

• 10 chamadas por segundo: recomendado;
• 100 por minuto: aplicado, com pequenos bursts até 300;
• 1 000 por hora: recomendado;
• 200 000 por dia: aplicado.

Um limite mais restrito da operação prevalece. A Sophos aplica os primeiros três separadamente às credenciais, à conta e ao IP de origem; a quota diária aplica-se à conta e às credenciais, não ao IP. Não use várias credenciais ou IPs para contornar limites.

Para pedidos de leitura que seja seguro repetir, tratar 429 Too Many Requests e 5xx com um número limitado de tentativas, backoff exponencial e jitter aleatório. Isto não se aplica indiscriminadamente à escrita: se a aceitação for incerta, verificar primeiro o efeito por objeto. Para 400, 401, 403, 404 e 409, corrigir primeiro o pedido, o token, a função, o ID ou o estado. Os endpoints em lote podem devolver listas de erros apesar de HTTP 200 ou 202; avaliar os sucessos e erros por objeto e reenviar apenas as partes falhadas que seja seguro repetir.

Introduzir escrita em segurança

1. Verifique tenant, host regional, paginação e filtros usando credenciais com uma função só de leitura.
2. Escolha a menor função e permissão documentadas para a operação exata.
3. Leia e guarde o estado e IDs afetados como registo da alteração.
4. Faça exatamente uma alteração num grupo-piloto ou dispositivo de teste.
5. Avalie toda a resposta da API e confirme o efeito no dispositivo ou no Central.
6. Só depois amplie; prepare a reversão, a expiração das credenciais da API, 429 e erros parciais.

Continuam a aplicar-se as regras de grupos Endpoint e inventário, ordem das Policies e Live Discover. O processo suportado para mover Endpoints já protegidos para outro tenant é descrito separadamente e não deve ser deduzido de um exemplo API genérico.

Perguntas frequentes