.. _corelight-client:

.. Version number is filled in automatically. .. |version| replace:: 1.5.22

==================================== Corelight Sensor コマンドラインクライアント

.. contents::

概要

このツールは、Corelight Sensor <https://www.corelight.com>_ 用のコマンドラインクライアントを提供します。Corelight Sensor は、Bro の作者たちによってゼロから設計された Bro <https://www.bro.org>_ アプライアンスであり、ネットワークトラフィックを分析パイプライン向けの高忠実度データに変換します。このコマンドラインクライアントを使用すると、Corelight Sensor の包括的な RESTful API を通じて、リモートから設定および制御を行うことができます。このクライアント概要の拡張版については、Corelight Sensor のドキュメントを参照してください。

:Version: |version| :Home: http://www.corelight.com :GitHub: https://github.com/corelight/corelight-client :Author: Corelight, Inc. <https://www.corelight.com>_ [email protected]

ライセンス

このクライアントは BSD ライセンスの下でオープンソースです。詳細は COPYING を参照してください。

インストール

コマンドラインクライアントには Python >= 3.4 と、主な依存関係として requests モジュールがインストールされている必要があります。

クライアントをインストールする最も簡単な方法は、Python Package Index を通じて行うものです::

# pip3 install corelight-client

あるいは、GitHub から最新バージョンをインストールすることもできます::

# git clone https://github.com/corelight/corelight-client
# cd corelight-client
# pip3 install setuptools
# python3 setup.py install

すべてが正しくインストールされていれば、--help で使用法のメッセージが表示されます::

# corelight-client --help
Usage: corelight-client [<global options>] <command> <subcommand> [<options>]
          [--ssl-ca-cert SSL_CA_CERT] [--ssl-no-verify-certificate]
          [--ssl-no-verify-hostname] [--cache CACHE]
[...]

最初のうちは、--help には使用できる追加のコマンドがまだ表示されないことに注意してください。クライアントをデバイスに接続させるには、次のセクションに進んでください。

アクセスと認証

デバイスの設定インターフェースを通じて Corelight API へのアクセスを有効にする必要があります。また、API ユーザー admin (無制限アクセス用) と monitor (読み取り専用アクセス用) のパスワードを設定する必要があります。詳細は Corelight Sensor のドキュメントを参照してください。

次に、corelight-client に Corelight Sensor のネットワークアドレスを伝える必要があります。これを行う方法は 3 つあります:

• コマンドラインに -b <address> を追加する。

• 内容が device=<address> である設定ファイル ~/.corelight-client.rc を作成する。

• 環境変数 CORELIGHT_DEVICE=<address> を設定する。

これらがすべて設定されていれば、corelight-client --help はユーザー名とパスワードを尋ね、その後、デバイス API がクライアントに提供できるコマンドの完全なリストを表示します。認証情報の保存を確認すると、クライアントはそれらを将来の再利用のために ~/.corelight-client/credentials に保存します。認証情報は 設定ファイル_ を通じて、または グローバルオプション_ として指定することもできます。

使用方法

クライアントは、<command> <subcommand> [options] という形式のコマンドのセットを通じて API の機能を提供します。任意のコマンドに --help を追加すると、その機能とオプションのすべての説明が表示されます。

--help の出力でコマンドのオプションが file 型としてリストされている場合、クライアントは送信するファイルのパスを指定する必要があります。さらに、任意のオプションの値の前に file:// を付けると、コマンドライン自体で指定する代わりにファイルからその内容を読み取ることができます。

(注: --help の出力にコマンドのリストが含まれるのは、クライアントがデバイスに接続し、認証できる場合のみです。)

.. _corelight-client-options:

グローバルオプション

corelight-client は以下のグローバルコマンドラインオプションをサポートしています。--device と --fleet オプションは相互排他的に使用する必要があります。その他のすべてのオプションはすべてのリクエストに適用されます:

--async 非同期コマンドが完了するのを待たずに終了します。

--device Corelight Sensor デバイスのネットワークアドレスを指定します。

--fleet Corelight Fleet Manager のネットワークアドレスを指定します。

--uid 指定された Corelight Fleet Manager を通じて管理される Corelight Sensor の UID を指定します。

--cache=<file> Corelight Sensor のメタデータをキャッシュするためのカスタムファイルを設定します。

--debug HTTP リクエストと応答を表示するデバッグ出力を有効にします。

--password 認証用のパスワードを指定します。

--mfa 指定された Corelight Fleet Manager での認証用の 2FA 検証コードを指定します。ユーザーに尋ねるには '-' を使用します。

--ssl-ca-cert デバイスの真正性を検証するためのカスタム SSL CA 証明書を含むファイルを指定します。

--ssl-no-verify-certificate クライアントに任意の Corelight Sensor の SSL 証明書を受け入れるよう指示します。

--ssl-no-verify-hostname ホスト名と一致しない場合でも、クライアントに Corelight Sensor の SSL 証明書を受け入れるよう指示します。

--socket リクエストの送信に unix ドメインソケットを使用するようクライアントに指示します。

--user 認証用のユーザー名を指定します。

--version corelight-client のバージョンを表示して終了します。

--ignore-meta CLI で指定されていない限り、sensor API 呼び出しにメタデータ情報を送信しません。

--automation 自動化に適した動作のバンドルを有効にします: リクエストタイムアウト、一時的な障害の再試行、構造化された JSON エラー、厳選された終了コード分類、および厳密な非対話型確認。詳細は以下の 自動化_ を参照してください。環境変数 CORELIGHT_AUTOMATION=1 を設定することでも有効にできます。

--timeout リクエストタイムアウトを秒単位で設定します。単一の数値 N (connect と read の両方に適用) または connect,read として指定します。--automation が有効な場合のデフォルトは 10,3600 です。

--retries 一時的な障害 (接続エラー、および冪等なリクエストに対する HTTP 429/502/503/504) に対して試行する再試行回数を設定します。--automation が有効な場合のデフォルトは 3、それ以外は 0 です。

--retry-max-time 再試行に費やす最大合計秒数を設定します。--automation が有効な場合のデフォルトは 120 です。

--error-format 出力/エラー形式を text または json に設定します。--automation が有効な場合のデフォルトは json、それ以外は text です。

--assume-yes 確認を求めずに確認ゲート付きの操作を進めます (エイリアス: --confirm)。--automation が有効な場合に破壊的な操作を実行するために必要です。そうでない場合、それらの操作は確認が必要であるというエラーで失敗します。

自動化

--automation を渡す (または CORELIGHT_AUTOMATION=1 を設定する) と、自動化に適した動作のバンドルが有効になり、以下の終了コード分類がオンになります。これは --noblock を暗黙的に含み、デフォルトで 10 秒の connect / 3600 秒の read タイムアウト、3 回の再試行 (合計最大 120 秒)、および成功とエラーの両方に対する JSON 出力になります。各部分はそれぞれ独自のフラグで上書きできます。

--automation がない場合、リクエストタイムアウトはまったくありません (クライアントは無期限にブロックします)。そのため、これを有効にしても以前から存在したタイムアウトが短くなることはありません。デフォルトの read タイムアウトは意図的に長く設定されています: これは、スタックした接続を制限することのみを目的としており、通常の作業を制限するものではありません。大規模なアップロードなど一部の操作は、正当に何分もかかることがあり、read タイムアウトは転送全体ではなくネットワーク読み取りごとに適用されるため、安定したアップロードではタイムアウトがリセットされ続けます。自動化をより早く諦めさせたい場合は --timeout を下げ、低速リンクでの異常に大きな転送の場合は上げてください。

再試行は冪等性を考慮しています: GET/HEAD/OPTIONS リクエストは、接続障害時および HTTP 429/502/503/504 で再試行します。安全でないメソッド (POST/PUT/DELETE) は、サーバーに到達する前に接続がタイムアウトした場合にのみ再試行するため、変更が二重に送信されることはありません。安全でないメソッドでのその他の一時的な障害については、クライアントは再試行しません。一致するコードで終了し (JSON エラーエンベロープに retriable を設定します)、その操作を繰り返しても安全かどうかを唯一知っている呼び出し元が判断できるようにします。

--retry-max-time は、再試行ループの合計実時間予算であり、最初の試行から測定され、リクエスト自体に費やされた時間も含まれます。これは新しい試行のたびにチェックされます: 経過時間と次のバックオフの合計がそれを超えると、それ以上の試行は開始されません。すでに実行中のリクエストを中断することはありません -- 単一のリクエストの所要時間は、この値ではなく上記の read タイムアウトによって制限されます。

終了コード (自動化が有効な場合のみ):

===== ==================================================== コード 意味 ===== ==================================================== 0 成功 1 一般的 / 予期しないエラー 2 使用法 / 不正な引数 3 接続失敗またはタイムアウト (再試行後) 4 認証 / 認可 (401/403) 5 リソースが見つからない (404) 6 サーバーエラー (5xx) 7 確認が必要 (拒否またはブロック) 8 API バージョンがサポートされていない ===== ====================================================

.. _corelight-client-config:

設定ファイル

corelight-client は設定ファイル ~/.corelight-client.rc を探します。 ファイルは <key>=<value> という行で構成されている必要があります。# で始まるコメントは無視されます。corelight-client は以下のキーをサポートしています:

device Corelight Sensor デバイスのネットワークアドレス。

fleet Corelight Fleet Manager のネットワークアドレス。

uid 指定された Corelight Fleet Manager を通じて管理される Corelight Sensor の UID。

user 認証用のユーザー名。

password 認証用のパスワード。

mfa Corelight Fleet Manager での認証用の 2FA 検証コード。ユーザーに尋ねるには '-' を使用します。

ssl-ca-cert デバイスの真正性を検証するためのカスタム SSL CA 証明書を含むファイル。

ssl-no-verify-certificate false に設定すると、クライアントは任意の Corelight Sensor の SSL 証明書を受け入れます。

ssl-no-verify-hostname false に設定すると、クライアントはホスト名と一致しない場合でも Corelight Sensor の SSL 証明書を受け入れます。

socket リクエストの送信に使用する unix ドメインソケット。

automation 真の値に設定すると、自動化に適した動作を有効にします。自動化_ を参照してください。

timeout リクエストタイムアウト (秒単位)。N または connect,read として指定します。

retries 一時的な障害に対して試行する再試行回数。

retry-max-time 再試行に費やす最大合計秒数。

error-format 出力/エラー形式。text または json。