horizon3ai/h3-cliHorizon3.ai API用CLIツール
NodeZero MCP Server が利用可能になりました。これにより、ローカルでホストされる MCP Server を実行および管理して、NodeZero の Find、Fix、Verify（FFV）機能を開発ワークフローやセキュリティワークフローに直接組み込むことができます。
h3-cli は、Horizon3.ai API にアクセスするための便利な CLI（コマンドラインインターフェース）です。Horizon3.ai API は、Horizon3.ai ポータルで利用できる機能の一部へのプログラムによるアクセスを提供します。大まかに言うと、この API を使用すると、次のことができます。
API は、環境の定期的なアセスメントのスケジュール設定や、継続的インテグレーションのビルドパイプラインの一部としてペンテストを開始するなど、さまざまなユースケースで利用できます。
以下の手順で、h3-cli をすばやくインストールして使い始めることができます。この手順は macOS および Linux マシンでテスト済みで、bash をサポートする POSIX 準拠 のシステムであれば一般に動作するはずです。
内部ペンテストを h3-cli で実行する予定がある場合は、NodeZero を起動するのと同じ Docker ホストに h3-cli をインストールしてください。
Horizon3.ai のアカウントをすでにお持ちであることを前提としています。お持ちでない場合は、https://portal.horizon3ai.com/ でサインアップしてください。
H3 API にアクセスするには API キーが必要です。ユーザー -> アカウント設定 メニューでポータルから作成できます。
API キーを作成する際は、その権限を制御するロールを割り当てる必要があります。利用可能なロールは次のとおりです。
h3-cli を試していて、そのすべての機能を試してみたい場合は、 ロールをお勧めします。その後は、ユースケースに応じて、より制限の強い権限を使用するとよいでしょう。たとえば、h3-cli を NodeZero Runner のセットアップにのみ使用したい場合は、 ロールを使用することをお勧めします。
同じ h3-cli インストール内で複数の API キーを簡単に管理できます。詳細は こちら を参照してください。
❗ API キーは安全に保管してください。API キーを知っている人は誰でもあなたの H3 アカウントにアクセスできるためです。 API キーは、ユーザー名とパスワードを 1 つにまとめたものと考えてください。API キーを知っている人は、どこからでもあなたのアカウントにアクセスできます。h3-cli は API キーを $HOME/.h3 ディレクトリに保存します。このディレクトリはインストール中に作成され、あなただけが読み書きできるように権限が設定されます。
シェル/ターミナルセッションで以下の 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 プロファイルを作成します。API キーは h3-cli プロファイルに保存されます。ディレクトリとプロファイルの権限は制限されており、自分以外のユーザーは読み書きできません。
インストールスクリプトは、シェルプロファイル（オペレーティングシステムに応じて $HOME/.bash_profile、$HOME/.bash_login、$HOME/.profile のいずれか）を編集して、次の環境変数を設定するよう求めます。
H3_CLI_HOME: h3-cli が自身とサポートファイルの場所を特定するために使用する環境変数です。PATH: シェルコマンドを検索するディレクトリを指定する環境変数です。シェルプロファイルを更新したら、再ログインするかシェルセッションを再起動してプロファイルの変更を反映させ、コマンドプロンプトで h3 を実行して起動できることを確認してください。
h3
すべてが正しくインストールされていれば、h3-cli のヘルプテキストが表示されるはずです。
h3-cli は毎月、新機能、バグ修正、その他のアップデートをリリースしています。以下のいずれかの方法でインストールをアップグレードしてください。
h3 upgrade コマンドを使用する（推奨）2023 年 6 月以降、h3 upgrade コマンドを使用して h3-cli を最新バージョンにアップグレードできます。
ERROR: unrecognized command: "upgrade" というエラーが表示された場合、使用している h3-cli は upgrade コマンドをサポートしていない旧バージョンです。以下のいずれかの方法で 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 ファイルを再ダウンロードして同じ場所に解凍します（つまり、既存の h3-cli インストールを新しい zip に置き換えます）。
2023 年 6 月以降、次のコマンドで現在の h3-cli バージョンを確認できます。
h3 version
バージョンの全履歴とリリースノートは、次のコマンドで確認できます。
h3 version -v
次のコマンドを実行して、API との接続を確認します。
h3 hello-world
次の応答が表示されるはずです。
{
"data": {
"hello": "world!"
}
}
❗️ エラー応答が返ってくる場合は、Horizon3.ai ポータル のチャットアイコンから H3 にお問い合わせください。
以下のコマンドは、アカウント内のペンテストの一覧を新しい順に返します。
h3 pentests
特定の検索語に一致するペンテストを絞り込むには、検索語をパラメータとして渡します。
h3 pentests sample
アカウント内の最新のペンテストを照会するには:
h3 pentest
アカウント内の任意のペンテストを照会するには、ペンテストの op_id をパラメータとして渡します。
h3 pentest your-op-id-here
いくつかの h3-cli コマンドは、パラメータとして op_id が渡されない限り、最新のペンテストをデフォルトとして使用します。
「op」と「ペンテスト」という用語は、しばしば同じ意味で使用されます。
ペンテストを実行するには、op テンプレート を指定する必要があります。op テンプレートは、スコープ、攻撃パラメータ、その他の（オプションの）設定を含む、完全なペンテスト構成を指定します。
Horizon3.ai は、新規ユーザーに Default 1 - Recommended というデフォルトの op テンプレートを提供しています。このテンプレートは、常に最新の攻撃パラメータと推奨構成に更新されています。デフォルトのテンプレートにはスコープが定義されていません。その場合、NodeZero は Intelligent Scope を使用します。NodeZero のホストサブネットが初期スコープを提供し、ペンテスト中により多くのホストとサブネットが発見されるにつれて、スコープは有機的に拡大します。Intelligent Scope やその他のデプロイオプションの詳細については、製品ドキュメント を参照してください。
経験豊富なユーザーは、Horizon3.ai ポータル でカスタム op テンプレートを作成できます。カスタム op テンプレートを作成するには、Run a Pentest モーダルでペンテスト構成をカスタマイズするオプションが表示されるまで進みます。op テンプレートは、実際にペンテストを実行せずに作成できます。
デフォルトの op テンプレートと Intelligent Scope を使用してペンテストをプロビジョニングするには:
h3 run-pentest
JSON 応答には、新しく作成されたペンテストの詳細が含まれています。Horizon3.ai ポータル を確認するか、h3 pentest を実行することで、ペンテストがプロビジョニングされていることを確認できます。
ペンテスト作成時に追加のパラメータを指定する方法はいくつかあります。詳細は 追加の例はこちら を参照してください。
❗ 待ってください。まだ終わっていません！
内部 ペンテスト（デフォルト）の場合、ペンテストが実行を開始するまでに追加の手順が必要です。ペンテストの開始を完了するには、次のセクションの NodeZero のダウンロードと実行に関する説明を参照してください。
外部 ペンテストを実行する場合、NodeZero は
h3 run-pentestの一部として H3 クラウド内で自動的に起動されるため、ペンテストを開始するための追加の手順はありません。
❗ ️次の手順は 内部 ペンテストにのみ適用されます。外部 ペンテストの場合、NodeZero は H3 クラウド内で自動的に起動されます。
内部 ペンテストを作成したら、ネットワーク内の Docker ホスト上で NodeZero コンテナを実行する必要があります。これを行うには、Docker ホスト上で NodeZero 起動スクリプトを実行します。
直近に作成したペンテスト用の 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 を最初にインストールすると、install.sh に指定した API キーを使用して、default という名前の初期プロファイルが自動的に作成されます。
別の API キーで別のプロファイルを作成する場合は、次のコマンドを使用します:
h3 save-profile my-profile {api-key}
これにより、指定された {api_key} に対して $HOME/.h3 配下に my-profile という名前のプロファイルが作成されます。現在のシェルセッションでプロファイルをアクティベートするには、次のコマンドを使用します（先頭のドット . に注意）:
. h3 profile my-profile
現在アクティブなプロファイルは h3 profile で確認でき、その API キーの詳細は h3 whoami で確認できます:
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 キーは失効されないことに注意してください。ローカルマシンから削除されるだけです。API キーの失効はポータルから行えます。
このセクションでは、h3-cli を使用したペンテスト実行の追加の例を示します。
ペンテストをプロビジョニングする最も簡単な方法は、デフォルトの op テンプレートと Intelligent Scope を使用することです:
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 でアセットグループの uuid を確認してから、外部ペンテストを実行できます:
h3 asset-groups
次に、以下のコマンドを使用して、そのアセットグループに対して外部ペンテストを実行します。{your-asset-group-uuid} を実際のアセットグループの uuid に置き換えてください:
h3 run-pentest '{"schedule_op_form": {"op_type": "ExternalAttack", "asset_group_uuid": "{your-asset-group-uuid}"}}'
Horizon3.ai API は GraphQL をベースとしています。この CLI ドキュメントに加えて、関連ドキュメントは次のとおりです。
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に置き換えてください。