IBM-Beispielcode

Dieses Repository enthält Python-Code zur Verwaltung von IBM Security Appliances über ihre jeweiligen REST-APIs. Die ISAM-Appliance hat den ausgereiftesten Code.

Code für die ISDS-Appliance befindet sich in der Entwicklung.

Code für die ISVG-Appliance ist brandneu (nur mit 10.0.1.0 und höher getestet).

Anforderungen

Für dieses Paket ist Python v3.9 und höher erforderlich.

Die folgenden Python-Pakete sind erforderlich:

1. requests – für REST-API-Aufrufe
2. PyYAML – damit der Beispielcode funktioniert
3. jmespath – ist für den Beispielcode erforderlich

Die folgenden Python-Pakete sind optional:

1. cryptography – zum Ausführen von Aktionen an Zertifikaten (wird für die Idempotenz in management_ssl_certificate verwendet)
2. python-dateutil – Datumsdienstprogramme (wird für die Idempotenz in management_ssl_certificate verwendet)

Appliances müssen für ihr LMI eine IP-Adresse definiert haben. Dies kann bedeuten, dass Appliances ihre Erstkonfiguration mit Lizenzakzeptanz abgeschlossen haben.

TLS-Verifizierung aktiviert (v2024.4.5)

Diese Änderungen sind abwärtskompatibel. Standardmäßig wird nicht verifiziert, aber es wird immer ein Hinweis angezeigt:

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

Um diese Zertifikatsvalidierungswarnung zu beheben, beachten Sie die folgenden Anweisungen:

Korrekte Verwendung:

Wenn Sie das Zertifikat irgendwo auf der Festplatte haben, instanziieren Sie die ISAMAppliance mit:

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

Sie können dies von der Appliance mit einem Befehl wie dem folgenden abrufen:

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

Wenn das Zertifikat in Ihrer Python-Umgebung bereits vertrauenswürdig ist, instanziieren Sie die ISAMAppliance mit:

ISAMAppliance(…, verify=True)

oder setzen Sie die Umgebungsvariable: IBMSECLIB_VERIFY_CONNECTION=true

Wenn Sie Fehler erhalten, dass der Hostname nicht mit dem Zertifikat übereinstimmt:

Das könnte so aussehen:

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

Stellen Sie sicher, dass der Hostname, der beim Instanziieren Ihrer ISAMAppliance verwendet wird, mit dem Subject Alternative Name des Zertifikats übereinstimmt.

Überprüfen Sie mit:

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

Beispiel:

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

Certificate:

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

…

Das Folgende erzeugt Fehler:

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

da der Host nicht mit dem Subject Alternative Name übereinstimmt. Verwenden Sie stattdessen:

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

Versionierung

Dieses Paket verwendet ein Datum für die Versionierung. Zum Beispiel: "2017.03.18.0"

Es ist das Datum, an dem das Paket veröffentlicht wird, mit einer Sequenznummer am Ende, um zu behandeln, wenn es mehrere Veröffentlichungen an einem Tag gibt (was voraussichtlich ungewöhnlich ist).

Funktionen

Dieses Python-Paket bietet die folgenden Funktionen:

1. Einfach zu bedienen – die Einzelheiten eines REST-Aufrufs werden innerhalb einer Appliance-Klasse behandelt
2. Intuitives Layout des Codepakets und Benennung, die der GUI-Oberfläche der Appliance entspricht
3. Idempotenz – Funktionen, die Aktualisierungen vornehmen, fragen die Appliance ab, um die angegebenen Daten zu vergleichen und zu sehen, ob eine Änderung erforderlich ist, bevor die eigentliche Änderung vorgenommen wird.
4. Commit- und Deploy-Schritte werden separat bereitgestellt, um Flexibilität bei deren Aufruf zu ermöglichen
5. Standardmäßiges Logging ist enthalten – mit der Möglichkeit, Logging-Stufen festzulegen.
6. Parameter für Funktionen verwenden, wo immer möglich, Standardwerte.
7. Eine Force-Option wird bereitgestellt, um die Idempotenz zu überschreiben.
8. Vergleichsfunktionen werden bereitgestellt – sie nehmen JSON-Ausgabe und liefern einen aussagekräftigen Vergleich.

Format der Funktionsdatenrückgabe

{
    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>
}

Hinweis: Es ist bevorzugt, Warnungen zurückzugeben, anstatt einen Nicht-Null-rc zurückzusenden.

Organisation des Codes

Appliance-Klassen

Eine abstrakte ibmappliance-Klasse wird erweitert, um eine Klasse für jede hier unterstützte Appliance zu erstellen. Derzeit sind das ISAM- und ISDS-Appliances.

Benutzerklassen

Ein abstrakter User wird für jede benötigte Benutzerart erweitert. Für ISAM gibt es einen Benutzer für den Appliance-Zugriff und einen anderen für die Authentifizierung bei Web Runtime (Policy Server).

Layout der ISAM-Pakete

Es gibt vier primäre ISAM-Pakete – base, web, aac und fed. web enthält alle Komponenten, die für die Einrichtung der Web-Funktionalität benötigt werden, einschließlich eingebettetem LDAP, Runtime und Funktionen, die als Teil des wga-Moduls aktiviert werden. aac enthält Funktionen, die als Teil des mga-Moduls aktiviert werden, und fed die der federation. base enthält alles andere – einschließlich aac und fed runtime und Audit Configuration (diese sind aac und fed gemeinsam und befinden sich daher in base).

Paket- und Dateinamen

Die Paket- und Dateinamen wurden mit der folgenden Absicht erstellt:

1. Namen beibehalten, die mit der GUI-Oberfläche übereinstimmen (LMI für die ISAM-Appliance).
2. Jede Datei sollte nur eine Funktion jedes Typs enthalten (siehe Liste unten) – d. h. nur ein add().
3. Verwandte Funktionen gruppieren – eine von jedem Typ – in einer Datei.
4. Der URI für die REST-API-Aufrufe innerhalb einer Datei ist derselbe und verwaltet ein "Feature" der Appliance.

Dienstprogramme

Enthält verschiedene Funktionen, die generisch und unabhängig von einer IBM Appliance sind, z. B. json_compare().

Funktionstypen