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. Também permite aplicar de forma reproduzível a mesma configuração a várias firewalls quando o processo está estritamente delimitado e testado. 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:

1. Verificar que sistema precisa de acesso API.
2. Em Hosts and services > IP host, criar um objeto IP Host claro para esse sistema.
3. Se forem necessárias várias fontes, nomear corretamente IP Hosts, IP ranges ou redes.
4. Em Administration > API access, ativar API access.
5. Em Allowed IP hosts, permitir apenas estes objetos.
6. Clicar em Apply.
7. Não inserir redes amplas de clientes ou servidores.
8. Testar o acesso a partir do verdadeiro host de automação ou monitorização, não do portátil do administrador.
9. Remover fontes que já não sejam necessárias.
10. 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.

O HTTPS só protege as credenciais de forma fiável contra interceção e manipulação quando o cliente valida o certificado da firewall. Por isso, o sistema de automação deve usar o nome presente no certificado, confiar na CA emissora e interromper a operação em caso de erro do certificado ou do hostname. Opções como curl -k ignoram esta verificação e não devem ser usadas em tarefas de produção.

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.
• Teste negativo: A partir de um host de teste controlado, deliberadamente ausente de Allowed IP hosts, enviar o mesmo pedido de leitura inofensivo e confirmar que a API o rejeita sem devolver dados de configuração. Não alargar nem remover uma autorização de produção apenas para criar este caso de teste.
• 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

Limite de versão: As instruções SFOS 22 incluem navegadores como clientes XML. Desde SFOS 23.0, a instrução específica de envio de pedidos XML exclui expressamente navegadores; usar Postman ou uma linha de comandos Linux controlada para estes POST. O resumo geral XML ainda menciona navegadores, mas isso não autoriza POST por navegador no SFOS 23.0. A REST API local com chaves administrativas é uma interface separada, não outra autenticação para estes payloads XML.

As consultas e alterações mostradas aqui usam HTTP POST para o mesmo APIController. Ler, criar, atualizar ou eliminar é definido no payload XML, não no método HTTP. XML <Get> significa leitura, não automaticamente HTTP GET; a consulta Object Usage chamada «API GET request» também é enviada por HTTP POST. A exportação de certificados abaixo é uma exceção HTTP GET documentada separadamente. A estrutura exterior inclui <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. A referência XML geral documenta apenas o nome do objeto Name, com os critérios =, != e like e a sintaxe <key name="Name" ...>. As estatísticas Object Usage, documentadas separadamente, suportam outras chaves e critérios; não os aplicar a consultas normais de objetos.

Nas operações de escrita, não confiar na omissão de operation em <Set>. A documentação descreve o valor omitido de forma contraditória: o resumo XML indica add, enquanto a referência XML completa para SFOS 22 e 23 indica Add seguido de Update. Isto não demonstra um comportamento predefinido exclusivamente de adição que tenha sido testado, nem um comportamento universal de upsert ou de substituição. Utilizar apenas uma operação explícita confirmada em API help para o objeto em causa e o build instalado; se este ponto não estiver esclarecido, não executar o pedido de escrita e solicitar esclarecimentos ao Support. APIXMLTags documenta o atributo alfanumérico opcional transactionid em <Set>; facilita a correlação entre o pedido e a resposta. Para operações especializadas, deve seguir-se o exemplo do objeto em API help do build SFOS utilizado. O exemplo de certificado coloca transactionid em <Certificate>; esta exceção não constitui uma regra geral para o colocar nas tags de objeto dentro de <Set>.

APIVersion em <Request> é específico da versão: a referência XML para SFOS 22 apresenta 2200.1 e a de SFOS 23 apresenta 2300.1. São exemplos da documentação, não uma recomendação para utilizar esse valor em todos os builds. Segundo a referência, APIVersion em <Response> contém o valor indicado no pedido; se o pedido o omitir, é considerada a versão da API do firmware ativo. No entanto, a secção sobre pedidos afirma que a indicação da versão é necessária, enquanto exemplos posteriores a omitem. Esta inconsistência interna não demonstra que o valor seja universalmente obrigatório ou opcional em tempo de execução. Por isso, as tags de objeto, os atributos, os códigos de estado e as configurações de exemplo exatos devem vir da API help do build SFOS utilizado; confirmar a versão e a compatibilidade do objeto antes da utilização e não transferir payloads entre versões sem verificação.

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.

Os valores seguintes são códigos de estado XML documentados no atributo code de <Status>, não códigos de estado HTTP. A mensagem e a secção Status Message Information do objeto em causa no build instalado determinam a interpretação exata:

• 200: configuração aplicada com sucesso; 201: sucesso apenas parcial. Com 203, a operação foi bem-sucedida, mas algumas configurações não foram aplicadas; a referência indica que se deve contactar o Support. 204–210 indicam falha parcial, não sucesso completo.
• 211–215: avisos; 216: sucesso explicado especificamente para o objeto. Em ambos os casos, consultar a respetiva Status Message Information, em vez de tratar todos os valores XML 2xx como sucesso completo da configuração.
• 500: não é possível executar a operação no objeto; 501: falha na validação dos parâmetros; 502: o nome já existe; 503: já existem os mesmos parâmetros. Com 504–510, uma referência noutro objeto impede a eliminação; verificar primeiro as dependências. Para 511–520, a referência exige esclarecimentos junto do Support.
• 521: pedido incompatível com a versão atual da API; 522–525: limite de objetos atingido; 526: o registo não existe; 528: objeto predefinido não editável; 529: XML inválido para o objeto; 530: versão da API não suportada para este objeto. 541–590 são erros específicos do objeto, com mais informações em Status Message Information; 599 indica falta de permissão para criar ou alterar.

Em caso de sucesso parcial ou de avisos, comparar a resposta com o estado real do objeto antes de tentar novamente uma operação de escrita; não assumir que a configuração foi integralmente aplicada nem que é inofensivo repetir o pedido. Partilhar com o Support apenas respostas e logs dos quais tenham sido removidos os dados sensíveis.

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

Transferir e importar a coleção Postman atual. A coleção abrange apenas parte dos pedidos suportados; a API help local da firewall mostra o conjunto completo de operações e as configurações de exemplo e definições de entidades específicas do build. Antes do primeiro pedido, substituir nas Collection Variables os quatro valores de exemplo incluídos apiadmin, Admin@12345, 172.16.16.16 e 4444 pelos valores username, password, firewall-ip e firewall-port do ambiente. Os valores de objetos incluídos também 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.

Importações XML sensíveis: Antes de importar palavras-passe ou outros valores sensíveis, verificar na API help do build instalado se a operação concreta exige SecureStorageMasterKey e o atributo Token em <Request> e quais os dados válidos. No exemplo POST do SFOS 23, SecureStorageMasterKey é um parâmetro separado no corpo; Token está em <Request> no XML do campo reqxml do corpo. Enviar apenas os dados confirmados para essa operação nas posições POST/XML aprovadas. Neste processo, manter chaves, palavras-passe e tokens fora dos URL, do histórico da shell e dos logs; isto não significa que todas as consultas XML exijam um token.

Quanto à origem, a referência XML descreve SecureStorageMasterKey como a chave mestra da firewall de origem, da qual foi exportada a configuração. Segundo a referência, sem esta chave não são importadas informações sensíveis, como palavras-passe, nem as definições que delas dependem; se a chave não estiver disponível, indica que se deve contactar o administrador predefinido com o nome de utilizador admin. Token e os valores cifrados das palavras-passe provêm do resultado Get/exportação documentado. A indicação hashform="mode1", por exemplo em <Password>, identifica aí um valor de palavra-passe cifrado; a referência menciona, em alternativa, uma palavra-passe não cifrada. Esta informação explica a origem e a interpretação dos dados, mas não autoriza a cópia de texto cifrado, tokens ou marcadores entre quaisquer objetos e builds. XML <Get> não autoriza automaticamente o método HTTP GET. Não é introduzido aqui nenhum novo comando de importação ou exportação; continuam obrigatórias a confirmação específica para o objeto e o build e a interrupção indicada a seguir caso os dados de entrada não estejam esclarecidos.

A documentação também mantém um exemplo de URL contraditório para a chave mestra. Enquanto um conflito entre fontes, um dado necessário ou a sua interpretação para o build instalado não estiver esclarecido, não executar a importação sensível e solicitar esclarecimentos ao Support. A exportação de certificados por HTTP GET descrita abaixo, com as suas precauções específicas, continua a ser uma exceção distinta.

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.

Em WebAdmin, Usage está disponível para interfaces, zonas, gateways, perfis SD-WAN, hosts e serviços. O contador é atualizado uma vez por dia; antes de uma alteração, atualizá-lo com o controlo junto a Usage. Clicar no contador do objeto, expandir a categoria relevante e abrir a regra ou política indicada para substituir ou remover aí o objeto. Isto remove a referência, não automaticamente o próprio objeto. Algumas configurações de gateways WAN e CLI não podem ser editadas na janela Object Usage; utilizar a página de configuração correspondente ou a CLI.

Iniciar e terminar sessões de Live Users através da API

O SFOS pode iniciar ou terminar a sessão de um utilizador como Live User através da API. Isto é adequado para uma integração com um sistema de autenticação externo que tenha uma responsabilidade claramente definida, mas não é um atalho geral para contornar o login normal. Um login incorreto associa tráfego a uma identidade e pode, por isso, influenciar regras de firewall ou web baseadas em utilizadores.

Para o administrador que executa a operação, Manage live users tem de estar definido como Read-write em Profiles > Device access > Identity. O endpoint previsto é:

https://<Firewall-IP-ou-FQDN>:<Port>/xmlapi/v1/authentication/networkuser

Este endpoint processa logins e logouts em paralelo. O APIController geral pode processar as mesmas operações em série. Por isso, uma integração existente não deve ser migrada sem teste apenas devido a esta diferença de comportamento.

Um payload de login pode ter esta estrutura:

<Request>
  <LiveUserLogin>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogin>
</Request>

Para terminar a sessão, envia-se o mesmo utilizador lógico com LiveUserLogout:

<Request>
  <LiveUserLogout>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogout>
</Request>

api-liveusers, ADMIN_SECRET, testuser, 192.0.2.25 e o endereço MAC são valores de exemplo. O nome de utilizador, o endereço IP e o endereço MAC têm de corresponder à sessão real. O segredo de administrador deve ser guardado no secret store protegido da ferramenta e enviado no corpo HTTP POST, não num URL, no histórico da shell, num ficheiro de log ou numa collection partilhada.

Depois do login, o utilizador tem de aparecer em Current activities > Live users com Client type API client. Um teste controlado verifica em seguida a decisão esperada da regra baseada em utilizadores. Depois do logout, a sessão já não deve constar como cliente API ativo. Se o utilizador continuar visível, verificar primeiro o payload, o nome de utilizador, o endereço IP, o endereço MAC e a resposta da API; não terminar por suspeita uma sessão Live User alheia.

Transferir ou exportar certificados através da API

No Postman, criar um pedido através de New > HTTP Request, atribuir-lhe um nome com Save e guardá-lo numa collection. Utilizar POST e o endpoint APIController acima com a porta WebAdmin real. A aplicação desktop envia por predefinição a partir desse computador; permitir o seu IP de origem tal como é visto pela firewall. Em Body > form-data, criar uma entrada com nome do tipo File para o certificado e outra para a chave privada, selecionando os ficheiros locais; a terceira entrada, reqxml, é do tipo Text. Guardar os ficheiros localmente com acesso restrito, não numa pasta sincronizada com a cloud.

O exemplo Postman utiliza C:/Users/[yourname]/Postman/files como localização Windows. Substituir [yourname] e verificar as restrições de acesso e o acesso local da aplicação aos ficheiros; este caminho não é um parâmetro geral de SFOS.

⚠️ Exemplo do fabricante para documentação, não autorizado para execução: O payload de certificado PEM seguinte para reqxml omite operation em <Set>. Devido às descrições contraditórias do comportamento predefinido, não o enviar, nem sequer para criar um certificado novo. Esclarecer primeiro a operação explícita e o payload completo do certificado para o objeto e o build instalado em API help ou junto do Support. Todas as contas, segredos, objetos e nomes de ficheiros são valores de exemplo:

<Request><Login><Username>api-certificates</Username><Password>SECRET</Password></Login><Set><Certificate transactionid="10"><Name>TestCertificate</Name><Action>UploadCertificate</Action><CertificateFormat>pem</CertificateFormat><CertificateFile>TestCertificate.pem</CertificateFile><PrivateKeyFile>TestCertificate.key</PrivateKeyFile></Certificate></Set></Request>

CertificateFile e PrivateKeyFile identificam os ficheiros selecionados para upload. O atributo opcional transactionid permite relacionar este pedido com a resposta. A omissão de operation não demonstra que se trate de criação ou de atualização; o exemplo do fabricante, mantido sem alterações, continua bloqueado até haver esclarecimentos específicos para o objeto e o build. Em particular, para um certificado existente, verificar o payload de atualização concreto em API help, em vez de o reenviar sem verificação. Só após este esclarecimento enviar um payload confirmado; depois, consultar a resposta em Body e verificar o certificado de destino em WebAdmin.

Os certificados são um caso especial porque, além do XML, são transferidos ficheiros. Para um payload de criação ou atualização confirmado, utiliza-se na aplicação desktop do Postman um pedido form-data com três partes: ficheiro de certificado, ficheiro de chave privada e reqxml com a operação explícita confirmada em <Set> e os campos <Certificate> correspondentes. A estrutura abreviada do exemplo bloqueado não é um modelo executável. 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. Todo o percurso de automação, desde a CA pública e o upload específico do build até à atribuição ao serviço e à verificação externa, está descrito em Renovar um certificado Sophos Firewall através da API XML e verificar os serviços.

Um pedido <Get><Certificate/></Get> devolve um arquivo .tar com certificados, Private Keys e Entities.xml, não um resultado XML normal. Não funciona, portanto, como resposta normal do Postman. A instrução específica documenta HTTP GET via Linux ou navegador; ambas as variantes colocam credenciais no reqxml do URL.

SFOS 23.0: Esta instrução GET ainda menciona navegadores, enquanto a instrução POST os exclui. Isto não comprova proibição de todos os HTTP GET nem exportação por navegador testada neste firmware. Não transportar instruções antigas de navegador nem assumir que POST fornece o mesmo download. Antes de exportar, verificar com Support ou num sistema de teste autorizado o caminho CLI GET e o tratamento seguro de credenciais para o build instalado; sem verificação, não executar a exportação.

Para uma exportação verificada usar apenas conta temporária com direitos limitados num host protegido, não registar URL ou comando e depois rodar o segredo. Validar certificado TLS e hostname; não transportar -k dos exemplos do fabricante para produção. O arquivo é altamente sensível: guardar cifrado com acesso restrito, extrair de forma controlada e eliminar seguramente cópias inúteis.

Numa exportação CLI autorizada, definir um caminho de saída local explícito para filename.tar. Antes de extrair, verificar as entradas com tar -tf filename.tar; não aceitar caminhos ou ligações inesperados. Extrair com tar -xvf filename.tar apenas num diretório de destino vazio e com acesso restrito. filename.tar é um nome de exemplo. A saída destes comandos pode revelar nomes de ficheiros sensíveis e não deve chegar a logs públicos.

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.

1. Criar um perfil de administrador com as permissões necessárias em Profiles > Device access.
2. Criar um utilizador administrador para o processo API em Authentication > Users.
3. Atribuir o perfil de administrador adequado.
4. Para acesso temporário à API, designar um responsável e agendar a remoção manual da conta API dedicada e/ou da autorização de origem dedicada à API no fim do período aprovado; verificar depois que esse acesso à API foi efetivamente revogado sem desativar acessos partilhados legítimos. Access Time para utilizadores comuns controla o acesso à internet; Schedule for device access para administradores controla os inícios de sessão em WebAdmin. Nenhuma destas definições está aqui documentada como mecanismo de expiração automática do acesso à API XML: não confiar nelas para terminar o acesso à API. Se for necessário aplicar um horário, obter previamente confirmação na documentação primária da compilação instalada ou através de uma verificação autorizada.
5. Se possível, limitar Login restriction for device access às origens previstas.
6. Depois permitir API access e Device Access para a origem adequada.

No exemplo oficial, o perfil recebe Read-write para Objects e Network. Não é uma recomendação geral: para integrações apenas de leitura e outras tarefas de API, as áreas desnecessárias permanecem em None ou Read-only; a permissão de escrita só é concedida após um teste de leitura controlado.

A Sophos suporta as APIs oficiais e scripts de exemplo não modificados. O suporte técnico da Sophos não presta aconselhamento nem resolução de problemas para integrações personalizadas; a Sophos encaminha este trabalho para o Sophos Partner responsável ou para a Sophos Professional Services. Por isso, integrações, wrappers e automações próprias precisam 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.

Os direitos do perfil não autorizam a origem: Os perfis em Profiles > Device access aplicam-se a WebAdmin e à API; a ACL de serviços locais em Administration > Device access é um controlo diferente. Os perfis predefinidos não podem ser editados. Utilizar Edit para consultar os direitos; criar e editar um perfil personalizado para os adaptar. Antes de eliminar um perfil, retirar a atribuição a todos os administradores. Cada área suporta None, Read-only e Read-write. Com None, a configuração não é visível em WebAdmin nem pode ser obtida pela API; a ausência de dados API não significa automaticamente uma falha de rede.

Os perfis predefinidos têm âmbitos diferentes: Administrator, incluindo a conta predefinida admin, tem acesso completo a WebAdmin e CLI, todos os tipos de pedido API e pode criar administradores. Audit admin tem Read-write para logs e relatórios; Crypto admin para certificados de segurança. HAProfile tem acesso Read-only ao equipamento Auxiliary quando HA está configurada. Security admin tem Read-write para todas as funcionalidades exceto perfis, logs e relatórios. Não assumir que um destes é um perfil API de privilégios mínimos; verificar os direitos efetivos no objeto necessário.

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 atual de Known Issues documenta NC-177609 para SFOS 22.0.0 GA Respin Build 411: após uma atualização, alterações de configuração por API podem falhar para utilizadores migrados se a MFA estiver ativa e não for enviado um one-time token. Os utilizadores não migrados mantêm o comportamento anterior até ao onboarding da MFA. O workaround oficial é uma conta API separada sem MFA ou a exclusão dessa conta da MFA. Isto não justifica desativar a MFA para administradores interativos; para builds posteriores, consultar primeiro as Release Notes e Known Issues.

Abordagem recomendada:

1. Usar uma conta de serviço própria para processos API.
2. Atribuir à conta apenas os direitos necessários.
3. Limitar adicionalmente API access a IP Hosts fixos ou redes de gestão.
4. Verificar se MFA é tecnicamente e operacionalmente adequada para esta conta.
5. 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.
6. 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.

HA: verificar o acesso após um failover

Num cluster HA, a configuração da firewall é sincronizada do Primary para o Auxiliary; o link HA dedicado e as Administration Ports não são sincronizados. Por isso, os clientes API devem usar o nome do cluster ou o endereço de interface partilhado previstos e não depender inadvertidamente de um endereço de administração específico de um nó.

Após configurar o HA, alterar o certificado ou ocorrer um failover, repetir um teste de leitura e um teste negativo. Verificar a resolução DNS, o nome do certificado, o IP de origem, a porta de administração, API access e Device Access. Um objeto host sincronizado não prova, por si só, que todo o percurso de rede e TLS funciona após a troca de funções.

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 enviado sem operação: Não confiar num comportamento predefinido nem repetir o pedido sem verificação. As descrições documentadas contradizem-se; antes de qualquer escrita, confirmar a operação explícita para o objeto e o build; caso contrário, interromper.
• Não é possível importar definições ou tokens MFA: O payload deve conter o elemento vazio <tokenid/>.
• Não é possível eliminar um utilizador: No payload <Remove>, indicar o nome de utilizador exato como <Name>username</Name>. Antes de enviar o pedido, verificar a conta, as dependências, o backup e o rollback.
• 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.
• Sessão de Live User iniciada sem correlação: O nome de utilizador, o endereço IP e o endereço MAC não correspondem à sessão real, pelo que as regras baseadas em utilizadores podem tomar decisões incorretas.
• 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:

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

Se uma alteração da API tiver efeitos inesperados, primeiro proteja a última cópia de segurança e depois verifique o trilho de auditoria, a comparação do Config Studio e os objetos da firewall afetados. Para problemas de tráfego em tempo real, o Log Viewer e o Packet Capture são mais úteis do que a própria API.

Numa operação XML rejeitada ou com erro, guardar primeiro <Response> e <Status>. Depois, verificar apiparser.log, validation.log e validationError.log em Diagnostics > Tools > Troubleshooting logs; a Sophos associa estes ficheiros à tradução e validação da API. Ficheiros de serviço e logs do Sophos Firewall explica como filtrar e exportar. Remover os segredos antes de partilhar um excerto do log.

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.
• Validar logins de Live Users via API com API client, a decisão da regra e um logout correto.
• 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