**文档**：https://thehive-project.github.io/TheHive4py **源代码**：https://github.com/TheHive-Project/TheHive4py # 简介 **最新动态：** 这是一个为 TheHive 5 量身重建的 `thehive4py` 版本。敬请期待，我们还有更多令人兴奋的更新！ 欢迎使用 `thehive4py`，这是一个旨在简化与 TheHive 5.x 交互的 Python 库。无论您是网络安全爱好者，还是希望将 TheHive 集成到 Python 项目中的开发者，本库都能为您提供全面支持。 请自由探索该库的功能，并为它的发展贡献力量。我们感谢您对使 Python 中的 TheHive 集成更加便捷高效的支持。 # 快速入门 ## 系统要求 `thehive4py` 兼容所有当前受支持的 Python 版本。您可以[点击此处](https://devguide.python.org/versions/)查看官方版本支持与生命周期状态。 ## 安装 `thehive4py` 可通过 pip 安装，如下所示： ``` pip install thehive4py ``` ## 创建客户端 您可以通过两种不同的方式创建 `thehive4py` 客户端实例，具体取决于您的认证方式： **方法 1：用户名/密码认证** 如果您使用用户名和密码进行认证，可以按如下方式创建客户端： ``` from thehive4py import TheHiveApi hive = TheHiveApi( url="https://thehive.example.com", username="analyst@example.com", password="supersecret", ) ``` **方法 2：API 密钥认证** 或者，如果您更倾向于使用 API 密钥进行认证，请使用以下方法： ``` from thehive4py import TheHiveApi hive = TheHiveApi( url="https://thehive.example.com", apikey="h1v3b33", ) ``` 请选择最适合您需求和安全要求的认证方式。 ## 创建告警 要创建一个新告警，您可以使用客户端的 `alert.create` 方法，并传入以下必需字段： - `type`：告警类型。 - `source`：告警来源。 - `sourceRef`：告警的唯一引用。 - `title`：描述性标题。 - `description`：描述告警的附加信息。 以下示例演示了如何使用这些必需字段创建新告警： ``` my_alert = hive.alert.create( alert={ "type": "my-alert", "source": "my-source", "sourceRef": "my-reference", "title": "My test alert", "description": "Just a description", } ) ``` 上述代码片段将创建一个仅包含必需字段的新告警，并将返回的告警对象存储在 `my_alert` 变量中。 ## 添加告警可观测对象 为了让告警更具信息量和可操作性，您可以为其添加可观测对象。可观测对象是与告警相关的特定数据。在本例中，我们将为之前的告警添加两个可观测对象：一个 IP 地址 `93.184.216.34` 和一个域名 `example.com`。 **方法 1：逐个添加可观测对象** 您可以使用 `alert.create_observable` 方法将可观测对象添加到现有告警，如下所示： ``` hive.alert.create_observable( alert_id=my_alert["_id"], observable={"dataType": "ip", "data": "93.184.216.34"}, ) hive.alert.create_observable( alert_id=my_alert["_id"], observable={"dataType": "domain", "data": "example.com"}, ) ``` 此方法适用于在告警创建后添加可观测对象。 **方法 2：在创建告警时添加可观测对象** 或者，如果您在创建告警时已知这些可观测对象，可以直接在告警创建方法中使用 `observables` 字段，以更简洁的方式完成： ``` my_alert = hive.alert.create( alert={ "type": "my-alert", "source": "my-source", "sourceRef": "my-reference", "title": "My test alert", "description": "Just a description", "observables": [ {"dataType": "ip", "data": "93.184.216.34"}, {"dataType": "domain", "data": "example.com"}, ], } ) ``` 这种方法不仅能减少额外的网络请求，还能降低出错概率，使代码更高效、更可靠。 通过将可观测对象纳入告警，您为进一步的分析和事件响应提供了有价值的信息和上下文。 ## 更新告警 如果您需要向现有告警添加或修改字段，可以轻松使用客户端的 `alert.update` 方法。在此示例中，我们将添加标签 `my-tag` 并修改告警标题： ``` hive.alert.update( alert_id=my_alert["_id"], fields={ "title": "My updated alert", "tags": ["my-tag"], }, ) ``` 上述代码会更新告警标题并向 TheHive 添加新标签。 需要注意的是，Python 代码中的 `my_alert` 对象不会自动反映这些更改。`thehive4py` 不提供对象关系映射功能。要获取修改后的最新告警信息，您需要重新获取： ``` my_alert = hive.alert.get(alert_id=my_alert["_id"]) ``` 完成此请求后，`my_alert["title"]` 将变为 `"My Updated Alert"`，`my_alert["tags"]` 将包含 `"my-tag"`。这样可以确保您的 Python 代码拥有最新的信息。 ## 创建案件 在 `thehive4py` 中，您有两种方式创建案件：要么将现有告警提升为案件，要么创建一个全新的空案件。 **方法 1：将现有告警提升为案件** 您可以使用 `alert.promote_to_case` 方法将现有告警转换为案件，并将其与该告警关联： ``` my_case = hive.alert.promote_to_case(alert_id=my_alert["_id"]) ``` 此方法会基于现有告警创建一个案件，并自动将告警分配给该案件。告警中的所有可观测对象也会被复制为案件可观测对象。 **方法 2：创建空案件** 或者，您可以使用 `case.create` 方法创建一个全新的空案件： ``` my_case = hive.case.create( case={"title": "My First Case", "description": "Just a description"} ) ``` 此方法会创建一个没有任何告警或可观测对象的新案件。 若之后需要将现有告警合并到新案件中，可以使用 `alert.merge_into_case` 方法： ``` hive.alert.merge_into_case(alert_id=my_alert["_id"], case_id=my_case["_id"]) ``` 通过选择适合您工作流程的方法，您可以高效地在 TheHive 中管理案件和告警。 ## 查询案件可观测对象 要从案件中检索可观测对象，可以使用 `thehive4py` 提供的 `case.find_observables` 方法。该方法支持多种过滤和查询选项，让您能够检索特定或全部与案件关联的可观测对象。 ### 检索案件的所有可观测对象 要检索案件的所有可观测对象，请使用以下代码： ``` case_observables = hive.case.find_observables(case_id=my_case["_id"]) ``` ### 检索特定可观测对象 如果您希望基于特定条件检索可观测对象，可以利用 TheHive 强大的查询功能。更多细节请参考官方 [查询 API 文档][query-api-docs]。 以下是如何检索 IP 类型可观测对象的示例： ``` ip_observable = hive.case.find_observables( case_id=my_case["_id"], filters=Eq("dataType", "ip") & Like("data", "93.184.216.34") ) ``` 在此示例中，我们使用 `Eq`、`Like` 以及 `&` 运算符来指定查询条件。您也可以使用基于字典的方法进行过滤： ``` ip_observable = hive.case.find_observables( case_id=my_case["_id"], filters={ "_and": [ {"_field": "dataType", "_value": "ip"}, {"_like": {"_field": "data", "_value": "93.184.216.34"}}, ] } ) ``` 基于字典的方法可行，但我们推荐使用内置的过滤类来构建查询表达式，因其更易用。 目前，过滤类支持以下运算符： - `&`：用于查询 API 的 `_and` 构造。 - `|`：用于查询 API 的 `_or` 构造。 - `~`：用于查询 API 的 `_not` 构造。 这些运算符提供了一种便捷且直观的方式来构建复杂查询。 # 开发 ## 设置虚拟环境（可选） 强烈建议使用虚拟环境进行干净且隔离的 Python 开发。它可以帮助您管理项目特定依赖项，并避免与其他项目产生冲突。如果您不了解虚拟环境的使用方法，请[点击此处](https://docs.python.org/3/library/venv.html#module-venv)了解更多。 ## 安装开发包 如果您是首次向 GitHub 项目贡献代码，请先熟悉[贡献指南](https://docs.github.com/en/get-started/quickstart/contributing-to-projects)。 导航到克隆的仓库目录，并使用 pip 安装带有开发依赖的包： ``` pip install -e .[dev] ``` 此命令将以可编辑模式（`-e`）安装该包，并包含额外的开发依赖项。 现在，您已在该开发环境中安装 `thehive4py` 包，准备好进行贡献。 ## 贡献 要向 `thehive4py` 贡献代码，请遵循以下步骤： 1. **创建问题**：首先创建一个问题，描述您希望解决或添加的功能。这有助于讨论和协调与其他贡献者的工作。 2. **创建分支**：一旦问题确定，请为其创建一个分支。命名约定为：`-title-of-branch`。例如，如果您正在处理问题 #1 并更新 README，请将分支命名为 `1-update-readme`。 ## 在推送更改前运行 CI 检查 该项目使用 [nox] 库来定义和运行自动化开发脚本。 为确保更改的完整性并维护代码质量，您可以使用本地 `noxfile.py` 提供的会话。 例如，您可以在推送更改到仓库前运行 CI 检查： ``` nox ``` 这将触发除测试之外的所有 CI 检查（默认情况下 `noxfile.py` 已配置为如此）。 要单独运行某个检查，可以列出所有可用的会话： ``` nox --list ``` **方法 2：使用预提交钩子（实验性）** 为了更流畅的工作流程，您可以安装该仓库提供的预提交钩子。这些钩子将在每次提交前自动执行检查。安装方法如下： ``` pre-commit install ``` 启用预提交钩子后，您的将在每次提交时自动验证是否符合编码标准和其他质量检查。这有助于在早期发现问题并确保贡献流程顺畅。 ## 测试 `thehive4py` 主要依赖集成测试，这些测试针对真实的 TheHive 5.x 实例执行，以确保库在接近真实使用环境中的功能正确性。 ### 测试要求 由于测试套件依赖本地运行的 TheHive 5.x 容器，因此必须安装本地 Docker 引擎。 如果您不熟悉 Docker，请查阅[官方文档][get-docker]。 ### 测试设置 测试套件使用官方的 [thehive-image] 创建本地名为 `thehive4py-integration-tester` 的容器，该容器将作为唯一标识符。 该容器会随机暴露 TheHive 端口，以避免与其他容器冲突。 测试套件可以通过查询容器信息来识别该随机端口。 一旦 TheHive 可用，套件将初始化实例并设置测试所需的内容（例如测试用户、组织等）。 请注意，由于初始设置，首次运行测试可能需要较长时间等待所有服务启动。后续运行的启动时间会显著缩短。 ### 本地测试执行 要本地执行整个测试套件，可以使用 `noxfile.py` 提供的 `test` 会话，如下所示： ``` nox --session=test ``` 或 ``` nox -s test ``` 简写形式。 请注意，以上命令将执行完整的测试套件，可能需要几分钟才能完成。 如果只想执行部分测试套件，可以通过在会话后添加额外参数来实现，例如： ``` nox -s test -- tests/test_observable_endpoint.py -v ``` 该 nox 命令会将 `--` 之后的参数传递给底层的 `pytest` 命令。

标签：API 客户端, CIDR查询, Discord 社区, PyPI, Python, Python API 客户端, Python SDK, REST API, SOAR, TheHive, TheHive4py, TheHive 项目, 代码覆盖率, 威胁情报, 安全运营, 开发者工具, 开源客户端, 扫描框架, 文档站点, 无后门, 逆向工具