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 を試していて、そのすべての機能を試してみたい場合は、User ロールをお勧めします。その後は、ユースケースに応じて、より制限の強い権限を使用するとよいでしょう。たとえば、h3-cli を NodeZero Runner のセットアップにのみ使用したい場合は、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 コマンドを実行すると、認証はシームレスかつ自動的に行われます。認証のために明示的に行う必要があることはありません。このセクションでは、その背後にある仕組みについて説明します。