IBM Sample Code

Este repositorio contiene código Python para gestionar IBM Security Appliances mediante sus respectivas API REST. El appliance ISAM es el que tiene el código más maduro.

El código para el appliance ISDS está en desarrollo.

El código para el appliance ISVG es nuevo (probado solo con 10.0.1.0 y superiores).

Requisitos

Se requiere Python v3.9 o superior para este paquete.

Se requieren los siguientes paquetes de Python:

1. requests - para realizar llamadas a la API REST
2. PyYAML - para que el código de ejemplo funcione
3. jmespath - es necesario para el código de ejemplo

Los siguientes paquetes de Python son opcionales:

1. cryptography - para realizar acciones sobre certificados (utilizado para la idempotencia en management_ssl_certificate)
2. python-dateutil - utilidades de fecha (utilizadas para la idempotencia en management_ssl_certificate)

Los appliances deben tener una dirección ip definida para su LMI. Esto puede significar que los appliances hayan completado su configuración inicial con la aceptación de la licencia.

Verificación TLS habilitada (v2024.4.5)

Estos cambios son compatibles con versiones anteriores. Por defecto no se verifica, pero siempre se muestra un aviso:

La verificación de certificados ha sido deshabilitada. Python NO está verificando el certificado SSL
del appliance host y los mensajes InsecureRequestWarning están

siendo suprimidos para el siguiente host:

https://{0}:{1}

Para utilizar la verificación de certificados:

1. Cuando el certificado sea de confianza en su entorno Python:
   Cree todas las instancias de ISAMAppliance con verify=True o establezca
   la variable de entorno IBMSECLIB_VERIFY_CONNECTION=True.
2. Cuando el certificado no sea aún de confianza en su entorno Python:
   Cree todas las instancias de ISAMAppliance con el parámetro verify
   establecido a la ruta completa de un paquete de CA.

Consulte la siguiente URL para más detalles:
https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification

Para remediar esta advertencia de validación de certificado, considere las instrucciones siguientes:

Uso correcto:

Si tiene el certificado en disco en alguna ubicación, cree la instancia de ISAMAppliance con:

ISAMAppliance(…, verify=<ruta al certificado>)

Puede obtenerlo del appliance usando un comando como:

openssl s_client -connect ${HOSTNAME}:${PORT} </dev/null 2>/dev/null | openssl x509 -outform pem >  isamAppliance.pem

Si el certificado ya es de confianza en su entorno Python, cree la instancia de ISAMAppliance con:

ISAMAppliance(…, verify=True)

o establezca la variable de entorno: IBMSECLIB_VERIFY_CONNECTION=true

Si recibe errores sobre el nombre de host que no coincide con el certificado:

Esto podría verse así:

<stack trace>

…

    raise CertificateError("hostname %r doesn't match %r" % (hostname, dnsnames[0]))

urllib3.util.ssl_match_hostname.CertificateError: hostname '192.168.42.111' doesn't match 'appliance.ibm.com'

Asegúrese de que el nombre de host utilizado al crear la instancia de su ISAMAppliance coincida con el Subject Alternative Name del certificado.

Compruébelo con:

openssl x509 -in <archivo-pem-del-cert> -text

Ejemplo:

$ openssl x509 -in /path/to/appliance.pem -text

Certificate:

Data:
    Version: 3 (0x2)
    …
        X509v3 Subject Alternative Name:
            DNS:appliance.ibm.com

…

Lo siguiente generará errores:

ISAMAppliance(host=”192.168.42.111”, lmi_port=443, verify=/path/to/appliance.pem)

ya que el host no coincide con el Subject Alternative Name. En su lugar, use:

ISAMAppliance(host=”appliance.ibm.com”, lmi_port=443, verify=/path/to/appliance.pem)

Versionado

Este paquete utiliza una fecha para el versionado. Por ejemplo: "2017.03.18.0"

Es la fecha en la que se publica el paquete con un número de secuencia al final para manejar los casos en los que haya múltiples publicaciones en un mismo día (se espera que sea poco común).

Características

Este paquete de Python proporciona las siguientes características:

1. Fácil de usar: los detalles de realizar una llamada REST se gestionan dentro de una clase de appliance.
2. Disposición intuitiva del paquete de código y nombres que se corresponden con la interfaz GUI del appliance.
3. Idempotencia: las funciones que realizan actualizaciones consultarán al appliance para comparar los datos proporcionados y ver si se requiere un cambio antes de realizar el cambio real.
4. Los pasos de Commit y Deploy se proporcionan por separado para permitir flexibilidad al invocarlos.
5. Se incluye registro estándar (logging), con la capacidad de establecer niveles de registro.
6. Los parámetros de las funciones utilizarán valores predeterminados estándar siempre que sea posible.
7. Se proporciona una opción force para anular la idempotencia.
8. Se proporcionan funciones compare: toman la salida JSON y proporcionan una comparación significativa.

Formato de datos devueltos por las funciones

{
    rc:       <0 para éxito, mayor para errores>
    changed:  <True o False>
    warnings: <Lista de cadenas con advertencias - p. ej. versión incompatible>
    data:     <Datos JSON devueltos por la API REST del appliance que llamó a la función>
}

Nota: se prefiere devolver advertencias en lugar de enviar un rc distinto de cero.

Organización del código

Clases de Appliance

Una clase abstracta ibmappliance se extiende para crear una clase para cada appliance compatible aquí. Actualmente, los appliances ISAM e ISDS.

Clases de Usuario

Un User abstracto se extiende para cada tipo de usuario necesario. Para ISAM, hay un usuario para el acceso al appliance y otro para autenticarse en Web Runtime (Policy Server).

Disposición de los paquetes de ISAM

Hay cuatro paquetes principales de ISAM: base, web, aac y fed. web contiene todos los componentes necesarios para configurar la funcionalidad web, incluidos el LDAP integrado, el runtime y las características que se activan como parte del módulo wga. aac contiene las características activadas como parte del módulo mga y fed las de federation. base contiene todo lo demás, incluidos aac y fed, runtime y Audit Configuration (estos son comunes a aac y fed y, por lo tanto, están en base).

Nombres de paquetes y archivos

Los nombres de los paquetes y archivos se crearon con la siguiente intención:

1. Mantener nombres que coincidan con lo que hay en la interfaz GUI (LMI para el appliance ISAM).
2. Cada archivo debe contener solo una de cada tipo de función (ver lista abajo), es decir, solo un add().
3. Agrupar funciones relacionadas (una de cada tipo) en un archivo.
4. La URI para las llamadas a la API REST dentro de un archivo será la misma y gestionará una "característica" del appliance.

Utilidades

Contiene funciones misceláneas que son genéricas e independientes de cualquier IBM Appliance, p. ej. json_compare().

Tipos de funciones