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 y y, por lo tanto, están en ).

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

get_all()

Esta función normalmente devolverá todos los objetos relacionados con esa característica.

get()

Esta función devuelve los detalles de un objeto en particular.

set()

Esta función determinará si el objeto a manipular existe; si no existe, llamará a add(); de lo contrario, llamará a update(). En los casos en que no haya update(), comparará para ver si hay una diferencia entre el valor existente en el appliance y el que se está estableciendo mediante la función; si son diferentes, hará delete() del objeto antes de llamar a add().

add()

Comprueba si el objeto ya existe; si es así, lo omite; de lo contrario, lo añade.

update()

Comprueba si el objeto ya existe; si es así, comprueba si la actualización es necesaria antes de realizar un cambio; de lo contrario, no hace nada.

delete()

Comprueba si el objeto ya existe; si es así, lo elimina; de lo contrario, no hace nada.

import_<>()

"import" es una palabra reservada, por lo que hay un sufijo que indica qué importar (p. ej. archivo o clave). Esto comprobará si el objeto existe antes de importarlo.

export_<>()

Export comprobará si existe antes de exportarlo; al exportar a un archivo, si el archivo ya existe, no lo volverá a exportar. Export

compare()

Compare toma la salida JSON de las funciones get_all() y la compara. Eliminará de la salida JSON los datos que sean únicos de cada appliance (p. ej. valores UUID). El valor deleted_keys devuelto enumera las claves JSON que se eliminaron antes de la comparación.

Parámetros de las funciones

Objeto Appliance

Cree un objeto appliance y páselo a la función. El appliance y el objeto User necesarios son clases que permiten extensiones futuras, como la autenticación mediante certificado en lugar de usuario/contraseña.

check_mode

El valor predeterminado es False; pase True para retornar y no realizar un cambio. El indicador "changed" se establecerá en True si se detectan cambios.

force

El valor predeterminado es False; pase True para anular la lógica de idempotencia.

Otros parámetros

Los demás parámetros coincidirán textualmente con la documentación de la API REST. La intención era hacer referencia a la documentación de la API REST y no tener que repetirla. Consulte la documentación de la API REST para más detalles.

Cómo añadir y realizar cambios

Por favor, cree un issue en github cuando se descubra un error o haya API REST no cubiertas por este paquete. Proporcione notas detalladas junto con los registros de traza cuando se informe de un error.

Licencia

El contenido de este repositorio es de código abierto bajo la licencia Apache 2.0.

Copyright 2017 International Business Machines

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.