horizon3ai/h3-cliCLI tool for the Horizon3.ai API
NodeZero MCP Server 现已可用，使您能够运行和管理一个本地托管的 MCP Server，将 NodeZero 的“发现、修复、验证”（Find, Fix, Verify，FFV）能力直接带入您的开发与安全工作流。
h3-cli 是一个便捷的 CLI（命令行界面），用于访问 Horizon3.ai API。Horizon3.ai API 提供对 Horizon3.ai Portal 中可用功能子集的编程访问。概括来说，该 API 允许您：
该 API 可用于多种使用场景，例如定期评估您的环境，或作为持续集成构建流水线的一部分启动渗透测试。
以下步骤将使您快速上手 h3-cli。这些说明已在 macOS 和 Linux 机器上测试通过，通常应适用于任何支持 bash 的 POSIX 兼容 系统。
如果您打算使用 h3-cli 运行_内部_渗透测试，则应将 h3-cli 安装在启动 NodeZero 的同一台 Docker 主机上。
我们假设您已拥有 Horizon3.ai 账户。如果没有，请在 https://portal.horizon3ai.com/ 注册。
访问 H3 API 需要 API 密钥。您可以在 Portal 的 用户 -> 账户设置 菜单下创建。
创建 API 密钥时，必须为其分配一个控制权限的角色。可用角色包括：
如果您正在试用 h3-cli 并希望尝试其全部功能，我们推荐使用 User 角色。之后，您可以根据自己的使用场景改用限制更严格的权限。例如，如果您只想使用 h3-cli 来设置 NodeZero Runner，我们建议使用 NodeZero Runner 角色。
您可以在同一个 h3-cli 安装中轻松管理多个 API 密钥。请在此处了解更多。
❗ 请确保您的 API 密钥安全，因为任何持有您 API 密钥的人都可以访问您的 H3 账户。 可以把 API 密钥看作是将用户名和密码合二为一。任何持有 API 密钥的人都可以从任何地方访问您的账户。h3-cli 会将您的 API 密钥存储在 $HOME/.h3 目录下。该目录在安装时创建，并配置为仅允许您本人读写。
在 shell/终端会话中执行以下 git 命令，将 h3-cli git 仓库 安装到您的机器上。
git clone https://github.com/horizon3ai/h3-cli
这将创建一个新目录 h3-cli，并将仓库内容下载到其中。h3-cli 目录将在您运行 git 命令的目录下创建。您可以将 h3-cli 安装到文件系统的任何位置。
如果没有安装 git，可以从上方菜单中选择以 zip 存档形式下载该仓库，然后将其解压到文件系统的任意位置。
运行以下命令来安装和配置 h3-cli。将 your-api-key-here 替换为您实际的 API 密钥。
cd h3-cli
bash install.sh your-api-key-here
安装脚本将安装依赖项（jq），并在 $HOME/.h3 目录下创建您的默认 h3-cli 配置文件（profile）。您的 API 密钥存储在您的 h3-cli 配置文件中。该目录和配置文件的权限受到限制，除您本人以外的其他用户无法读写。
安装脚本会要求您编辑 shell 配置文件（$HOME/.bash_profile 或 $HOME/.bash_login 或 $HOME/.profile，具体取决于您的操作系统），以设置以下环境变量：
H3_CLI_HOME：h3-cli 使用此环境变量来定位自身及其支持文件。PATH：此环境变量指定搜索 shell 命令时要查找的目录。更新 shell 配置文件后，请重新登录或重启 shell 会话以应用配置更改，然后在命令提示符下运行 h3 来验证能否调用它：
h3
如果一切安装正确，您应该会看到 h3-cli 的帮助文本。
我们每月都会发布 h3-cli 的新功能、bug 修复和其他更新。请使用以下方法之一升级您的安装。
h3 upgrade 命令（推荐）自 2023 年 6 月起，您可以使用 h3 upgrade 命令升级到最新版本的 h3-cli。
如果您收到 ERROR: unrecognized command: "upgrade"，说明您使用的是不支持 upgrade 命令的旧版 h3-cli。请使用以下方法之一升级 h3-cli。
easy_install.sh（如果 h3 upgrade 不可用，推荐使用）请在 h3-cli 的父目录（即包含 h3-cli/ 目录的目录）中运行此命令：
curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash
如果您使用 git clone 安装的仓库，只需运行 git pull 即可安装最新版本。
如果您是以 zip 文件形式下载的仓库，请重新下载 zip 文件并将其解压到相同位置（换句话说，用新的 zip 替换您现有的 h3-cli 安装）。
自 2023 年 6 月起，您可以通过以下命令查看当前 h3-cli 版本：
h3 version
您可以通过以下命令查看完整的版本历史和发布说明：
h3 version -v
运行以下命令以验证与 API 的连通性。
h3 hello-world
您应该会看到如下响应：
{
"data": {
"hello": "world!"
}
}
❗️ 如果您收到错误响应，请通过 Horizon3.ai Portal 中的聊天图标联系 H3。
以下命令将返回您账户中的渗透测试列表，最新的排在最前面。
h3 pentests
要筛选匹配给定搜索词的渗透测试，请将搜索词作为参数传入：
h3 pentests sample
要查询您账户中最新的渗透测试：
h3 pentest
要查询账户中的任意渗透测试，请将渗透测试的 op_id 作为参数传入：
h3 pentest your-op-id-here
除非传入了 op_id 参数，否则多个 h3-cli 命令会默认使用最近的渗透测试。
“op”和“pentest”这两个术语经常互换使用。
运行渗透测试需要指定一个 op 模板。op 模板指定了完整的渗透测试配置，包括范围、攻击参数以及其他（可选的）配置。
Horizon3.ai 为新用户提供了一个名为 Default 1 - Recommended 的默认 op 模板。该模板始终与我们的最新攻击参数和推荐配置保持一致。默认模板不定义范围，在这种情况下，NodeZero 将使用 智能范围（Intelligent Scope） —— NodeZero 的主机子网将提供初始范围，并在渗透测试过程中随着发现更多主机和子网而有机扩展。有关智能范围和其他部署选项的更多信息，请访问我们的产品文档。
对于有经验的用户，可以通过 Horizon3.ai Portal 创建自定义 op 模板。要创建自定义 op 模板，请浏览 运行渗透测试（Run a Pentest） 对话框，直到看到自定义渗透测试配置的选项。可以在不实际运行渗透测试的情况下创建 op 模板。
要使用默认 op 模板和智能范围创建渗透测试：
h3 run-pentest
JSON 响应中包含新创建的渗透测试的详细信息。您可以通过查看 Horizon3.ai Portal 或运行 h3 pentest 来验证渗透测试是否正在创建。
创建渗透测试时有多种指定附加参数的方式。更多信息请参见此处的其他示例。
❗ 等等！您还没完成！
对于_内部_渗透测试（默认类型），在渗透测试开始运行之前还需要执行额外步骤。请参阅下一节中有关下载和运行 NodeZero 的内容，以完成渗透测试的启动。
如果您运行的是_外部_渗透测试，NodeZero 会在
h3 run-pentest期间自动在 H3 云中为您启动，这种情况下您无需额外操作即可启动渗透测试。
❗ ️以下步骤仅适用于_内部_渗透测试；对于_外部_渗透测试，NodeZero 会在 H3 云中自动为您启动。
创建_内部_渗透测试后，您需要在网络内的 Docker 主机上运行我们的 NodeZero 容器。这可以通过在 Docker 主机上运行 NodeZero 启动脚本（NodeZero Launch Script）来完成。
要为最近创建的渗透测试运行 NodeZero 启动脚本：
h3 run-nodezero
您的渗透测试已启动！ 假设所有命令均无错误运行，那么您已成功创建并启动了渗透测试。您应该会看到 NodeZero 启动脚本的输出记录到控制台。该脚本会先验证您的系统是否与 NodeZero 兼容，然后才会下载并运行它。渗透测试完成后，NodeZero 会自动关闭自身。
NodeZero 是一个 Docker 容器。您可以使用 docker ps 查看它。容器名称的格式为 n0-xxxx。
渗透测试结束后，使用以下命令下载一个包含最近创建的渗透测试所有 PDF 和 CSV 报告的 zip 文件：
h3 pentest-reports
上述命令会将 zip 文件下载到当前目录下的 pentest-reports-{op_id}.zip 中。
jq 解析 JSON。 了解如何利用 jq 的强大功能解析 h3-cli 的 JSON 响应。jq 可以解析特定字段、打印响应结构，甚至可以将 JSON 响应转换为 CSV。当您调用 h3 命令时，身份验证会自动无缝完成。您无需显式进行任何身份验证操作。本节介绍其底层机制。
h3-cli 从您的 h3-cli 配置文件（位于 $HOME/.h3 下）中读取 H3_API_KEY 来向 Horizon3.ai API 进行身份验证，并建立（临时的）会话。会话令牌（JWT）会被缓存在 $HOME/.h3 下。会话令牌在 1 小时后过期，届时 h3-cli 会自动重新进行身份验证并重新建立会话。
您可以使用以下命令显式进行身份验证：
h3 auth
上述命令将输出会话令牌（并同时将其缓存在 $HOME/.h3 下）。如果您已有有效（未过期）的会话令牌，h3 auth 将继续使用该会话令牌，而不是重新进行身份验证。
如果您想_强制_ h3-cli 重新进行身份验证，请使用 force 选项：
h3 auth force
您可以在同一个 $HOME/.h3 目录下管理多个 h3-cli 身份验证配置文件。每个 h3-cli 配置文件都有自己的 API 密钥。
首次安装 h3-cli 时，它会自动创建一个名为 default 的初始配置文件，其中包含您在 install.sh 中提供的 API 密钥。
如果您希望使用不同的 API 密钥创建另一个配置文件，请使用以下命令：
h3 save-profile my-profile {api-key}
这将在 $HOME/.h3 下为给定的 {api_key} 创建一个名为 my-profile 的配置文件。要在当前 shell 会话中激活该配置文件，请使用以下命令（注意前导点 .）：
. h3 profile my-profile
您可以使用 h3 profile 验证当前激活的配置文件，并使用 h3 whoami 查看其 API 密钥的详细信息：
h3 profile
h3 whoami
您可以在不同的 h3-cli 配置文件下保存多个 API 密钥，并根据需要使用上述命令在它们之间切换。例如，要切换回 default 配置文件：
. h3 profile default
要查看 $HOME/.h3 目录下的 h3-cli 配置文件列表：
h3 profiles
您可以使用以下命令从 $HOME/.h3 目录中删除配置文件：
h3 delete-profile {name}
这将从本地机器的 $HOME/.h3 目录中删除名为 {name} 的配置文件及其 API 密钥。请注意，它不会撤销该 API 密钥；只是将其从本地机器上删除。您可以通过 Portal 撤销该 API 密钥。
本节包含使用 h3-cli 运行渗透测试的其他示例。
最简单的创建渗透测试的方法是使用默认 op 模板和_智能范围_：
h3 run-pentest
要创建渗透测试并在本地机器上启动 NodeZero（仅适用于_内部_渗透测试）：
h3 run-pentest-and-nodezero
请注意，这仅适用于_内部_渗透测试。对于_外部_渗透测试，NodeZero 会在 h3 run-pentest 期间自动在 H3 云中为您启动。
如果您恰好针对外部渗透测试运行了
h3 run-pentest-and-nodezero，它只会跳过下载和运行 NodeZero 的部分，因为该操作已由 H3 云自动处理。
要使用自定义 op 模板运行渗透测试，请将其作为参数传给 schedule_op_template.graphql：
h3 run-pentest '{"op_template_name":"your-op-template-here"}'
要使用默认 op 模板运行渗透测试，但为其指定您选择的名称，请使用可选的 op_name 参数：
h3 run-pentest '{"op_name":"your-op-name-here"}'
要使用默认 op 模板运行渗透测试，但指定其名称和范围，请使用可选的 schedule_op_form 参数：
h3 run-pentest '{"schedule_op_form":{"op_name":"your-op-name-here", "op_param_max_scope": "192.168.0.0/24"}}'
请注意，
h3 run-pentest和h3 run-pentest-and-nodezero接受所有相同的可选参数。
要运行渗透测试并将其分配给名为 my-nodezero-runner 的 NodeZero Runner：
h3 run-pentest '{"schedule_op_form":{"op_name":"Pentest created via h3-cli and launched via runner", "runner_name":"my-nodezero-runner"}}'
如果您已为外部渗透测试配置了 op 模板：
h3 run-pentest '{"op_template_name":"your-op-template-here"}'
如果您没有 op 模板，可以先通过 h3 asset-groups 查找您的资产组（Asset Group）的 uuid，然后运行外部渗透测试：
h3 asset-groups
然后使用以下命令针对该资产组运行外部渗透测试。用您的资产组 uuid 替换 {your-asset-group-uuid}：
h3 run-pentest '{"schedule_op_form": {"op_type": "ExternalAttack", "asset_group_uuid": "{your-asset-group-uuid}"}}'
Horizon3.ai API 由 GraphQL 驱动。除了本文档外，相关文档还包括：
h3-cli 提供了一种简单的机制来运行您自己的 GraphQL 查询。首先，您需要在文件中定义 GraphQL 查询（通常使用 .graphql 扩展名，不过这不是必需的）。然后将文件传给 h3 gql：
h3 gql {your-query-file}
例如，在名为 my_session.graphql 的文件中定义以下内容：
query {
session_user_account {
email
name
company_name
}
}
然后运行：
h3 gql ./my_session.graphql
您应该会看到 GraphQL 服务器返回的原始 JSON 响应。您可以使用 jq 美化 JSON 响应：
h3 gql ./my_session.graphql | jq .
重要！ 您必须指定 graphql 文件的路径（完整路径或相对路径，例如 ./my_session.graphql，而不是仅 my_session.graphql），否则可能会与 h3-cli 内部使用的 graphql 文件发生冲突。
GraphQL 查询还可以定义参数，这些参数以 JSON 对象的形式传给 h3 gql。
例如，在名为 my_pentest.graphql 的文件中定义以下内容：
query q($op_id: String!) {
pentest(op_id:$op_id) {
op_id
name
state
}
}
在本例中，$op_id 是运行查询必须提供的参数。该参数在 JSON 对象中传给查询：
h3 gql ./my_pentest.graphql '{"op_id":"your-op-id-here"}' | jq .
将
your-op-id-here替换为实际的op_id。