Ir al contenido
Avanet
Iniciar sesion

API REST de Sophos Firewall: acceso seguro y ciclo de vida de claves

Sophos Firewall

La API REST local de SFOS 23.0 permite consultar y modificar la configuración directamente en el firewall. Empezar con un administrador dedicado de permisos limitados, autorizar solo el host de automatización, generar la clave con esa cuenta y validar primero una lectura. La disponibilidad de documentación no confirma una fecha GA ni compatibilidad con firmware anterior.

Tres interfaces, tres identidades

  • API REST local: la clave de un administrador del firewall actúa como token Bearer; sus permisos proceden del perfil administrador.
  • API XML local: cargas XML y credenciales de administrador, normalmente mediante HTTP POST a APIController. XML <Get> no es una solicitud REST.
  • API de configuración de Sophos Central: principal de servicio cloud, token temporal, tenant y host API regional. Una clave local no sustituye estas credenciales.

Preparar acceso y administrador

  1. En Profiles > Device access, crear un perfil con los permisos necesarios; para inventario, solo los permisos de lectura apropiados. En Authentication > Users, crear un administrador dedicado con ese perfil. La planificación de administradores y perfiles explica los roles. No usar cuentas personales ni el admin predeterminado con todos los privilegios para los trabajos.
  2. En Hosts and services > IP host, definir el host real, por ejemplo api-inventory con 192.0.2.20. Sustituir nombre y dirección de documentación. Un origen fijo es más restrictivo que toda la red de gestión; con NAT importa el origen que ve el firewall.
  3. En Administration > API access, activar API access, desactivado por defecto, seleccionar solo los orígenes necesarios en Allowed IP hosts y pulsar Apply. Se admiten direcciones, rangos y redes, hasta 64 entradas. Revisar los orígenes apiconfig migrados al actualizar a SFOS 22.0 o posterior.
  4. En Administration > Device access, comprobar WebAdmin desde la zona correspondiente. Device Access y la lista API son controles distintos; no abrir el acceso WAN indiscriminadamente.

Generar y capturar la clave una sola vez

Iniciar sesión como administrador dedicado. En Administration > API access > REST API keys, pulsar Add API key, escribir un nombre descriptivo como inventory-prod-2026-10 y generar con Add API key.

Antes de Close: copiar la clave al almacén de secretos protegido del trabajo. Al cerrar la ventana no volverá a mostrarse. No incluirla en capturas, tickets, archivos del repositorio ni exportaciones de colecciones sin protección.

La clave es válida un año y hereda los permisos de su creador. Los administradores crean y eliminan sus propias claves; todos ven la lista, pero no recuperan el secreto. El admin predeterminado también puede eliminar claves ajenas. Límites: 10 claves por administrador, 1024 en total. No compartir claves entre administradores.

Construir la solicitud desde el esquema del firewall

En REST API help, descargar OpenAPI.yaml de este firewall e importarlo en Postman o Swagger. En REST API guide, comprobar autenticación, referencias de objetos y esquema del endpoint elegido. Los nombres se parecen a los de la interfaz, pero no siempre coinciden.

Documentación revisada el 29 de octubre de 2026, SFOS 23.0: La referencia generada de la API indica la base https://<firewall-host>:<port>/api/firewall-config/v1. Sin embargo, la introducción general indica una ruta sin /api y muestra incluso APIController en el primer ejemplo. Eso no constituye una instrucción fiable para probar distintas rutas. Para el firewall propio se utiliza la URL completa del servidor que figura en su esquema descargado; sin una operación local correspondiente no se ejecuta el siguiente piloto.

Primera consulta de lectura: hotfixes aplicados

La operación oficial GET /system/security-updates consulta las actualizaciones de seguridad hotfix aplicadas. No inicia una actualización ni un cambio de configuración. Antes de ejecutarla, comprobar que el esquema local contiene exactamente esa ruta con método GET y copiar la URL base completa.

Antes de ejecutar la consulta, confirmar en el esquema local la operación, la URL base y el formato de respuesta. Comprobar después el estado HTTP y los datos recibidos; no deducir el resultado de la solicitud únicamente de su sintaxis.

El ejemplo se ejecuta con Python 3 en el host de administración o automatización autorizado, no en Device Console. firewall.example.com, el puerto 4444 y la ruta del archivo CA son valores que deben sustituirse. El hostname debe coincidir con el certificado; 4444 es únicamente el puerto HTTPS administrativo elegido para este ejemplo. El archivo PEM contiene la CA emisora de confianza, no material de clave privada. Si la cadena ya es de confianza en el almacén de Python, puede utilizarse ca_file = None. No confiar en una CA descargada 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

La clave se solicita sin mostrarla, no se guarda como argumento de comando ni como literal en el script. El cliente solo acepta HTTPS y no sigue redirecciones: ante una respuesta 3xx inesperada se detiene en lugar de enviar la cabecera Bearer a otro destino. Durante el piloto no activar logs de depuración de la shell o del cliente; tampoco copiar sin revisar los datos del dispositivo mostrados en tickets. Para un trabajo desatendido se utilizará después el Secret Store previsto.

Interpretar la respuesta y los errores habituales

Si la solicitud se procesa correctamente, se espera HTTP 200. Los datos deben describir las actualizaciones de seguridad hotfix aplicadas. La cantidad y el contenido se contrastan con el estado conocido del dispositivo y con el esquema de respuesta de ese firmware; un body JSON válido no demuestra por sí solo integridad ni un nivel de parche concreto. Confirmar los nombres y tipos de los campos de respuesta en el esquema de la versión instalada y comprobar los valores recibidos.

  • 401: La referencia exige autenticación. Comprobar cabecera Bearer, clave correcta, caducidad y eliminación sin registrar el secreto.
  • 403: La referencia exige permisos. Comprobar la cuenta creadora y sus derechos para la operación, en lugar de conceder permisos de administrador completos de forma general.
  • 3xx: No seguir la redirección. Revisar la URL de servidor confirmada, un posible proxy intermedio y sus reglas de redirección; no enviar la clave al destino de la redirección.
  • 404: No está documentado como respuesta funcional de esta operación. Comprobar puerto administrativo, base completa del esquema, ruta, firmware y un posible proxy intermedio. No cambiar automáticamente al endpoint XML ni a un segundo prefijo REST.
  • 400 o 500: La referencia diferencia solicitud no válida y error interno del servidor. Comprobar método y esquema o estado del dispositivo y diagnóstico depurado.
  • Sin estado HTTP: Investigar DNS, ruta, conexión, timeout y cadena de certificados TLS. Ante errores de certificado, corregir hostname, cadena de confianza y validez; no desactivar la comprobación con -k ni con un contexto SSL sin verificar.

Prueba de lectura y control operativo

Validar primero la ruta autorizada desde el host real de automatización. Para la prueba negativa de origen, ejecutar la misma solicitud de solo lectura únicamente desde un host de prueba adicional autorizado que ya esté fuera de la lista de orígenes de API permitidos. No debe recibir configuración ni datos de hotfixes. No se garantiza un estado concreto de rechazo; una respuesta con datos supondría una prueba negativa fallida. No retirar permisos de producción ni utilizar una red ajena para la prueba.

La prueba negativa TLS también se realiza sin reducir protecciones: un hostname de prueba expresamente autorizado que no coincida deliberadamente con el certificado debe fallar en la comprobación del certificado antes de recibir datos de API. No modificar DNS productivo ni crear otra autorización de red para ello. Si no existe un nombre de prueba adecuado, esa parte de la validación queda pendiente. Documentar hora, host origen, firmware, versión del esquema, resultado HTTP/TLS y contraste funcional de datos, nunca la clave.

Antes de escribir, preparar copia de seguridad y recuperación, probar un pequeño cambio autorizado y comprobar el objeto en WebAdmin y el Audit Trail. Tras un timeout de escritura, consultar el estado real antes de reintentar. Consultas lentas, como firmas IPS, pueden necesitar un timeout mayor.

Caducidad, sustitución y eliminación

Documentar cuenta, trabajo, origen autorizado, creación, caducidad y equipo responsable, nunca la clave. Programar avisos y sustitución antes de caducar; no asumir renovación automática. Reservar un espacio libre para rotación con solapamiento. Con 10 claves propias o 1024 totales, identificar primero las innecesarias con su responsable, sin revocar trabajos activos indiscriminadamente.

Para una sustitución planificada, generar y capturar otra clave con la misma cuenta, cambiar el trabajo y validar una lectura. Después eliminar la clave antigua propia y comprobar que la nueva funciona y la anterior ya no concede acceso. No considerar recuperables las claves eliminadas. Sustituir también una clave cuya visualización única se haya perdido. Ante una posible filtración, revocar inmediatamente aunque interrumpa el servicio. Para claves ajenas, recurrir al responsable del admin predeterminado. Al retirar una integración, eliminar claves y orígenes innecesarios, revisando primero los compartidos.

Límites de SFOS 23.0

El alcance actual excluye de esta API REST:

  • Web: Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
  • Todas las funciones Email, Wireless y RED.
  • Network: DDNS e IP tunnels; SD-WAN profiles.
  • VPN: IPsec routes, GRE routes, L2TP, PPTP, clientes y servidores SSL VPN site-to-site.
  • Authentication: Guest users y clientless users; Firewall rule groups.
  • Let’s Encrypt certificates; High availability y TAP mode; System time.
  • Información de estado, como concesiones DHCP, estado HA y almacenamiento de datos.

La lista no es exhaustiva ni promete una versión futura. Verificar cada operación en el esquema actual; un menú visible no demuestra compatibilidad API. XML o cloud no son sustitutos automáticamente equivalentes.

Si el trabajo falla

Para conexión, revisar origen tras NAT, routing, puerto administrativo, TLS, acceso API y Device Access. Para autenticación o permisos, revisar clave, caducidad, eliminación, cuenta creadora y perfil en vez de otorgar todos los derechos. Para errores de esquema, comparar método, ruta, campos obligatorios y referencias dependientes. Una clave perdida se sustituye, no se vuelve a visualizar.

Para escalar, conservar firmware, versión del esquema, hora, endpoint, estado HTTP y respuesta saneada, sin secretos. Sophos admite la API oficial y scripts sin modificar, no asesoramiento ni troubleshooting de integraciones personalizadas. Estas necesitan un responsable interno; recurrir a un partner o Sophos Professional Services cuando sea necesario.