IBM Sample Code

Ce dépôt contient du code Python pour gérer les appliances de sécurité IBM à l'aide de leurs API REST respectives. L'appliance ISAM dispose du code le plus abouti.

Le code pour l'appliance ISDS est en cours de développement.

Le code pour l'appliance ISVG est tout nouveau (testé uniquement avec 10.0.1.0 et versions supérieures).

Prérequis

Python v3.9 ou supérieur est requis pour ce package.

Les packages Python suivants sont requis :

1. requests - pour effectuer les appels API REST
2. PyYAML - pour le bon fonctionnement de l'exemple de code
3. jmespath - est requis pour l'exemple de code

Les packages Python suivants sont facultatifs :

1. cryptography - pour effectuer des actions sur les certificats (utilisé pour l'idempotence dans management_ssl_certificate)
2. python-dateutil - utilitaires de date (utilisés pour l'idempotence dans management_ssl_certificate)

Les appliances doivent avoir une adresse IP définie pour leur LMI. Cela peut impliquer que les appliances aient effectué leur configuration initiale avec l'acceptation de la licence.

Vérification TLS activée (v2024.4.5)

Ces modifications sont rétrocompatibles. Par défaut, nous ne vérifions pas, mais nous affichons toujours un avis :

Certificate verification has been disabled. Python is NOT verifying the SSL
certificate of the host appliance and InsecureRequestWarning messages are

being suppressed for the following host:

https://{0}:{1}

To use certificate verification:

1. When the certificate is trusted by your Python environment:
   Instantiate all instances of ISAMAppliance with verify=True or set
   the environment variable IBMSECLIB_VERIFY_CONNECTION=True.
2. When the certificate is not already trusted in your Python environment:
   Instantiate all instances of ISAMAppliance with the verify parameter
   set to the fully qualified path to a CA bundle.

See the following URL for more details:
https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification

Pour remédier à cet avertissement de validation de certificat, suivez les instructions ci-dessous :

Utilisation correcte :

Si vous avez le certificat sur le disque quelque part, instanciez le ISAMAppliance avec :

ISAMAppliance(…, verify=<path to cert>)

Vous pouvez l'obtenir depuis l'appliance à l'aide d'une commande comme :

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

Si le certificat est déjà approuvé dans votre environnement Python, instanciez le ISAMAppliance avec :

ISAMAppliance(…, verify=True)

ou définissez la variable d'environnement : IBMSECLIB_VERIFY_CONNECTION=true

Si vous recevez des erreurs concernant le nom d'hôte ne correspondant pas au certificat :

Cela peut ressembler à ceci :

<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'

Assurez-vous que le nom d'hôte utilisé lors de l'instanciation de votre ISAMAppliance correspond à la Subject Alternative Name du certificat.

Vérifiez avec :

openssl x509 -in <cert-pem-file> -text

Exemple :

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

Certificate:

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

…

Ce qui suit générera des erreurs :

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

car le nom d'hôte ne correspond pas à la Subject Alternative Name. À la place, utilisez :

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

Gestion des versions

Ce package utilise une date pour la gestion des versions. Par exemple : "2017.03.18.0"

Il s'agit de la date de sortie du package avec un numéro de séquence à la fin pour gérer les cas où il y a plusieurs versions le même jour (ce qui devrait être rare).

Fonctionnalités

Ce package Python fournit les fonctionnalités suivantes :

1. Facile à utiliser - les détails de l'exécution d'un appel REST sont gérés dans une classe d'appliance
2. Disposition intuitive du package de code et des noms correspondant à l'interface GUI de l'appliance
3. Idempotence - les fonctions qui effectuent des mises à jour interrogent l'appliance pour comparer les données fournies afin de voir si un changement est nécessaire avant d'effectuer le changement réel.
4. Les étapes Commit et Deploy sont fournies séparément pour offrir une certaine flexibilité dans leur invocation.
5. La journalisation standard est incluse - avec la possibilité de définir les niveaux de journalisation.
6. Les paramètres des fonctions utiliseront des valeurs par défaut standard dans la mesure du possible.
7. Une option force est fournie pour outrepasser l'idempotence.
8. Des fonctions de comparaison sont fournies - elles prennent la sortie JSON et fournissent une comparaison pertinente.

Format des données retournées par les fonctions

{
    rc:       <0 for success, higher for errors>
    changed:  <True or False>
    warnings: <List of strings with warnings - e.g. incompatible version>
    data:     <JSON data returned by appliance REST API that the function called>
}

Remarque : il est préférable de retourner des avertissements plutôt que de renvoyer un code rc non nul.

Organisation du code

Classes d'appliance

Une classe abstraite ibmappliance est étendue pour créer une classe pour chaque appliance prise en charge ici. Il s'agit actuellement des appliances ISAM et ISDS.

Classes d'utilisateur

Une classe abstraite User est étendue pour chaque type d'utilisateur nécessaire. Pour ISAM, il s'agit d'un utilisateur pour l'accès à l'appliance et d'un autre pour l'authentification à Web Runtime (Policy Server).

Structure des packages ISAM

Il existe quatre packages ISAM principaux - base, web, aac et fed. web contient tous les composants nécessaires à la configuration des fonctionnalités web, y compris ldap intégré, runtime et les fonctionnalités activées dans le cadre du module wga. aac contient les fonctionnalités activées dans le cadre du module mga et fed celles de federation. base contient tout le reste - y compris aac et fed runtime et Audit Configuration (ces éléments sont communs à aac et fed et se trouvent donc dans base).

Noms de packages et de fichiers

Les noms de packages et de fichiers ont été créés avec l'intention suivante :

1. Conserver des noms qui correspondent à ce qui se trouve dans l'interface graphique (LMI pour l'appliance ISAM).
2. Chaque fichier doit contenir un seul de chaque type de fonction (voir la liste ci-dessous) - c'est-à-dire un seul add().
3. Regrouper les fonctions liées - une de chaque type - dans un fichier.
4. L'URI des appels API REST d'un fichier sera le même et gérera une « fonctionnalité » de l'appliance.

Utilitaires

Contient diverses fonctions génériques et indépendantes de toute appliance IBM, par exemple json_compare().

Types de fonctions