Пример кода IBM

Этот репозиторий содержит код Python для управления устройствами IBM Security с использованием их соответствующих REST API. Наиболее зрелым является код для устройства ISAM.

Код для устройства ISDS находится в разработке.

Код для устройства ISVG является совершенно новым (протестирован только с версией 10.0.1.0 и выше).

Требования

Для этого пакета требуется Python v3.9 и выше.

Требуются следующие пакеты Python:

1. requests - для выполнения вызовов REST API
2. PyYAML - для работы примера кода
3. jmespath - требуется для примеров кода

Следующие пакеты Python являются необязательными:

1. cryptography - для выполнения действий с сертификатами (используется для идемпотентности в management_ssl_certificate)
2. python-dateutil - утилиты для работы с датами (используется для идемпотентности в management_ssl_certificate)

Устройства должны иметь определённый IP-адрес для своего LMI. Это может означать, что устройства прошли первоначальную настройку с принятием лицензии.

Включена проверка TLS (v2024.4.5)

Эти изменения обратно совместимы. По умолчанию мы не проверяем сертификаты, но всегда отображаем уведомление:

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

Чтобы устранить это предупреждение о проверке сертификата, следуйте приведённым ниже инструкциям:

Правильное использование:

Если у вас есть сертификат где-то на диске, создайте экземпляр ISAMAppliance с помощью:

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

Вы можете получить его с устройства с помощью команды вида:

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

Если сертификат уже является доверенным в вашем окружении Python, создайте экземпляр ISAMAppliance с помощью:

ISAMAppliance(…, verify=True)

или установите переменную окружения: IBMSECLIB_VERIFY_CONNECTION=true

Если вы получаете ошибки о несоответствии имени хоста сертификату:

Это может выглядеть так:

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

Убедитесь, что имя хоста, используемое при создании экземпляра ISAMAppliance, соответствует Subject Alternative Name сертификата.

Проверьте с помощью:

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

Пример:

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

Certificate:

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

…

Следующий код вызовет ошибки:

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

поскольку имя хоста не соответствует Subject Alternative Name. Вместо этого используйте:

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

Версионирование

Этот пакет использует дату для версионирования. Например: "2017.03.18.0"

Это дата выпуска пакета с порядковым номером в конце для случаев, когда в один день выходит несколько релизов (ожидается, что это редко).

Возможности

Этот пакет Python предоставляет следующие возможности:

1. Простота использования - детали выполнения REST-вызова обрабатываются внутри класса устройства
2. Интуитивно понятная структура пакета кода, а названия соответствуют графическому интерфейсу устройства
3. Идемпотентность - функции, вносящие изменения, запрашивают устройство для сравнения предоставленных данных, чтобы определить, требуется ли изменение перед фактическим изменением.
4. Шаги Commit и Deploy предоставляются отдельно, чтобы обеспечить гибкость при их вызове
5. Включено стандартное журналирование - с возможностью настройки уровней журналирования.
6. Параметры функций используют стандартные значения по умолчанию везде, где это возможно.
7. Предусмотрена опция force для переопределения идемпотентности.
8. Предусмотрены функции сравнения - принимают JSON-вывод и предоставляют осмысленное сравнение.

Формат возвращаемых данных функции

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

Примечание: предпочтительно возвращать предупреждения, а не отправлять ненулевой код возврата.

Организация кода

Классы устройств

Абстрактный класс ibmappliance расширяется для создания класса для каждого поддерживаемого здесь устройства. В настоящее время это устройства ISAM и ISDS.

Классы пользователей

Абстрактный класс User расширяется для каждого требуемого типа пользователя. Для ISAM это пользователь для доступа к устройству и ещё один для аутентификации в Web Runtime (Policy Server).

Структура пакетов ISAM

Существует четыре основных пакета ISAM - base, web, aac и fed. web содержит все компоненты, необходимые для настройки веб-функциональности, включая встроенный LDAP, среду выполнения (runtime) и функции, активируемые в рамках модуля wga. aac содержит функции, активируемые в рамках модуля mga, а fed - функции федерации. base содержит всё остальное, включая runtime для aac и fed и Audit Configuration (они общие для aac и fed, и поэтому находятся в base).

Имена пакетов и файлов

Имена пакетов и файлов были созданы со следующей целью:

1. Сохранять имена, соответствующие тому, что есть в графическом интерфейсе (LMI для устройства ISAM).
2. Каждый файл должен содержать только по одной функции каждого типа (см. список ниже) - т.е. только один add().
3. Группировать связанные функции - по одной каждого типа - в файле.
4. URI для вызовов REST API в файле будет одинаковым и управляет «функцией» (feature) устройства.

Утилиты

Содержит различные функции, которые являются общими и независимыми от любого устройства IBM, например json_compare().

Типы функций