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 autenticação, referências de objetos e esquema do endpoint escolhido. Os nomes assemelham-se à interface, mas nem sempre coincidem.

SFOS 23.0: A referência gerada da API indica a base https://<firewall-host>:<port>/api/firewall-config/v1. A introdução geral indica, pelo contrário, um caminho sem /api e apresenta até APIController no primeiro pedido. Isto não é uma instrução fiável para experimentar vários caminhos. Para o firewall próprio, aplica-se o URL completo do servidor no esquema descarregado; sem operação local correspondente, não executar o piloto seguinte.

Primeiro pedido de leitura: consultar hotfixes aplicados

A operação oficial GET /system/security-updates lê as atualizações de segurança hotfix aplicadas. Não inicia uma atualização nem altera a configuração. Antes do pedido, confirmar no esquema local a existência desse caminho exato com método GET e copiar o URL base completo.

Comparar a resposta HTTP e os dados devolvidos com a operação solicitada.

O exemplo executa Python 3 no host administrativo ou de automação aprovado, não na Device Console. firewall.example.com, a porta 4444 e o caminho do ficheiro CA são valores a substituir. O hostname tem de corresponder ao certificado; 4444 é apenas a porta HTTPS administrativa escolhida no exemplo. O ficheiro PEM contém a CA emissora de confiança, não material de chave privada. Se a cadeia de certificados já for considerada fiável pelo truststore Python, pode utilizar-se ca_file = None. Não confiar numa CA descarregada arbitrariamente.

python3 - <<'PY'
import getpass
import json
import ssl
import urllib.error
import urllib.request

# Vollständige servers-URL des lokalen Schemas übernehmen.
# Dieser Beispielpfad entspricht der generierten Referenz.
api_base = "https://firewall.example.com:4444/api/firewall-config/v1"
ca_file = "/pfad/zur/management-ca.pem"
if not api_base.startswith("https://"):
    raise SystemExit("Nur die bestätigte HTTPS-Server-URL verwenden.")
context = ssl.create_default_context(cafile=ca_file)

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = urllib.request.build_opener(
    NoRedirect(), urllib.request.HTTPSHandler(context=context)
)
api_key = getpass.getpass("Freigegebener REST-API-Schlüssel: ")
request = urllib.request.Request(
    api_base.rstrip("/") + "/system/security-updates",
    method="GET",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer " + api_key,
    },
)
try:
    with opener.open(request, timeout=30) as response:
        status = response.status
        body = response.read()
except urllib.error.HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: Ursache vor erneutem Aufruf prüfen.")
except urllib.error.URLError as error:
    raise SystemExit(f"Verbindungs- oder TLS-Fehler: {error.reason}")

print(f"HTTP {status}")
if status != 200 or not body:
    raise SystemExit("Noch keine Abnahme: Status und Body mit dem Schema abgleichen.")
try:
    data = json.loads(body)
except (json.JSONDecodeError, UnicodeDecodeError):
    raise SystemExit("Kein gültiger JSON-Body; Zielpfad und Antwort prüfen.")
print(json.dumps(data, indent=2, ensure_ascii=False))
PY

A chave é solicitada com entrada oculta, sem ficar como argumento de comando nem literal no script. O cliente aceita apenas HTTPS e não segue redirecionamentos: perante uma resposta 3xx inesperada, para em vez de enviar o cabeçalho Bearer a outro destino. Não ativar logs de depuração da shell ou do cliente durante o piloto; os dados do dispositivo apresentados também não devem ser copiados sem verificação para tickets. Para um trabalho não supervisionado, utilizar posteriormente o Secret Store previsto.

Interpretar a resposta e os erros típicos

A resposta de sucesso esperada é HTTP 200. Os dados devem descrever as atualizações hotfix de segurança aplicadas. Comparar quantidade e conteúdo com o estado conhecido do dispositivo e o esquema de resposta dessa versão de firmware; um corpo JSON válido não comprova completude nem um nível específico de correções. Confirmar os nomes dos campos no esquema da versão instalada antes de interpretar a resposta.

401: A referência exige autenticação. Verificar cabeçalho Bearer, chave correta, validade e eliminação, sem registar o segredo.
403: A referência exige autorização. Verificar conta criadora e direitos para a operação, em vez de atribuir indiscriminadamente administração total.
3xx: Não redirecionar. Verificar o URL de servidor confirmado, eventual proxy intermédio e respetivas regras; não transportar a chave para o destino do redirecionamento.
404: Não está documentado como resposta funcional desta operação. Verificar porta administrativa, base completa do esquema, caminho, firmware e eventual proxy. Não mudar automaticamente para o endpoint XML nem para outro prefixo REST.
400 ou 500: A referência distingue pedido inválido de erro interno. Verificar método e esquema ou estado do dispositivo e diagnóstico expurgado.
Sem estado HTTP: Investigar DNS, rota, ligação, timeout e cadeia de certificados TLS. Corrigir hostname, cadeia de confiança e validade perante erros de certificado; não desativar a verificação com -k nem com um contexto SSL não validado.

Teste de leitura e controlo operacional

Validar primeiro o percurso permitido a partir do host real de automação. Para o teste negativo de origem, executar o mesmo pedido exclusivamente de leitura apenas a partir de um host de teste adicional aprovado que já esteja fora da lista de origens API. Não deve receber configuração nem dados de hotfixes. Não se garante um estado de recusa específico; uma resposta com dados significaria falha do teste negativo. Não remover autorizações de produção nem utilizar uma rede alheia para o teste.

O teste negativo TLS também não reduz a proteção: um hostname de teste deliberadamente incompatível com o certificado, expressamente aprovado, deve falhar na validação do certificado antes de receber dados API. Não alterar DNS de produção nem criar outra autorização de rede para isso. Sem nome de teste adequado, esta parte da validação fica pendente. Documentar momento, host de origem, firmware, versão do esquema, resultado HTTP/TLS e comparação funcional dos dados, nunca a chave.

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.