IBM 示例代码

此仓库包含用于通过各自 REST API 管理 IBM 安全设备的 Python 代码。 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 中的幂等性）

设备需要为其 LMI 定义一个 IP 地址。这可能意味着设备已完成初始设置并接受了许可证。

启用 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)

因为主机与主题备用名称不匹配。

应改用：

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

版本控制

此软件包使用日期进行版本控制。例如："2017.03.18.0"

即软件包发布时的日期，末尾附带一个序号，用于处理同一天内有多个版本发布的情况（预计不常见）。

功能特性

此 Python 软件包提供以下功能特性：

1. 易于使用 - 发起 REST 调用的细节在设备类内处理
2. 代码包布局直观，命名与设备的 GUI 界面相对应
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>
}

注意：更倾向于返回警告，而不是返回非零的 rc。

代码组织

设备类

抽象类 ibmappliance 被扩展为这里支持的每种设备创建一个类。目前支持 ISAM 和 ISDS 设备。

用户类

抽象类 User 被扩展为所需的每种用户类型。对于 ISAM，一个是用于设备访问的用户，另一个是用于向 Web Runtime（策略服务器）进行身份验证的用户。

ISAM 软件包的布局

ISAM 有四个主要软件包 - base、web、aac 和 fed。web 包含设置 Web 功能所需的所有组件，包括嵌入式 ldap、运行时以及作为 wga 模块一部分而激活的功能。aac 包含作为 mga 模块一部分而激活的功能，fed 包含作为 federation 一部分而激活的功能。base 包含所有其他内容 - 包括 aac 和 fed 的 runtime 和 Audit Configuration（这些对 aac 和 是通用的，因此位于 中）。

软件包和文件名

软件包和文件名的创建遵循以下意图：

1. 保持名称与 GUI 界面（ISAM 设备的 LMI）中的内容一致。
2. 每个文件应仅包含每种函数类型中的一个（见下面的列表） - 即仅一个 add()。
3. 将相关函数（每种类型一个）分组放在一个文件中。
4. 文件中 REST API 调用的 URI 将相同，并管理设备的某个"功能"。

工具函数

包含各种通用且独立于任何 IBM 设备的杂项函数，例如 json_compare()。

函数类型

get_all()

此函数通常返回与该功能相关的所有对象。

get()

此函数返回某个特定对象的详细信息。

set()

此函数将判断要操作的对象是否存在，如果不存在则调用 add()，否则调用 update()。在没有 update() 的情况下，它将比较设备上的现有值与通过函数设置的值之间是否存在差异 - 如果有差异，则先 delete() 该对象，然后再调用 add()。

add()

检查对象是否已存在 - 如果存在则跳过，否则添加它。

update()

检查对象是否已存在 - 如果存在，则在更改前检查是否需要更新，否则不做任何操作。

delete()

检查对象是否已存在 - 如果存在则删除，否则不做任何操作。

import_<>()

"import" 是保留字，因此有一个后缀来指明要导入的内容（例如文件或密钥）。此函数在导入前会检查对象是否存在。

export_<>()

导出函数在导出前会检查对象是否存在 - 当导出到文件时，如果文件已存在，则不会重新导出。 导出

compare()

Compare 获取 get_all() 函数的 JSON 输出并进行比较。它会从 JSON 中剥离每个设备独有的数据（例如 UUID 值）。返回的 deleted_keys 值列出了在比较之前被删除的 JSON 键。

函数参数

设备对象

创建设备对象并将其传递给函数。所需的设备对象和用户对象都是类，以便支持未来的扩展，例如使用证书而非用户名/密码进行身份验证。

check_mode

默认值为 False，传入 True 将返回且不进行更改。如果检测到更改，"changed" 标志将设置为 True。

force

默认值为 False，传入 True 将覆盖幂等性逻辑。

其他参数

其他参数将与 REST API 文档完全一致。其意图是直接引用 REST API 文档，而无需重复。详细信息请参阅 REST API 文档。

添加和进行更改

当发现错误或存在此软件包未覆盖的 REST API 时，请在 github 中提交 issue。报告错误时请提供详细说明以及跟踪日志。

许可证

此仓库的内容根据 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.