Пример кода 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 и , и поэтому находятся в ).

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

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

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

Утилиты

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

Типы функций

get_all()

Эта функция обычно возвращает все объекты, связанные с данной функцией.

get()

Эта функция возвращает сведения об одном конкретном объекте.

set()

Эта функция определяет, существует ли объект, которым нужно управлять; если нет, она вызывает add(), в противном случае — update(). В случаях, когда update() отсутствует, она сравнивает существующее значение на устройстве со значением, устанавливаемым через функцию; если они различаются, она вызывает delete() для объекта перед вызовом add().

add()

Проверяет, существует ли объект; если да, пропускает, в противном случае добавляет его.

update()

Проверяет, существует ли объект; если да, проверяет, нужно ли обновление, прежде чем вносить изменения, в противном случае ничего не делает.

delete()

Проверяет, существует ли объект; если да, удаляет, в противном случае ничего не делает.

import_<>()

«import» является зарезервированным словом, поэтому используется суффикс, указывающий, что импортировать (например, file или key). Эта функция проверяет, существует ли объект, перед его импортом.

export_<>()

Export проверяет, существует ли объект, перед его экспортом; при экспорте в файл, если файл уже существует, повторный экспорт не выполняется. Экспорт

compare()

Compare принимает JSON-вывод функций get_all() и сравнивает его. Она удаляет из JSON данные, которые уникальны для каждого устройства (например, значения UUID). Возвращаемое значение deleted_keys содержит список JSON-ключей, которые были удалены перед сравнением.

Параметры функций

Объект Appliance

Создайте объект устройства и передайте его в функцию. Объекты Appliance и User, которые необходимы, являются классами, что допускает будущие расширения, например аутентификацию с использованием сертификата вместо имени пользователя/пароля.

check_mode

Значение по умолчанию — False; передайте True, чтобы функция вернулась, не внося изменений. Флаг "changed" будет установлен в True, если изменения обнаружены.

force

Значение по умолчанию — False; передайте True, чтобы переопределить логику идемпотентности.

Другие параметры

Остальные параметры будут точно соответствовать документации REST API. Предполагалось ссылаться на документацию REST API, а не повторять её. Пожалуйста, обращайтесь к документации REST API за подробностями.

Добавление и внесение изменений

Пожалуйста, создавайте issue на GitHub при обнаружении ошибки или если существуют REST API, не охваченные этим пакетом. При сообщении об ошибке предоставляйте подробные описания вместе с журналами трассировки.

Лицензия

Содержимое этого репозитория является открытым исходным кодом на условиях лицензии 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.