Kassinipedia

Automatización y API

Se lee en 8 min

Automatización y API

Resumen

Todo lo que haces en la interfaz web del firewall también se puede hacer por API: leer estado, cambiar configuración, hacer commit, registrar IP con tags, consultar sesiones. Esto permite automatizar tareas repetitivas (crear objetos y reglas en lote, respaldos programados, aislar un equipo infectado en segundos) y reducir errores humanos. PAN-OS ofrece dos APIs principales: la XML API (la clásica, con cuatro tipos de petición: keygen, op, config y commit, más user-id y export) y la REST API (recursos JSON por objeto: direcciones, reglas, zonas…). Ambas se usan con HTTPS y una API key.
Además de scripts con curl, existen herramientas que se apoyan en esas APIs: el SDK de Python pan-os-python (y pan-python), módulos de Ansible y el proveedor de Terraform para Palo Alto, que permiten tratar la configuración como código. Esta nota explica cómo obtener una API key, ejemplos básicos de XML y REST con curl, el patrón seguro para cambiar y confirmar configuración, buenas prácticas de seguridad y los errores más comunes. Es contenido propio para la vida real: no depende de un laboratorio.

Requisitos previos

  • Acceso HTTPS a la interfaz de gestión del firewall o de Panorama desde el equipo donde correrá el script (ver Initial Setup y Management Plane)
  • Una cuenta de servicio dedicada, con un Admin Role que habilite solo la API y los permisos necesarios (ver Admin Authentication y RBAC)
  • La IP del equipo de automatización en la lista de Permitted IP Addresses (ver Hardening del Management Plane)
  • curl (o Python, Ansible, Terraform) en el equipo de automatización
  • Un entorno de laboratorio para probar antes de ejecutar contra producción
  • Un respaldo reciente de la configuración (ver CLI y Config Management)
  • Un lugar seguro (un gestor de secretos) para guardar la API key

Conceptos clave

ConceptoQué es
API keyCadena que identifica y autoriza a una cuenta; se envía en cada petición
XML APIInterfaz clásica: /api/?type=... con parámetros en la URL y respuesta XML
REST APIInterfaz JSON por recursos: /restapi/<versión>/Objects/Addresses?...
type=keygenGenera la API key a partir de usuario y contraseña
type=opEjecuta un comando operativo (como show system info)
type=configLee o modifica la configuración candidata (get, show, set, edit, delete…)
type=commitConfirma la configuración candidata
type=user-idRegistra o elimina mapeos IP-usuario o IP-tag
XPathLa ruta del elemento dentro de la configuración XML
Candidate configConfiguración pendiente de commit; las llamadas config la modifican
sequenceDiagram
    participant S as Script / Ansible / Terraform
    participant F as Firewall o Panorama
    S->>F: keygen (usuario y contraseña) o API key guardada
    F-->>S: API key
    S->>F: config set (candidate config)
    F-->>S: success
    S->>F: commit
    F-->>S: job id
    S->>F: op show jobs id (hasta FIN)
    F-->>S: result OK

Configuración y uso (Ejemplo)

Se usa 192.168.1.51 como firewall de ejemplo y <API-KEY> como marcador. Cambia ambos por los tuyos.

1. Cuenta de servicio y rol de API

  1. Device > Admin Roles > Add: Name API-Automation.
  2. Pestaña XML API: habilita solo lo necesario (Configuration, Operational Requests, Commit, User-ID Agent, Export…). Pestaña REST API: habilita los recursos que usarás.
  3. Pestaña Web UI y Command Line: None en Command Line si la cuenta no necesita entrar por ahí (en Web UI usa Disable por área).
  4. Device > Administrators > Add: Name svc-automation, Authentication (contraseña fuerte), Administrator Type Role Based, Profile API-Automation.
  5. Commit.

2. Obtener la API key

curl -k -X GET "https://192.168.1.51/api/?type=keygen&user=svc-automation&password=<CONTRASEÑA>"

La respuesta es un XML con <key>...</key>. Guarda la clave en un gestor de secretos. Para no dejar la contraseña en el historial, usa -X POST con --data-urlencode:

curl -k -X POST "https://192.168.1.51/api/" --data-urlencode "type=keygen" --data-urlencode "user=svc-automation" --data-urlencode "password=<CONTRASEÑA>"

-k ignora el certificado: úsalo solo en laboratorio. En producción confía en la CA del firewall (ver Certificates y PKI) y quita -k.

3. Comandos operativos (type=op)

curl -k -G "https://192.168.1.51/api/" --data-urlencode "type=op" --data-urlencode "cmd=<show><system><info></info></system></show>" --data-urlencode "key=<API-KEY>"
curl -k -G "https://192.168.1.51/api/" --data-urlencode "type=op" --data-urlencode "cmd=<show><high-availability><state></state></high-availability></show>" --data-urlencode "key=<API-KEY>"
curl -k -G "https://192.168.1.51/api/" --data-urlencode "type=op" --data-urlencode "cmd=<show><session><info></info></session></show>" --data-urlencode "key=<API-KEY>"

El cmd es el comando de CLI convertido a XML: cada palabra es una etiqueta anidada. Para descubrir el XML de un comando, ejecuta el comando en la CLI con debug cli on y verás la petición XML correspondiente.

4. Leer y modificar configuración (type=config)

Leer un objeto de dirección:

curl -k -G "https://192.168.1.51/api/" --data-urlencode "type=config" --data-urlencode "action=get" --data-urlencode "xpath=/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']/address/entry[@name='DMZ-Server']" --data-urlencode "key=<API-KEY>"

Crear un objeto de dirección:

curl -k -G "https://192.168.1.51/api/" --data-urlencode "type=config" --data-urlencode "action=set" --data-urlencode "xpath=/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']/address" --data-urlencode "element=<entry name='API-Host-1'><ip-netmask>10.10.0.50/32</ip-netmask></entry>" --data-urlencode "key=<API-KEY>"

Confirmar (commit):

curl -k -G "https://192.168.1.51/api/" --data-urlencode "type=commit" --data-urlencode "cmd=<commit></commit>" --data-urlencode "key=<API-KEY>"

La respuesta trae un job id; consúltalo hasta que termine:

curl -k -G "https://192.168.1.51/api/" --data-urlencode "type=op" --data-urlencode "cmd=<show><jobs><id>5</id></jobs></show>" --data-urlencode "key=<API-KEY>"

Los xpath son largos y sensibles a comillas: para obtener el xpath exacto de algo que existe, mira la configuración en XML (Device > Setup > Operations > Export named configuration snapshot) o usa show en la API.

5. Registrar IP con tags (respuesta automática)

curl -k -X POST "https://192.168.1.51/api/?type=user-id&key=<API-KEY>" --data-urlencode "cmd=<uid-message><version>2.0</version><type>update</type><payload><register><entry ip='10.10.0.105'><tag><member>quarantine</member></tag></entry></register></payload></uid-message>"

Con un Dynamic Address Group asociado al tag, esa IP queda bloqueada sin commit (ver Dynamic Address Groups y Tagging).

6. REST API (JSON)

curl -k -X GET "https://192.168.1.51/restapi/v10.2/Objects/Addresses?location=vsys&vsys=vsys1&name=DMZ-Server" -H "X-PAN-KEY: <API-KEY>"
curl -k -X POST "https://192.168.1.51/restapi/v10.2/Objects/Addresses?location=vsys&vsys=vsys1&name=API-Host-2" -H "X-PAN-KEY: <API-KEY>" -H "Content-Type: application/json" -d '{"entry":{"@name":"API-Host-2","ip-netmask":"10.10.0.51/32"}}'

Cambia v10.2 por la versión de tu PAN-OS (por ejemplo v11.0). El REST modifica la configuración candidata; hace falta commit por la XML API o la GUI. En Panorama, la ubicación es location=device-group&device-group=<nombre>.

7. Herramientas de automatización

HerramientaPara qué
pan-os-pythonSDK de Python para escribir scripts orientados a objetos (direcciones, reglas, commits)
Ansible (colección paloaltonetworks.panos)Playbooks que definen el estado deseado de reglas, objetos y más
Terraform (proveedor panos)Configuración como código con planificación (plan) y aplicación (apply)

Con cualquiera de ellas aplica el mismo patrón: cambios pequeños, probados en laboratorio, versionados (Git) y con commit controlado.

8. Patrón seguro de cambios

  1. Respaldo antes de cambiar (export de la configuración).
  2. Cambio en la candidata (config set / REST).
  3. Validación (validate full antes del commit: type=op&cmd=<validate><full></full></validate>).
  4. Commit y espera del job hasta FIN y OK.
  5. Verificación (consulta de lo cambiado y de los logs).
  6. Reversa: si algo falla, revert de la candidata (type=op&cmd=<load><config><from>running-config.xml</from></config></load>) o carga del respaldo.

Concurrencia

Si dos personas o scripts modifican la candidata a la vez, un commit puede incluir cambios ajenos. Usa config lock (<request><config-lock><add></add></config-lock></request>) en cambios grandes, o commits por administrador (Partial commit/commit scope).

Verificación

Comando o lugarQué debes verSi no lo ves
Respuesta de keygenstatus="success" con <key>Si error, revisa usuario, contraseña y el permiso de API
Respuesta de opstatus="success" y el resultado del comandoSi Invalid command, revisa el XML del comando
Respuesta de config setstatus="success"Si error, el xpath o el elemento son inválidos
Tasks (icono de tareas, abajo a la derecha) o show jobs allEl job de commit en FIN / OKSi FAIL, lee el detalle
GUI: Objects > AddressesEl objeto creado por APISi falta, el cambio está en candidata sin commit o hubo error
Monitor > Logs > ConfigLa entrada del cambio con el usuario svc-automationSi no aparece, no se aplicó
Monitor > Logs > SystemAutenticaciones de la cuenta de servicioÚtil para detectar usos extraños
show object registered-ip allLas IP registradas con tagsSi falta, revisa el XML del registro

Errores comunes

Invalid credentials o 403 al usar la API

  • Causa: usuario o clave incorrectos, la cuenta no tiene permisos de API en su Admin Role, o la IP de origen no está en Permitted IP Addresses.
  • Solución: revisa el rol (pestañas XML API/REST API), la IP permitida y vuelve a generar la clave.

Invalid XPath o Object not found

  • Causa: el xpath tiene un nombre de entry, vsys o dispositivo incorrectos, o comillas mal escapadas.
  • Solución: obtén el xpath exacto desde la configuración XML exportada y usa --data-urlencode para evitar problemas de escape.

El cambio se hizo pero no aparece en la política activa

  • Causa: no hubo commit.
  • Solución: haz commit y espera el job.

El commit falla con errores de validación

  • Causa: referencias a objetos que no existen, zonas inválidas o reglas duplicadas.
  • Solución: ejecuta validate full y corrige lo que indique.

Mi script cambia cosas de otro administrador

  • Causa: la candidata es compartida, y el commit las incluye.
  • Solución: usa config lock o commit por administrador, y coordina los cambios.

Error de certificado con curl

  • Causa: el firewall usa un certificado autofirmado o de una CA que el equipo no conoce.
  • Solución: instala la CA correcta (no uses -k en producción).

La API key se filtró

  • Causa: quedó en un script, historial o repositorio.
  • Solución: genera una clave nueva (cambia la contraseña de la cuenta de servicio y regenera) y revoca la anterior; no guardes claves en Git, usa un gestor de secretos.

REST devuelve 404 o Invalid version

  • Causa: la versión de la URL no coincide con la de PAN-OS, o el recurso no existe en esa versión.
  • Solución: usa la versión correcta (show system info > sw-version) y revisa la documentación de la API de esa versión.

Vista Gráfica

Retroenlaces