基本的な使い方：HPCSキーのスキャン（デフォルト）

以下のコマンドを使用して、現在ターゲットとしている IBM Cloud アカウントすべての hs-crypto インスタンス、その鍵、およびそれらの鍵によって暗号化されたクラウド・リソースをスキャンする。

./<kur-binary>

Key Protect キーのスキャン

HPCSの代わりに Key Protect インスタンスをスキャンするには、 -service kms フラグを使用する。

./<kur-binary> --service kms

スキャン対象 Key Protect 専用インスタンスのみ

Key Protect Dedicatedインスタンスのみを含むようにスキャンをフィルタリングすることができます。

./<kur-binary> --service kms --service-type dedicated

Key Protect マルチテナントインスタンスのみをスキャンする

Key Protect Standard（マルチテナント）インスタンスのみを含むようにスキャンをフィルタリングできます。

./<kur-binary> --service kms --service-type multi-tenant

デバッグ・ロギングを有効にする

問題のトラブルシューティングやツールの動作を理解するために、詳細なデバッグ出力を有効にします。

./<kur-binary> --service kms --debug

カスタム出力ファイルのパスを指定する

デフォルトでは、このツールは自動生成された名前で出力ファイルを生成するが、カスタムパスを指定することもできる。

./<kur-binary> --service kms --output my-report.json

メタデータ

メタデータには、ツールのバージョン、ターゲットKMSサービス、 IBM Cloud APIエンドポイント、 アカウント名、 アカウント ID、スキャンを実行したユーザーなどの実行コンテキストが含まれる。

KMSインスタンス

アカウント見つかったKMSまたはHPCSインスタンスごとに1エントリ。 キーの使用が検出されたインスタンスが最初に列挙され、次に使用が検出されなかったインスタンスが列挙される。 各インスタンスには

インスタンス・メタデータ

名前、CRN、状態、許可されたネットワーク、パブリックおよびプライベート・エンドポイント、タイプ（ Key Protect の場合： multi-tenant または dedicated ）

found_by_kms_instance_listing

true インスタンスがアカウント内のKMSインスタンスをリストして見つかった場合。

found_by_resource_scan

true リソーススキャン中に検出されたキーを持つインスタンスの場合。

instance_stats

州別のキーカウント：

• active_crk_count, suspended_crk_count, deactivated_crk_count, destroyed_crk_count
• active_standard_key_count, destroyed_standard_key_count.

keys[]

Key Protect APIからの完全なキーインベントリ。 各キーには以下のものが含まれる：

• type crk （お客様 ）または。 standard_key
• state_name: pre-activation active, suspended, deactivated, または destroyed.
• name キー名。
• id キー UUID。
• has_migration_intent: キーにマイグレーション・インテントが設定されているかどうか。
• migration_intent_target_crk: ターゲット CRK CRN ( has_migration_intent が true のときのみ存在する)。
• found_by_kms_key_listing または found_by_resource_scan: キーの発見方法。
• associations[] Key Protect 登録 API から）キーに対して登録されたクラウドリソース。 各エントリーは、 resource_crn と、 prevent_key_deletion が有効になっているかどうかを示している。 キーに登録がない場合は省略。
• service_usage アカウントリソーススキャンによって検出された暗号化されたリソースへのサービス名のマップ。 リソーススキャンで見つかったキーのみに存在する。

CRN

KMSまたはHPCSの鍵CRNではないが、CRNパターンに一致する暗号化識別子を参照するリソースは、何もサイレント・ドロップされないように、ここでキャプチャされる。

未知数

CRNとしてまったく解析できなかった暗号化識別子を参照するリソースをここに列挙する。

インスタンス・エントリーの例

次の例は、JSONレポートのKMSインスタンス・エントリーの構造を示している。

{
  "name": "my-kp-instance",
  "type": "multi-tenant",
  "crn": "crn:v1:bluemix:public:kms:us-south:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab::",
  "state": "active",
  "allowed_network": "public-and-private",
  "public_endpoint": "https://us-south.kms.cloud.ibm.com",
  "private_endpoint": "https://private.us-south.kms.cloud.ibm.com",
  "found_by_kms_instance_listing": true,
  "found_by_resource_scan": true,
  "instance_stats": {
    "active_crk_count": 5,
    "suspended_crk_count": 0,
    "deactivated_crk_count": 1,
    "destroyed_crk_count": 2,
    "active_standard_key_count": 3,
    "destroyed_standard_key_count": 1
  },
  "keys": [
    {
      "type": "crk",
      "state_name": "active",
      "name": "my-root-key",
      "id": "abc12345-6789-0abc-def0-1234567890ab",
      "has_migration_intent": false,
      "found_by_kms_key_listing": true,
      "found_by_resource_scan": true,
      "associations": [
        {
          "resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab:bucket:my-encrypted-bucket",
          "prevent_key_deletion": true
        }
      ],
      "service_usage": {
        "cloud-object-storage (Cloud Object Storage)": [
          {
            "encrypted_resource": "crn:v1:bluemix:public:cloud-object-storage:global:a/00000000000000000000000000000000:deadbeef-0000-0000-0000-1234567890ab:bucket:my-encrypted-bucket"
          }
        ]
      }
    },
    {
      "type": "standard_key",
      "state_name": "active",
      "name": "my-standard-key",
      "id": "def45678-9012-3456-7890-abcdef012345",
      "has_migration_intent": false,
      "found_by_kms_key_listing": true,
      "found_by_resource_scan": false
    }
  ]
}

使用法

アクティビティ追跡ログファイルを処理するには、 process-at サブコマンドを使用します。

./<kur-binary> process-at <input.tsv>

実行内容

IBM Cloud Logs アクティビティ・トラッキング・イベント・ルーティング・アーカイブ・クエリからエクスポートされたTSVファイルを取得し、 text 列からJSONイベントを抽出し、KMSおよびHPCS関連のイベント（kms.* および hs-crypto.* アクション）をフィルタリングします。 そして4つの出力ファイルを作成する：

<base>_events.json

フォーマットされたJSON配列として抽出されたすべてのイベント。

<base>_events.csv

CSV serviceName, region, action, outcome, agent. accountId, instanceId, keyId, reasonType, reasonCode, initiatorId, initiatorName, authId, requestInstanceId, eventTime, correlationId,

<base>_events_summary.csv

サービス、地域、 アカウント、インスタンス、キー、アクション、結果、理由、および開始者によってグループ化された、イベントカウントによるグループ化されたサマリー。

<base>_events_summary_by_action.csv

サービス、地域、 アカウント、インスタンス、キー、アクション、およびイニシエータ（結果または理由の内訳なし）ごとにグループ化されたイベントカウントのサマリー。

ここで、 <base> は入力ファイル名から派生したものである（ _logs.tsv または .tsv ）。

例

次の例は、アクティビティ追跡ログファイルの処理方法と、生成される出力ファイルを示している。

./<kur-binary> process-at hpcs-at-data-1-day_logs.tsv

このコマンドは以下の出力ファイルを生成する：

• hpcs-at-data-1-day_events.json
• hpcs-at-data-1-day_events.csv
• hpcs-at-data-1-day_events_summary.csv
• hpcs-at-data-1-day_events_summary_by_action.csv

この機能は、KMSのキー・アクティビティ・パターンを分析し、どのサービスやユーザーがキー操作を実行しているかを特定し、 ack-migrate のような移行関連イベントを調査するのに便利です。

IBM Cloud CLIがインストールされていない

IBM Cloud CLI is not installed. Please install it first.
Visit: https://cloud.ibm.com/docs/cli?topic=cli-getting-started

Getting started with IBM Cloud CLI ドキュメントに従って、 IBM Cloud CLI をインストールします。

不足しているCLIプラグイン

必要なCLIプラグインがインストールされていない場合、不足しているプラグインの一覧を示すエラーメッセージが表示されます。

missing required IBM Cloud CLI plugins: [container-service vpc-infrastructure]

不足しているプラグインをインストールします：

ibmcloud plugin install container-service
ibmcloud plugin install vpc-infrastructure
ibmcloud plugin install event-notifications

古いCLIプラグイン

CLIプラグインが古い場合、更新が必要なプラグインをリストアップした警告メッセージが表示されます。

the following IBM Cloud CLI plugins are outdated: [container-service]

プラグインを更新する：

ibmcloud plugin update container-service

ログインしていません

IBM Cloud にログインしていない場合、ツールはエラーメッセージを表示します。

not logged in to IBM Cloud. Please login first

次のように IBM Cloud にログインします。

ibmcloud login

トークンの有効期限が切れた、または切れようとしている

このツールには、有効期限が3分以上残っている有効なIAMトークンが必要です。

IAMトークンの残り有効時間が3分を切ると、ツールはトークンを拒否する。 セッションをリフレッシュしてください：

ibmcloud login

プライベート専用インスタンス

KMSインスタンスによっては、プライベート・ネットワーク・アクセスのみを許可するように設定されている場合がある。 KMSインスタンスがプライベート・ネットワーク・アクセスのみを許可しており、 IBM Cloud Private ネットワークに接続していない場合、ツールはそのインスタンスの統計または鍵を取得できません。 --skip-private-calls を使用して、これらのインスタンスをスキップする：

./<kur-binary> --service kms --skip-private-calls

100以上のKMSインスタンス

IBM Cloud リソース一覧 API には、返されるインスタンスの数に制限があります。

[WARNING] 100 or more KMS instances, only the first 100 instances will be processed.

IBM Cloud リソース一覧APIは、最大100個のインスタンスを返す。 アカウント 100以上のKMSインスタンスがある場合、最初の100のみがレポートに含まれます。 この動作は既知の制限事項です。

hs-cryptoで無効なサービスタイプ

--service-type フラグは、 Key Protect インスタンスをスキャンするときのみ有効である。

error: --service-type can only be used with --service kms

--service-type フラグ（ dedicated または multi-tenant によるフィルタリング）は、 Key Protect (--service kms) にのみ適用されます。HPCS インスタンスには適用されません。