Automatizar com segurança a Sophos Central Endpoint API
A Sophos Central API é adequada para inventários recorrentes, alterações em massa controladas e integração com processos operacionais próprios. No entanto, não é uma segunda interface de reporting sem consequências. Consoante a função, uma aplicação pode analisar Endpoints, alterar grupos, editar Policies, atribuir software, migrar dispositivos ou iniciar Live Discover Queries.
Uma automatização segura começa, por isso, com três perguntas: qual é o Tenant afetado, qual é a permissão mínima necessária e como se pode comprovar e reverter cada alteração?
API Credentials como identidade própria
Em Global Settings > Access Control > API Credentials, um Super Admin cria um Service Principal. O nome e a descrição identificam aplicação, responsável, finalidade e data de expiração. Credenciais pessoais de administrador ou uma conta Super Admin não devem ser usadas em scripts.
A Sophos disponibiliza várias funções. Para tarefas de Endpoint, são especialmente relevantes:
| Função | Finalidade adequada | Limite importante |
|---|---|---|
| Service Principal Read-Only | inventário, estado e reporting | sem alterações nem Live Discover Queries |
| Service Principal Management | dispositivos, utilizadores, Policies e gestão da proteção | sem Forensics Queries |
| Service Principal Forensics | Live Discover | sem gestão geral de Endpoint |
| Service Principal Active Directory Sync | sincronização de AD | exclusivamente sincronização de diretório |
| Service Principal Super Admin | casos especiais que exigem expressamente acesso total | maior dano possível em caso de abuso |
O Client Secret só é apresentado uma vez e é imediatamente guardado num Secret Store. A Sophos não envia um aviso antes da expiração de uma API Credential. Depois de expirar, a entrada é removida automaticamente e a aplicação só volta a autenticar-se com novas credenciais. A monitorização da expiração e a rotação têm, portanto, de ocorrer fora do Central.
Os Legacy API Tokens da SIEM Integration API estão a ser substituídos. Os Tokens existentes só funcionam até expirarem; novas integrações utilizam API Credentials.
Autenticação e API Host correto
A Sophos utiliza OAuth2 com Client Credentials Flow. A aplicação envia Client ID e Client Secret para o Sophos ID Endpoint e recebe um Bearer Token temporário. O Token, o Secret e os Request Headers completos não são registados em tickets nem em Logs desprotegidos.
Após a autenticação, consulta-se primeiro a interface global Who Am I. A resposta fornece o Tenant ID e o API Host da Data Region. Só depois a aplicação chama um Endpoint regional como api-eu01.central.sophos.com ou api-eu02.central.sophos.com. Além do Bearer Token, o Regional Request requer o Header X-Tenant-ID.
Para um controlo manual, o Central também mostra a região em Profile > Support settings. Em alternativa, esta pode ser reconhecida no hostname de um link de download do installer. As automatizações continuam a utilizar Who Am I, porque uma região lida na interface não constitui um mecanismo multi-tenant fiável.
Importante: a região não é deduzida da localização da empresa nem do idioma. Um Host fixo no script pode estar errado para o Tenant seguinte. Who Am I ou a Tenant List é a fonte vinculativa.
As automatizações Partner e Enterprise trabalham com vários Tenants. Primeiro determinam o Partner ID ou Organization ID, leem todos os Tenants, incluindo a Data Region, e depois executam o Request para cada Tenant com o respetivo Regional Host e Tenant ID.
O que abrangem as Endpoint APIs
As interfaces oficiais incluem, entre outras funções:
- inventariar dispositivos e iniciar ações como um Scan;
- criar e alterar Endpoint Groups e atribuir dispositivos;
- criar, clonar e priorizar Policies adicionais e alterar definições;
- atribuir Protection, Device Encryption ou ZTNA como Device Software;
- consultar pacotes Recommended, Fixed, LTS e Support disponíveis;
- organizar dispositivos com Key-Value Tags;
- controlar migrações de Endpoint entre Tenants;
- ler resultados de Account Health e iniciar correções suportadas;
- avaliar Audit Events, Alerts, XDR Cases e Detections;
- iniciar Live Discover Queries guardadas ou próprias.
Nem todas as licenças e funções permitem todas as operações. Antes de uma automatização com escrita, um pedido Read-Only confirma se Tenant, Object IDs, licença e estado atual esperado correspondem.
Algumas APIs têm limites mais restritos do que o nome sugere. A Cases API só pode atualmente criar e alterar cases self-managed. A Sophos indica ainda um limite flexível de 100 requests por tenant em 24 horas e 10 requests por utilizador por minuto. Ao consultar as case detections, uma page size superior a 50 devolve 400 Bad Request. A Endpoint Software API só pode listar packages para computadores e servidores Windows e exige atualmente a função Service Principal Super Admin. Estes pré-requisitos específicos da API são verificados na respetiva reference antes da implementação e não deduzidos das funções ou limites gerais.
Grupos, Tags e atribuição de software
Os grupos continuam a ser o meio para atribuir Policies. As Tags complementam-nos para inventário, pesquisa e workflows externos. Uma Tag é composta por uma Key e um Value opcional. Key e Value podem ter, no máximo, 40 caracteres e não podem conter dois pontos. Cada Endpoint admite, no máximo, 15 Tags e a mesma Key só pode ter um Value por dispositivo.
Um Tag Request ou Software Request pode conter até 1'000 Endpoint UUIDs. Numa Bulk Operation, uma resposta HTTP 200 não significa necessariamente que todos os objetos foram alterados. Por isso, a aplicação também avalia Partial Errors por dispositivo e não repete cegamente toda a operação.
Na Device Software API, Protection, Encryption e ZTNA são categorias separadas. All atribui apenas a variante licenciada mais elevada dentro da categoria indicada e None remove apenas essa categoria. Os Software IDs disponíveis são consultados no Endpoint concreto; são case-sensitive e dependem da licença e do Device Catalog.
Não tratar Policies como ficheiros de texto
A Endpoint Policy API consegue ler Base Policies e Policies adicionais. As Policies adicionais podem ser criadas, clonadas, atualizadas e eliminadas. Na Base Policy só se podem alterar as definições, não o nome, a prioridade nem o estado de ativação.
Antes de uma atualização, guardam-se Policy Type, prioridade atual, atribuições e definições existentes. Um PATCH contém apenas as Keys alteradas intencionalmente. Uma automatização não deve substituir definições desconhecidas ou recentemente adicionadas pela Sophos através de um objeto completo antigo.
Os Policy Requests com escrita têm Rate Limits adicionais por Tenant. Uma sintaxe válida também não prova que a alteração é operacionalmente aceitável. Tal como na GUI, são necessários Pilot Group, Change Window, Audit Log e Rollback.
Pagination, Rate Limits e repetições
As listas têm de ser lidas integralmente em todas as páginas. Consoante a interface, as Sophos APIs usam Pagination baseada em Offset ou Key. Um script que só processa a primeira página pode apresentar um inventário incompleto como completo.
Para a utilização da API, a Sophos indica como valores de referência ou limites 10 Requests por segundo, 100 por minuto, 1'000 por hora e 200'000 por dia. APIs individuais podem ter limites mais restritos. Perante 429 Too Many Requests e erros 5xx temporários, repete-se com Exponential Backoff e Jitter aleatório. Em erros de autenticação, autorização ou validação, uma repetição infinita sem alterações é incorreta.
Cada execução regista, pelo menos, Tenant ID, operação, número de objetos, IDs concluídos e falhados, hora do Request e uma Correlation ID própria. Secrets, Bearer Tokens e conteúdo sensível das respostas são removidos dos Logs.
Introdução segura
Uma nova automatização começa num Test Tenant ou numa pequena Pilot Group. Primeiro, o mesmo workflow é executado apenas em modo de leitura e produz um plano verificável. Depois realiza-se exatamente uma alteração controlada, que é confirmada pela API e no Central, no dispositivo, na Effective Policy e no Audit Log.
O âmbito só é ampliado depois de testar Partial Errors, Pagination, Rate Limits, expiração das credenciais e Rollback. Em projetos únicos, as API Credentials são eliminadas no final; integrações permanentes recebem Owner, Rotation, Monitoring e um processo de desativação documentado.
Artigos relacionados
A migração de Endpoint entre Central Tenants utiliza um Receiving Workflow e Sending Workflow próprios. Para grupos Endpoint e inventário de dispositivos, ordem das Policies e Live Discover, aplicam-se as mesmas regras técnicas, quer a alteração seja feita pela GUI ou pela API.