Proteger o acesso à API XML do Sophos Firewall

A API XML do Sophos Firewall é útil para automação, monitorização, backups, análises e integrações. Por isso, também faz parte da superfície de ataque de gestão. Permitir acesso à API dá a um sistema a capacidade de ler dados de configuração ou, dependendo das permissões, fazer alterações.

O acesso à API não deve ser amplamente permitido a partir de redes internas ou de fontes aleatórias. É melhor ter um conjunto pequeno e documentado de redes de gestão, hosts de automação ou acessos de parceiros fixos.

Desde o SFOS 22, a Sophos expandiu o controle de acesso à API. As configurações de acesso à API estão na seção Administration > API access, e as fontes permitidas podem ser definidas como IP Hosts. Isso permite modelar não apenas endereços IP individuais, mas também intervalos de IP e redes de forma eficaz.

Nas versões anteriores do SFOS, a configuração da API encontrava-se em Backup and firmware > API. Esta alteração do caminho de menu deve ser considerada ao comparar instruções antigas.

Quando o acesso à API XML é útil

A API XML não é um acesso padrão para o trabalho administrativo normal. É útil quando há um processo técnico específico por trás.

Casos de uso típicos:

Monitorização ou inventário.
Verificações de configuração automatizadas.
Processos de backup ou documentação.
Plataformas MSP ou de integração.
Scripts para tarefas administrativas recorrentes.
Alterações preparadas a partir de ferramentas como o Sophos Firewall Config Studio.

Se um processo pode funcionar sem a API, o acesso à API não deve permanecer ativado por precaução. Cada interface adicional precisa de um responsável, uma fonte, um conceito de acesso e um controle.

O que mudou com o SFOS 22

Com o SFOS 22, o controle de acesso à API XML tornou-se significativamente mais gerenciável:

As configurações de acesso à API foram movidas para o menu Administration > API access.
O acesso à API está desativado por predefinição e deve ser ativado conscientemente.
O acesso à API pode ser restrito a IP Hosts.
Como fontes, são possíveis endereços IP, intervalos de IP e redes.
Até 64 IP Hosts podem ser permitidos.
Durante a atualização, os endereços IP permitidos anteriormente são automaticamente convertidos em objetos IP Host.
Objetos migrados recebem o prefixo apiconfig.

Isso é útil para a operação, pois as fontes da API não precisam mais ser mantidas como endereços individuais soltos. Pode-se nomear de forma clara uma rede de gestão, um host de automação ou um grupo de hosts dedicado e reconhecê-los em revisões posteriores.

Regra básica: permitir API apenas de fontes definidas

API access deve ser tratado como WebAdmin ou SSH: tão restrito quanto possível e tão amplo quanto necessário.

Fontes adequadas são, por exemplo:

um servidor de automação dedicado,
um sistema de monitorização,
um host de gestão de configuração,
uma rede interna de gestão,
uma rede VPN ou de administração,
um endereço de origem de parceiro ou MSP claramente definido.

Não são adequados:

redes de clientes completas,
redes guest ou IoT,
Any,
permissões vagas como “rede de servidores completa”,
endereços IP temporários de teste que depois ficam esquecidos.

Se prestadores externos precisarem de acesso API, a fonte deve ser definida da forma mais específica possível. Também deve ficar documentado para que serve o acesso e quando será removido.

Procedimento recomendado

O caminho exato na interface pode variar ligeiramente conforme a versão do SFOS. No SFOS 22, a configuração da API fica em Administration > API access.

Procedimento prático:

Verificar que sistema precisa de acesso API.
Em Hosts and services > IP host, criar um objeto IP Host claro para esse sistema.
Se forem necessárias várias fontes, nomear corretamente IP Hosts, IP ranges ou redes.
Em Administration > API access, ativar API access.
Em Allowed IP hosts, permitir apenas estes objetos.
Clicar em Apply.
Não inserir redes amplas de clientes ou servidores.
Testar o acesso a partir do verdadeiro host de automação ou monitorização, não do portátil do administrador.
Remover fontes que já não sejam necessárias.
Documentar a alteração no processo de change.

Em instalações existentes após uma atualização para SFOS 22, também se deve procurar objetos com o prefixo apiconfig. Estes objetos foram criados a partir de entradas API allow antigas e devem ser verificados, renomeados ou limpos.

Testar o acesso de forma direcionada

O endpoint da API normalmente encontra-se em:

https://<IP-ou-hostname-da-firewall>:<Port>/webconsole/APIController

A porta é a porta HTTPS da WebAdmin Console. Se a porta de administração foi alterada em Administration > Admin settings, a ferramenta API deve usar a mesma porta. A API trabalha com payloads XML via HTTP POST, não como uma API REST clássica com endpoints GET, POST, PUT e DELETE separados.

Um teste útil não responde apenas se o login é possível. Deve mostrar se a fonte correta é permitida, se a conta pode executar a operação necessária e se o resultado permanece rastreável no processo de auditoria ou change.

Para aceitação, verificar estes pontos separadamente:

Fonte: O teste corre a partir do verdadeiro host de automação, monitorização ou integração, não do portátil do administrador.
Acesso: A firewall aceita o IP de origem apenas se o objeto IP Host correspondente estiver permitido em API access.
Conta: A conta API ou de serviço utilizada tem apenas os direitos necessários.
Segredo: Nome de utilizador, palavra-passe ou token não acabam no histórico da shell, tickets, chats ou screenshots.
Auditoria: O acesso ou a alteração é rastreável no processo de auditoria ou change.
Rollback: Antes de operações de escrita existem backup, ponto de rollback e um teste de leitura inofensivo.

Exemplos curl com nome de utilizador e palavra-passe no URL são rapidamente copiados e depois difíceis de remover dos logs. É melhor fazer um teste curto com uma conta de serviço dedicada, segredo temporário de teste, armazenamento seguro e rotação posterior se um segredo foi usado num contexto inseguro.

Para testes estruturados, uma coleção Postman é muitas vezes mais limpa do que um comando shell copiado à pressa. Também aí, endereço da firewall, porta, nome de utilizador, palavra-passe e valores de objetos devem ser mantidos como variáveis ou segredos, não fixos em requests, screenshots ou tickets. A coleção não é um conceito de segurança, mas ajuda a testar operações de leitura e escrita de forma mais reprodutível.

Uma API acessível ainda não prova que a alteração planeada é tecnicamente segura. Antes de operações de escrita em produção, deve funcionar primeiro uma consulta de leitura inofensiva e depois uma pequena alteração controlada.

Construir e avaliar conscientemente os pedidos XML

A XML API utiliza sempre HTTP POST para o mesmo APIController nas consultas e alterações de configuração. A ação de ler, criar, atualizar ou eliminar é definida no payload XML, não no método HTTP. A estrutura exterior é composta por <Request>, <Login> e exatamente a operação necessária:

<Set operation="add"> cria objetos, regras ou políticas suportados.
<Set operation="update"> altera definições que não podem ser criadas como novos objetos.
<Get> lê configurações ou dados de estado.
<Remove> elimina objetos suportados. Definições fixas, como a configuração de SSL/TLS Inspection, não podem ser eliminadas, apenas atualizadas.
<Filter> limita uma consulta de leitura. Os critérios gerais são =, != e like; algumas consultas estatísticas suportam critérios adicionais.

Se operation for omitido em <Set>, o SFOS trata o pedido como add. Não é um valor predefinido inofensivo: um pedido pensado como atualização pode falhar ou atuar sobre o objeto errado. Um transactionid alfanumérico opcional facilita a correlação entre o pedido e a resposta.

Uma pequena consulta de leitura tem esta estrutura:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHost></IPHost>
  </Get>
</Request>

api-reader e SECRET são marcadores de posição. O segredo real deve ficar no secret store protegido da ferramenta, não num ficheiro XML no repositório. O teste só é bem-sucedido quando a resposta contém o resultado esperado em <Response> e um estado adequado em <Status>. Um sucesso HTTP ou Send successful no Postman não prova, por si só, que o SFOS executou a operação pretendida. Em operações de escrita, verificar também o objeto de destino no WebAdmin e a alteração no Audit Trail.

Utilizar com segurança a coleção oficial do Postman

A Sophos fornece uma coleção preparada em https://docs.sophos.com/nsg/sophos-firewall/api-collections/sophosfirewall.postman_collection.json. Depois da importação, adaptar username, password, firewall-ip e firewall-port nas Collection Variables ao ambiente. Os valores de objetos incluídos são exemplos e não devem ser enviados sem verificação.

Para um pedido próprio, utilizar o método POST, o endpoint indicado acima e a chave reqxml em Body > form-data. Testar primeiro Authenticate > Sign in e depois uma consulta <Get> inofensiva. Só quando origem, conta, resposta e auditoria estiverem corretas deve seguir-se uma pequena operação de escrita com rollback preparado.

Uma coleção exportada pode conter credenciais ou valores do ambiente. Limpar as coleções antes de as partilhar, não guardar segredos em texto simples como Initial Values e rodar as palavras-passe de teste depois de uma fuga.

Consultar Object Usage antes de alterações

A API pode devolver os nomes e o Usage Count dos objetos suportados. Para isso, são utilizados tags estatísticos como <IPHostStatistics> em vez do tag normal do objeto. Um filtro para nomes de IP Host tem este aspeto:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHostStatistics>
      <Filter>
        <key name="Name" criteria="like">branch</key>
      </Filter>
    </IPHostStatistics>
  </Get>
</Request>

O SFOS 22 suporta esta consulta de utilização para IP Hosts, IP Host Groups, MAC Hosts, FQDN Hosts e grupos, Country Groups, Services e Service Groups, assim como Interfaces, Zones, Gateways e SD-WAN Profiles. Os filtros de nome incluem like, not like, startswith, in, = e !=; o Usage Count suporta adicionalmente >, >= e listas de números com in.

Atualmente, a resposta contém apenas o nome do objeto e o número de utilizações, não as configurações dependentes. Por isso, um Usage Count de 3 não identifica as três regras ou perfis afetados. Antes de uma operação update ou remove, verificar também Object usage no WebAdmin ou no Config Studio. Um valor de 0 também não autoriza uma eliminação sem controlo: backup, verificação de dependências e teste limitado continuam obrigatórios.

Transferir ou exportar certificados através da API

Os certificados são um caso especial porque, além do XML, são transferidos ficheiros. Para criar ou atualizar um certificado, utilizar na aplicação desktop Postman um pedido form-data com três partes: ficheiro de certificado, ficheiro de Private Key e reqxml com um payload <Set><Certificate>...</Certificate></Set>. Os nomes dos ficheiros, o formato, a ação e o nome do certificado no XML têm de corresponder aos ficheiros carregados.

As Private Keys devem permanecer exclusivamente no endpoint de administração protegido e nunca chegar a uma cloud collection, ticket ou repositório. Depois de Send, avaliar primeiro <Response> e <Status>; em seguida, verificar em Certificates > Certificates se estão presentes exatamente o certificado esperado, a chave correspondente e a cadeia correta. A atribuição e o teste do serviço seguem o procedimento Importar e atribuir certificados no Sophos Firewall.

Um pedido <Get><Certificate/></Get> não devolve um resultado XML normal, mas um arquivo .tar com certificados, Private Keys e Entities.xml. Por isso, esta transferência não funciona como uma resposta normal do Postman; a Sophos documenta um navegador ou uma linha de comandos Linux. O arquivo é altamente sensível: transferi-lo apenas a partir de um host de gestão autorizado, armazená-lo cifrado e com acesso restrito, extraí-lo num local controlado e remover com segurança as cópias que já não sejam necessárias. Credenciais num URL, no histórico do navegador, na lista de processos ou no log do proxy representam um risco adicional que o método escolhido para gerir segredos e executar o pedido deve evitar.

Acesso à API e permissões de usuário

Um IP de origem sozinho não é um conceito de segurança completo. A restrição limita apenas de onde a API é acessível. Além disso, deve estar claro com qual conta o acesso à API é feito e quais permissões essa conta possui.

Para ambientes produtivos, deve-se verificar:

Está a ser utilizada uma conta de API ou de serviço própria?
A conta tem apenas as permissões necessárias?
Está claramente documentado qual pessoa ou equipe é responsável pela conta?
A senha ou segredo está armazenado de forma segura?
O acesso é removido quando a integração não é mais usada?
As alterações são rastreáveis através de logs de auditoria?

Contas de administrador compartilhadas são problemáticas para processos de API. Se vários sistemas ou pessoas usarem a mesma conta, a rastreabilidade é enfraquecida. Para análises de mudanças, é relevante verificar os logs de trilha de auditoria do Sophos Firewall.

Para uma conta API dedicada, um processo restrito é melhor do que copiar rapidamente um administrador completo. O planeamento geral de contas pessoais e perfis limitados é explicado em Configurar administradores e perfis Sophos Firewall em segurança; para automações, continua a ser determinante a conta de serviço separada aqui descrita. Na documentação Sophos, este bloco aparece como Allow API access to administrators: não é apenas a origem que é autorizada, o administrador ou o perfil também tem de ter o acesso adequado.

Criar um perfil de administrador com as permissões necessárias em Profiles > Device access.
Criar um utilizador administrador para o processo API em Authentication > Users.
Atribuir o perfil de administrador adequado.
Se o acesso for apenas temporário, limitar Access time.
Se possível, limitar Login restriction for device access às origens previstas.
Depois permitir API access e Device Access para a origem adequada.

A Sophos suporta as APIs oficiais e scripts de exemplo não modificados. Integrações, wrappers e automações próprias continuam a precisar de um responsável interno, testes e um conceito de rollback. “Funciona no lab” não é suficiente para operações de escrita em produção.

MFA e utilizadores API após SFOS 22

A MFA é importante para acessos administrativos interativos. Para processos API e de automação, porém, é necessário planear conscientemente como a autenticação deve funcionar. Um script, ferramenta de monitorização ou sistema de integração não consegue simplesmente introduzir um código OTP se o utilizador usado exigir MFA.

A lista Known Issues documenta um caso especial do SFOS 22: após uma atualização, alterações de configuração por API podem falhar para utilizadores migrados se MFA estiver ativa e nenhum one-time token for enviado. Utilizadores não migrados podem comportar-se de forma diferente em alguns casos. Para a operação, o importante não é desativar MFA em todo o lado, mas separar corretamente as contas API.

Abordagem recomendada:

Usar uma conta de serviço própria para processos API.
Atribuir à conta apenas os direitos necessários.
Limitar adicionalmente API access a IP Hosts fixos ou redes de gestão.
Verificar se MFA é tecnicamente e operacionalmente adequada para esta conta.
Se MFA não for prática para a conta API, controlar a conta de forma especialmente rígida através de fonte, direitos, armazenamento de segredos e audit trail.
Após uma atualização para SFOS 22, testar todos os processos API com operações de leitura e escrita.

⚠️ Utilizadores API sem MFA não são uma autorização para direitos amplos. Se uma conta API tiver de funcionar sem MFA por motivos técnicos, IP de origem, direitos, armazenamento da palavra-passe, responsabilidade e auditabilidade devem ser controlados com mais rigor.

Este ponto é especialmente importante em automações que não apenas leem, mas também alteram configuração.

Antes de alterações API em produção, verificar pelo menos três coisas:

Existe um backup da Sophos Firewall atual.
A conta API planeada consegue executar com sucesso uma consulta de leitura inofensiva.
Em alterações em massa preparadas com Sophos Firewall Config Studio, as chamadas API ou curl geradas funcionam com a conta planeada.

Distinção de Device Access

O controle de acesso à API não é o mesmo que Device Access, mas ambos os controles interagem. O Device Access controla serviços locais da firewall como WebAdmin, SSH, User Portal, VPN Portal, DNS ou Ping. As configurações de acesso à API controlam adicionalmente quais IP Hosts podem usar a API XML. Importante: as permissões de Device Access para a WebAdmin Console também se aplicam aos acessos API.

Na prática, isto significa que o API access deve estar permitido, a fonte deve estar autorizada nas configurações de acesso à API e o acesso local de gestão à firewall não pode estar bloqueado pelo Device Access. Cada camada limita uma parte diferente da superfície de ataque:

Configurar corretamente o Device Access: serviços locais da firewall como WebAdmin, SSH, User Portal, VPN Portal, DNS ou Ping
Controle de acesso à API: IP Hosts que também podem usar a API XML
Ativar MFA para WebAdmin, VPN Portal e Acesso Remoto do Sophos Firewall: Logins interativos para WebAdmin, VPN Portal e Acesso Remoto
Admins nomeados e papéis claros: Rastreabilidade e raio de dano de contas de admin e serviço

Se uma rede de administração pode usar WebAdmin, SSH e API, essa rede deve ser especialmente bem protegida. Um cliente comprometido na rede de gestão é, caso contrário, uma entrada direta na gestão da firewall.

Para acesso a partir da WAN, não se deve ativar HTTPS/WebAdmin para toda a zona WAN. Se o acesso externo à API ou à administração for realmente necessário, deve ser usada uma Local service ACL exception rule com uma Source estritamente limitada, o Service HTTPS adequado, uma posição de regra definida e um período documentado.

Operação e revisão

O acesso à API deve ser revisado regularmente. Especialmente após migrações, mudanças de prestadores de serviços, projetos de automação ou atualizações de firewall, muitas vezes permanecem fontes antigas.

Perguntas de revisão sensatas:

Quais IP Hosts podem atualmente usar o acesso à API?
Existem objetos com o prefixo apiconfig?
Esses objetos ainda são necessários?
Os nomes e descrições correspondem ao propósito real?
Existem responsáveis documentados?
Os acessos à API são considerados em um processo de mudança ou auditoria?
Existe um backup atual antes de grandes alterações baseadas em API?

Antes de alterações baseadas em API, deve sempre haver um backup. O artigo Criar ou restaurar backup do Sophos Firewall descreve o que deve ser considerado em relação a backup, restauração e compatibilidade.

Erros típicos

API access permitido para uma rede de clientes completa: Qualquer cliente comprometido nessa rede pode chegar à API.
Objetos apiconfig antigos não verificados: Exceções antigas migradas permanecem ativas sem serem notadas.
Conta de serviço usa direitos de administrador completos: Um segredo comprometido tem um raio de impacto desnecessariamente grande.
Automação API usa um administrador com MFA obrigatória: Script ou ferramenta pode falhar em operações de escrita após uma atualização SFOS.
Porta errada na ferramenta: A porta HTTPS de administração foi alterada, mas a ferramenta continua a usar a porta antiga.
Esperada lógica REST: A ferramenta envia métodos REST em vez de payload XML via HTTP POST para APIController.
Foi verificado apenas o estado HTTP: A operação real da API falhou apesar de o transporte ter sido bem-sucedido. Avaliar <Response> e <Status>.
Set foi enviado sem operação: O SFOS trata o pedido como add, embora estivesse prevista uma atualização.
Usage Count foi interpretado como uma lista completa de dependências: A estatística devolve número e nome, mas não as regras ou perfis afetados.
O arquivo de certificados foi guardado sem proteção: A exportação da API pode conter Private Keys e não deve ficar em Transferências, tickets ou armazenamento partilhado.
IP temporário do prestador continua ativo: O acesso externo permanece possível durante mais tempo do que o previsto.
Sem documentação sobre o objetivo: Administradores posteriores não sabem se uma autorização ainda é necessária.
Alterações API sem backup: Automação incorreta é mais difícil de reverter.

Resolução de problemas

Se uma ferramenta não conseguir acessar a API XML, deve-se verificar de forma estruturada:

O IP de origem está correto do ponto de vista da firewall?
A fonte está permitida como IP Host, intervalo de IP ou rede?
Um objeto apiconfig foi gerado após uma atualização, mas não foi ajustado adequadamente?
O Device Access permite acesso local WebAdmin/API a partir desta zona?
A ferramenta usa o endereço correto da firewall e a porta HTTPS de administração correta?
Nome de usuário, senha ou segredo estão corretos?
A conta tem os direitos necessários?
A conta exige MFA, embora a ferramenta não possa fornecer um token de uso único?
Existem efeitos de roteamento, NAT ou proxy entre a ferramenta e a firewall?
O acesso foi removido intencionalmente por uma medida de endurecimento?
O teste foi feito a partir do sistema de origem correto ou apenas a partir do cliente admin?

Se uma alteração na API tiver impactos inesperados, primeiro faça backup do último backup e depois verifique a trilha de auditoria, comparação do Config Studio e objetos de firewall afetados. Para problemas de tráfego ao vivo, o Log Viewer e o Packet Capture são mais úteis do que a própria API.

Lista de verificação

Antes da ativação:

Documentar o propósito do acesso à API.
Determinar claramente o sistema de origem.
Criar um objeto IP Host com um nome descritivo.
Verificar conta de serviço e permissões.
Definir conscientemente o comportamento do MFA da conta de API.
Estabelecer processo de backup e rollback.
Definir um método de teste sem fuga de segredos.
Documentar a operação XML planeada e o <Status> esperado.

Durante a operação:

Permitir acesso à API apenas para fontes definidas.
Não liberar redes amplas de clientes, convidados ou IoT.
Verificar objetos apiconfig após atualizações.
Controlar acessos de prestadores de serviços em termos de tempo e função.
Armazenar segredos de forma protegida e renovar em caso de mudança de pessoal ou ferramenta.
Rodar segredos se acabarem no histórico da shell, em tickets ou em armazenamento inseguro.
Testar operações de leitura e escrita da API após atualizações do SFOS.
Verificar Object Usage e as configurações dependentes antes de operações update ou remove.
Processar ficheiros de certificado, Private Keys e exportações da API apenas em locais protegidos.

Durante a revisão:

Revisar regularmente as fontes de API permitidas.
Remover IP Hosts que não são mais necessários.
Conciliar alterações com trilha de auditoria e tickets de mudança.
Testar processos de automação após atualizações de firmware.

FAQ

O que é a API XML do Sophos Firewall?

A API XML é uma interface de gestão do Sophos Firewall. Áreas de aplicação típicas são automação, integrações, monitorização ou consultas de configuração. A interface deve ser acessível apenas a partir de fontes de gestão ou automação definidas.

Onde se configura o acesso à API no SFOS 22?

A Sophos moveu as configurações de acesso à API para a seção Administration com o SFOS 22. Lá, pode-se definir quais IP Hosts recebem acesso à API.

O que significa o prefixo apiconfig?

Durante a atualização para o SFOS 22, a firewall converte endereços IP de API permitidos anteriormente em objetos IP Host. Esses objetos migrados são nomeados com o prefixo apiconfig e devem ser verificados após a atualização.

Uma restrição de IP de origem é suficiente como proteção de API?

Não. A restrição de IP de origem reduz as fontes acessíveis, mas não substitui contas limpas, permissões adequadas, armazenamento seguro de segredos, backups e auditabilidade.

Um usuário de API deve usar MFA?

Para administradores interativos, o MFA é sensato. Na automação de API, deve-se verificar se a ferramenta pode suportar um token de uso único. Se isso não for prático, deve-se usar uma conta de API dedicada com direitos mínimos, restrição de IP de origem rigorosa e auditoria limpa.

Deve-se manter o acesso à API ativado permanentemente?

Apenas se um processo específico precisar regularmente da API. Acessos temporários de teste ou de prestadores de serviços devem ser removidos ou desativados após a conclusão.