Using the Key Usage Reporter (KUR) tool

Basic usage — scan for HPCS keys (default)

Use the following command to scan the currently targeted IBM Cloud account for all hs-crypto instances, their keys, and any cloud resources encrypted by those keys.

./<kur-binary> 

Scan for Key Protect keys

To scan for Key Protect instances instead of HPCS, use the -service kms flag.

./<kur-binary> --service kms

Scan for Key Protect Dedicated instances only

You can filter the scan to only include dedicated Key Protect instances.

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

Scan for Key Protect multi-tenant instances only

You can filter the scan to only include multi-tenant Key Protect instances.

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

Enable debug logging

Enable detailed debug output to troubleshoot issues or understand the tool's behavior.

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

Specify a custom output file path

By default, the tool generates an output file with an auto-generated name, but you can specify a custom path.

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

Metadata

Metadata includes execution context such as the tool version, target KMS service, IBM Cloud API endpoint, account name, account ID, and the user who ran the scan.

KMS instances

One entry per KMS or HPCS instance found in the account. Instances that have detected key usage are listed first, followed by instances with no detected usage. Each instance contains:

Instance metadata

Name, CRN, state, allowed network, public and private endpoints, type (for Key Protect: multi-tenant or dedicated)

found_by_kms_instance_listing

true if the instance was found by listing KMS instances in the account

found_by_resource_scan

true if the instance had keys detected during the resource scan

instance_stats

Key counts by state:

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

keys[]

Full key inventory from the Key Protect API. Each key includes:

• type — crk (Customer Root Key) or standard_key
• state_name — pre-activation, active, suspended, deactivated, or destroyed
• name — key name
• id — key UUID
• has_migration_intent — whether the key has a migration intent set
• migration_intent_target_crk — target CRK CRN (only present when has_migration_intent is true)
• found_by_kms_key_listing or found_by_resource_scan — how the key was discovered
• associations[] — cloud resources registered against the key (from the Key Protect registrations API). Each entry shows the resource_crn and whether it has prevent_key_deletion enabled. Omitted when a key has no registrations.
• service_usage — map of service name to encrypted resources detected by the account-wide resource scan. Only present for keys found by the resource scan.

CRNs

Resources that referenced encryption identifiers matching a CRN pattern but not a KMS or HPCS key CRN are captured here to ensure nothing is silently dropped.

Unknowns

Resources that referenced encryption identifiers that could not be parsed as CRNs at all are listed here.

Example instance entry

The following example shows the structure of a KMS instance entry in the JSON report.

{
  "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
    }
  ]
}

Usage

Use the process-at subcommand to process activity tracking log files.

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

What it does

Takes a TSV file exported from the IBM Cloud Logs activity tracking event routing archive query, extracts the JSON events from the text column, and filters for KMS and HPCS-related events (kms.* and hs-crypto.* actions). It then produces four output files:

<base>_events.json

All extracted events as a formatted JSON array

<base>_events.csv

Flat CSV with one row per event, containing: serviceName, region, accountId, instanceId, keyId, action, outcome, reasonType, reasonCode, initiatorId, initiatorName, authId, requestInstanceId, eventTime, correlationId, agent

<base>_events_summary.csv

Grouped summary with event counts, grouped by service, region, account, instance, key, action, outcome, reason, and initiator

<base>_events_summary_by_action.csv

Grouped summary with event counts, grouped by service, region, account, instance, key, action, and initiator (without outcome or reason breakdown)

Where <base> is derived from the input file name (stripping _logs.tsv or .tsv).

Example

The following example shows how to process an activity tracking log file and the output files that are generated.

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

The command produces the following output files:

• 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

This is useful for analyzing KMS key activity patterns, identifying which services and users are performing key operations, and investigating migration-related events like ack-migrate.

IBM Cloud CLI not installed

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

Install the IBM Cloud CLI by following the Getting started with the IBM Cloud CLI documentation.

Missing CLI plugins

If required CLI plugins are not installed, you'll see an error message listing the missing plugins.

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

Install the missing plugins:

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

Outdated CLI plugins

If your CLI plugins are outdated, you'll see a warning message listing which plugins need to be updated.

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

Update the plugin:

ibmcloud plugin update container-service

Not logged in

If you're not logged in to IBM Cloud, the tool will display an error message.

not logged in to IBM Cloud. Please login first

Log in to IBM Cloud:

ibmcloud login

Token expired or about to expire

The tool requires a valid IAM token with at least 3 minutes of remaining validity.

If your IAM token has less than 3 minutes of remaining validity, the tool will reject it. Refresh your session:

ibmcloud login

Private-only instances

Some KMS instances might be configured to allow only private network access. If a KMS instance allows only private network access and you are not connected to the IBM Cloud private network, the tool cannot fetch stats or keys for that instance. Use --skip-private-calls to skip these instances rather than having the tool fail on them:

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

100+ KMS instances

The IBM Cloud resource listing API has a limit on the number of instances that can be returned.

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

The IBM Cloud resource listing API returns a maximum of 100 instances. If the account has more than 100 KMS instances, only the first 100 will be included in the report. This is a known limitation.

Invalid service-type with hs-crypto

The --service-type flag is only valid when scanning Key Protect instances.

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

The --service-type flag (to filter by dedicated or multi-tenant) only applies to Key Protect (--service kms). It is not applicable to HPCS instances.