REST API do Sophos Firewall: acesso seguro e ciclo de vida das chaves

A REST API local do SFOS 23.0 permite ler e alterar a configuração diretamente no firewall. Começar com um administrador dedicado com permissões limitadas, autorizar apenas o host de automação, gerar a chave com essa conta e validar primeiro uma leitura. A existência de documentação não confirma uma data GA nem suporte em firmware anterior.

Três interfaces, três identidades

REST API local: a chave de um administrador do firewall funciona como token Bearer; as permissões vêm do perfil administrativo.
XML API local: payloads XML e credenciais administrativas, normalmente por HTTP POST para APIController. XML <Get> não é um pedido REST.
API de configuração do Sophos Central: service principal cloud, token temporário, tenant e host API regional. Uma chave local não substitui estas credenciais.

Preparar o acesso e o administrador

Em Profiles > Device access, criar um perfil apenas com os direitos necessários; inventário requer permissões de leitura adequadas. Em Authentication > Users, criar um administrador dedicado com esse perfil. O planeamento de administradores e perfis explica os papéis. Não usar conta pessoal ou o admin predefinido com privilégios totais nos processos.
Em Hosts and services > IP host, definir o host real, por exemplo api-inventory com 192.0.2.20. Substituir nome e endereço de documentação. Uma origem fixa é mais restrita do que toda a rede de gestão; com NAT conta a origem vista pelo firewall.
Em Administration > API access, ativar API access, desativado por predefinição, selecionar apenas as origens necessárias em Allowed IP hosts e clicar em Apply. São possíveis endereços, intervalos e redes, até 64 entradas. Rever origens apiconfig migradas ao atualizar para SFOS 22.0 ou posterior.
Em Administration > Device access, verificar WebAdmin a partir da zona relevante. Device Access e a lista API são controlos distintos; não abrir amplamente o acesso WAN.

Gerar e guardar a chave uma única vez

Iniciar sessão como administrador dedicado. Em Administration > API access > REST API keys, clicar em Add API key, introduzir um nome descritivo como inventory-prod-2026-10 e gerar com Add API key.

Antes de Close: copiar a chave para o armazenamento de segredos protegido do processo. Depois de fechar a janela, nunca voltará a ser mostrada. Não incluir em capturas, tickets, ficheiros do repositório ou exportações de coleções sem proteção.

A chave é válida por um ano e herda os direitos do criador. Os administradores criam e eliminam as próprias chaves; todos veem a lista, mas não recuperam o segredo. O admin predefinido também pode eliminar chaves alheias. Limites: 10 chaves por administrador, 1024 no total. Não partilhar chaves entre administradores.

Construir o pedido a partir do esquema do firewall

Em REST API help, descarregar OpenAPI.yaml deste firewall e importar no Postman ou Swagger. Em REST API guide, verificar URL base, autenticação, referências de objetos e esquema do endpoint escolhido. Os nomes assemelham-se à interface, mas nem sempre coincidem.

A referência indica esta base e este cabeçalho; obter caminho, método e parâmetros do pedido no esquema correspondente:

https://<firewall-host>:<port>/firewall-config/v1
Authorization: Bearer <API_KEY>

Substituir hostname e porta HTTPS administrativa; inserir a chave pela função de segredos do cliente. Validar certificado TLS e hostname, sem contornar com -k. A introdução também contém exemplos com o caminho XML APIController; não os copiar sem verificação como instruções REST. Sem endpoint correspondente no esquema do firewall, não inventar caminhos.

Teste de leitura e controlo operacional

Enviar uma leitura inofensiva conforme ao esquema a partir do host real. Verificar resposta e dados esperados, não apenas sucesso HTTP. Repetir a partir de uma origem controlada não autorizada: não deve devolver configuração. Não remover autorizações de produção para preparar o teste.

Antes de escrever, preparar backup e recuperação, testar uma pequena alteração aprovada e verificar o objeto no WebAdmin e no Audit Trail. Após timeout de escrita, ler o estado real antes de repetir. Consultas lentas, como assinaturas IPS, podem exigir timeouts maiores.

Validade, substituição e eliminação

Documentar conta, processo, origem autorizada, criação, expiração e equipa responsável, nunca a chave. Programar lembretes e substituição antes da expiração; não assumir renovação automática. Reservar um espaço livre para rotação com sobreposição. Com 10 chaves próprias ou 1024 no total, identificar primeiro as desnecessárias com o responsável, sem revogar processos ativos indiscriminadamente.

Para substituição planeada, gerar e guardar outra chave com a mesma conta, atualizar o processo e validar uma leitura. Só depois eliminar a chave antiga própria e verificar que a nova funciona e a antiga já não concede acesso. Não considerar recuperáveis as chaves eliminadas. Substituir também uma chave cuja visualização única foi perdida. Perante suspeita de exposição, revogar imediatamente, mesmo com interrupção. Para chaves alheias, envolver o responsável pelo admin predefinido. Ao desativar uma integração, eliminar chaves e origens inúteis, verificando primeiro as partilhadas.

Limites do SFOS 23.0

O âmbito atual exclui desta REST API:

Web: Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
Todas as funções Email, Wireless e RED.
Network: DDNS e IP tunnels; SD-WAN profiles.
VPN: IPsec routes, GRE routes, L2TP, PPTP, clientes e servidores SSL VPN site-to-site.
Authentication: Guest users e clientless users; Firewall rule groups.
Let’s Encrypt certificates; High availability e TAP mode; System time.
Informação de estado, como leases DHCP, estado HA e armazenamento de dados.

A lista não é exaustiva nem promete uma versão futura. Verificar cada operação no esquema atual; um menu visível não prova suporte API. XML ou cloud não são substitutos automaticamente equivalentes.

Quando o processo falha

Para ligação, verificar origem após NAT, routing, porta administrativa, TLS, acesso API e Device Access. Para autenticação ou permissões, verificar chave, expiração, eliminação, criador e perfil em vez de conceder direitos totais. Para erros de esquema, comparar método, caminho, campos obrigatórios e referências dependentes. Uma chave perdida resolve-se por substituição, não por nova visualização.

Para escalamento, guardar firmware, versão do esquema, hora, endpoint, estado HTTP e resposta sanitizada, sem segredos. Sophos suporta a REST API oficial e scripts inalterados, não aconselhamento ou troubleshooting de integrações personalizadas. Estas precisam de um responsável interno; envolver um parceiro ou Sophos Professional Services quando necessário.