Gerir API Credentials do Sophos Central com segurança
O Sophos Central pode ser automatizado através de APIs e ligado a plataformas de SIEM, RMM, reporting ou seguros. Para esse efeito, não se utilizam contas pessoais de administrador, mas API Credentials próprias, compostas por Client ID e Client Secret.
Estas credenciais são identidades de máquinas. Quem possuir um secret pode executar todas as ações de API permitidas pela função Service Principal atribuída. Por isso, um secret deve ser tratado como uma palavra-passe privilegiada e nunca pode ficar guardado em scripts, tickets, e-mails ou repositórios Git.
Distinguir API Credentials do Integration Credential Manager
Em Global Settings > Access Control existem duas áreas com nomes semelhantes:
| Área | Função |
|---|---|
| API Credentials | Identidade técnica com a qual uma aplicação acede às APIs do Sophos Central |
| Integration Credential Manager | Credenciais de produtos de terceiros que a Sophos utiliza para integrações como Data Ingestion ou Response Actions |
Para um script próprio, uma consulta SIEM ou um cliente de API, criam-se API Credentials. As credenciais de um produto de terceiros que o próprio Sophos Central deve utilizar pertencem, pelo contrário, ao Integration Credential Manager.
Pré-requisitos e responsabilidade
Apenas um Super Admin pode criar e gerir API Credentials. Posteriormente, a aplicação autentica-se de forma independente deste administrador pessoal. Se o administrador for desativado, a identidade técnica mantém-se até expirar ou ser eliminada.
Antes da criação, documentam-se a finalidade, o responsável, o sistema de destino, a função necessária, a data de expiração e o contacto de emergência. Utiliza-se uma Credential própria para cada aplicação e ambiente. Um secret comum para um script de backup, o SIEM e prestadores externos impede um bloqueio seletivo e dificulta a análise da causa.
Escolher a função Service Principal adequada
A Sophos disponibiliza várias funções:
- Service Principal Read-Only lê dados do tenant, mas não os pode alterar nem executar consultas Live Discover.
- Service Principal Management pode consultar, criar, alterar e eliminar utilizadores e grupos de utilizadores, consultar e processar Alerts, consultar Endpoints e iniciar ações como um scan, bem como consultar e alterar definições globais de Endpoint Protection. Além disso, a função gere administradores, funções e Security Policies, mas não tem acesso a consultas Live Discover.
- Service Principal Forensics cria, inicia e elimina consultas Live Discover.
- Service Principal Active Directory Sync destina-se exclusivamente à sincronização do AD e não pode executar outras tarefas de API.
- Service Principal Firewall limita a identidade à gestão de Firewalls e não permite tarefas de API do Central fora desse âmbito.
- Service Principal Super Admin possui direitos abrangentes de leitura, escrita e eliminação, bem como acesso a consultas.
A seleção começa sempre pela função mais limitada. Uma integração de reporting ou de seguros cibernéticos recebe Read-Only. O AD Sync recebe a função prevista especificamente para esse efeito. Super Admin só é utilizado quando os endpoints de API documentados exigem efetivamente direitos de escrita abrangentes e nenhuma função mais limitada funciona.
Criar a Credential
O caminho é Global Settings > Access Control > API Credentials. No primeiro acesso, é necessário aceitar os termos de utilização.
- Abrir Add Credential.
- Introduzir um nome inequívoco e uma descrição com a aplicação, o ambiente e o responsável.
- Selecionar a função Service Principal mínima necessária.
- Criar a Credential e copiar imediatamente o Client ID e o Client Secret.
- Guardar o secret num Secret Store empresarial e limpar a área de transferência temporária.
O Client Secret só é apresentado uma vez. Não pode voltar a ser mostrado posteriormente. Se for perdido, não se recupera o secret existente; cria-se uma nova Credential e elimina-se a antiga depois de a transição ter sido concluída com êxito.
Testar a autenticação de forma controlada
O primeiro teste não consiste numa ação de escrita em produção. Primeiro, obtém-se um OAuth Access Token através do endpoint Sophos Identity. Em seguida, o endpoint whoami devolve o Tenant ID, o API Host e o tipo de dados da conta. Só depois se executa uma chamada de leitura inofensiva ao API Host fornecido para o tenant.
O API Host não é copiado de um exemplo. A Sophos opera várias regiões de dados, pelo que se deve utilizar o URL fornecido por whoami. O Tenant ID e o Organization ID também não são intercambiáveis.
Para o teste, documentam-se pelo menos os seguintes casos:
- A autenticação com a nova identidade funciona.
- É devolvido o tenant esperado.
- As operações de leitura autorizadas funcionam.
- Uma operação não autorizada é rejeitada com
403 Forbidden. - Os Audit Logs ou os registos da integração mostram o teste de forma rastreável.
Gerir a expiração e a rotação
A Sophos não envia qualquer aviso quando uma API Credential expira. Depois de expirar, já não pode ser utilizada para autenticação e é removida automaticamente do Central. Por isso, a monitorização tem de ser feita fora do Central.
Um processo de rotação correto utiliza uma sobreposição curta:
- Criar uma nova Credential com uma função idêntica ou mais limitada.
- Alterar a aplicação para o Client ID e o secret da nova Credential.
- Testar a autenticação e a função operacional.
- Eliminar a Credential antiga.
- Verificar a alteração no Audit Log, no registo de secrets e na documentação operacional.
A Credential antiga não permanece ativa durante meses por precaução. Se uma aplicação suportar apenas um conjunto de secrets, planeia-se uma janela de manutenção.
Substituir antigos SIEM API Tokens
API Token Management é o método de autenticação anterior para a SIEM Integration API. A Sophos já não emite novos tokens nessa área nem prolonga a validade dos existentes. Os tokens existentes só funcionam até à respetiva expiração.
Uma integração que ainda os utilize não deve ser mantida até ao último dia. Inventariam-se o token, o sistema de destino, a data de expiração e os endpoints utilizados, cria-se uma API Credential adequada, altera-se a aplicação e verifica-se o fluxo de dados completo. O token antigo só é removido depois de uma verificação paralela bem-sucedida.
A mudança de um Legacy Token para API Credentials não é uma simples alteração de nome. A integração tem de suportar a autenticação OAuth, whoami, o Regional Host e o modelo de funções. Por isso, um SIEM Connector é configurado com base nas instruções atuais do fabricante e não através de um exemplo antigo de token.
Prestadores externos e acesso de terceiros
Para uma entidade externa, cria-se uma identidade Service Principal Read-Only própria, desde que bastem direitos de leitura. O Client ID e o secret são transmitidos através de um canal separado e cifrado. Define-se uma data final para o acesso, que é eliminado no fim do projeto.
Através da API, este acesso de terceiros pode ler, em particular, Alerts e Events, resultados do Account Health Check, detalhes de dispositivos e configurações de Policy. Read-Only impede a adição, alteração e eliminação no Central, mas não limita automaticamente os dados legíveis que a plataforma de terceiros consulta ou armazena efetivamente. Antes da autorização, clarificam-se contratualmente o âmbito dos dados, a finalidade da utilização, o local de armazenamento, a retenção e a eliminação.
A criação segue o caminho normal Global Settings > Access Control > API Credentials > Add Credential. No primeiro acesso, confirmam-se os termos de utilização e de proteção de dados, seleciona-se a função Service Principal Read-Only e copiam-se imediatamente e de forma segura o Client ID e o Client Secret, que só é apresentado uma vez. A transmissão é feita através de um canal cifrado aprovado, por exemplo o portal HTTPS do fornecedor, e não por e-mail ou no texto de um ticket.
O API Host não é copiado de uma tabela regional estática. A aplicação utiliza whoami para determinar o API Host válido para esse tenant específico. Desta forma, a integração continua corretamente documentada mesmo que a Sophos altere regiões ou endpoints. Assim que o fornecedor deixar de necessitar do acesso, a Credential é eliminada, revogando imediatamente a autorização de API.
Não é aceitável exportar a conta pessoal de Super Admin, utilizar uma identidade de API comum para vários clientes ou colocar um secret num ticket de suporte. O prestador também tem de indicar onde o secret é guardado, como é protegido e quando é eliminado.
Isolar erros de forma direcionada
401 Unauthorized
Na maioria dos casos, o Client ID, o secret, o Token Endpoint ou o OAuth Request estão incorretos. Uma Credential expirada e já removida também provoca este erro. Primeiro, verifica-se se a Credential ainda existe no Central e se a aplicação utiliza realmente o conjunto de secrets mais recente.
403 Forbidden
A autenticação foi bem-sucedida, mas a função não permite a ação. Em vez de atribuir imediatamente Super Admin, associa-se o endpoint de API necessário à função Service Principal adequada.
Token correto, região de dados errada
O Access Token, por si só, não determina o API Host funcional. A aplicação tem de utilizar o Regional Host fornecido por whoami. Um Host fixo de outra região provoca erros ou consultas no limite errado da plataforma.
A integração falha sem aviso
Se o Central não mostrar um Alert aberto, verificam-se a data de expiração, a última chamada de API bem-sucedida e a versão do secret no sistema de destino. A monitorização da expiração pertence à monitorização externa.
Revisão regular
Pelo menos trimestralmente, verificam-se o nome, o responsável, a função, a última utilização, a expiração e o sistema de destino de cada Credential. As identidades não atribuíveis ou não utilizadas são eliminadas. Se houver suspeita de fuga de um secret, a Credential é imediatamente bloqueada, substituída por uma nova e o Audit Log é analisado à procura de ações anómalas.
Os direitos pessoais de administrador são verificados separadamente de acordo com Atribuir corretamente funções administrativas no Sophos Central. As API Credentials não substituem o MFA nem um acesso pessoal e rastreável de administrador.