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 à et et se trouvent donc dans ).

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

get_all()

Cette fonction retourne généralement tous les objets liés à cette fonctionnalité.

get()

Cette fonction retourne les détails d'un objet particulier.

set()

Cette fonction détermine si l'objet à manipuler existe ; si ce n'est pas le cas, elle appelle add(), sinon elle appelle update(). Dans les cas où il n'y a pas de update(), elle compare pour voir s'il y a une différence entre la valeur existante sur l'appliance et celle définie via la fonction - si elle est différente, elle appelle delete() sur l'objet avant d'appeler add().

add()

Vérifie si l'objet existe déjà - si c'est le cas, l'ignore, sinon l'ajoute.

update()

Vérifie si l'objet existe déjà - si c'est le cas, vérifie si une mise à jour est nécessaire avant d'apporter une modification, sinon ne fait rien.

delete()

Vérifie si l'objet existe déjà - si c'est le cas, le supprime, sinon ne fait rien.

import_<>()

« import » est un mot réservé, il y a donc un suffixe pour indiquer quoi importer (par exemple fichier ou clé). Cette fonction vérifie si l'objet existe avant de l'importer.

export_<>()

Export vérifie si l'objet existe avant de l'exporter - lors de l'exportation vers un fichier, si le fichier existe déjà, il ne sera pas réexporté. Export

compare()

Compare prend la sortie JSON des fonctions get_all() et la compare. Il supprime des données JSON les éléments uniques à chaque appliance (par exemple les valeurs UUID). La valeur deleted_keys retournée répertorie les clés JSON qui ont été supprimées avant la comparaison.

Paramètres des fonctions

Objet appliance

Créez un objet appliance et passez-le à la fonction. L'appliance et l'objet User nécessaires sont des classes permettant de futures extensions comme l'authentification par certificat au lieu du nom d'utilisateur/mot de passe.

check_mode

Ce paramètre est par défaut à False ; passez True pour retourner et ne pas effectuer de changement. L'indicateur « changed » sera défini à True si des changements sont détectés.

force

Ce paramètre est par défaut à False ; passez True pour outrepasser la logique d'idempotence.

Autres paramètres

Les autres paramètres correspondent mot pour mot à la documentation de l'API REST. L'intention était de référencer la documentation de l'API REST et de ne pas avoir à la répéter. Veuillez consulter la documentation de l'API REST pour plus de détails.

Ajouter et apporter des modifications

Veuillez ouvrir un problème (issue) sur github lorsqu'un bug est découvert ou que des API REST ne sont pas couvertes par ce package. Fournissez des notes détaillées accompagnées des journaux de trace lors du signalement d'un bug.

Licence

Le contenu de ce dépôt est open-source sous licence 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.