Thales Luna HSM Sensor User Guide

The Thales Luna HSM Sensor User Guide provides instructions for deploying and operating the Thales Luna HSM Sensor within the Keyfactor AgileSec Platform. This guide covers supported authentication methods, execution methods, configuration options, and troubleshooting.

Refer to Sensors Architecture and Overview for additional details on sensor architecture, data flows, incremental scanning, and auto-resolution.

Overview

The Thales Luna HSM Sensor integrates Thales Luna Network HSM with Keyfactor's AgileSec Platform. This sensor allows you to discover, inventory, and analyze cryptographic keys stored within Luna HSM partitions via the REST API.

Key Features

• Partition-Level Discovery: Enumerates cryptographic objects across multiple HSM partitions.

• Parallel Processing: Supports concurrent partition and object processing for faster scans.

• Per-Partition Configuration: Override role and password settings on a per-partition basis.

• Async Task Support: Handles long-running HSM operations with configurable task polling.

What Gets Scanned

The sensor queries the Luna HSM REST API to discover:

• Cryptographic Keys: Symmetric and asymmetric keys stored in HSM partitions

• Key Attributes: Algorithm, key size, usage flags, and object metadata

• Partition Information: HSM and partition identifiers

Prerequisites

Thales Luna Requirements

Remote Execution Requirements

If running the unified sensor remotely using CLI:

Supported Authentication Methods

The Thales Luna HSM sensor uses REST API authentication:

• Username/Password: REST API credentials configured on the Luna HSM appliance.

Running the Sensor

The Thales Luna HSM sensor can be executed using the following method:

1. Remote Scan Execution: Deploy and run the sensor via CLI on customer-managed infrastructure for scenarios such as:

   1. Scanning air-gapped or internal instances the platform cannot directly reach

   2. Customers wanting to manage their own scheduling and execution environment.

Refer to Sensors Architecture and Overview: Running the Sensor for additional execution and flow details.

Remote Scan Execution

Remote Execution Flow allows you to run the sensor on a host using the Unified Sensor binary.

Remote Scan Execution Configuration

Step 1: Download Unified Sensor

1.1 Navigate to AgileSec Platform UI → Sensors → Remote Scan.

1.2 Download the sensor binary for your operating system.

Step 2: Generate Remote Sensor Token

2.1 In the Remote Scan UI, click "Generate Token".

2.2 Copy the generated token.

2.3 Store the token securely in an environment variable or set it in the sensor config:

  export SENSOR_TOKEN="your-generated-token"

Step 3: Create Configuration File

Create a YAML configuration file (e.g., thales_luna-config.yml) with your scan settings. An example configuration can be found in config/sample-configs/thales_luna.yml.

Step 4: Run the Sensor

Execute the sensor with your configuration file:

• Linux/macOS

  BASH

  # Set environment variables
  export SENSOR_TOKEN="your-sensor-token"
  
  # Run sensor
  ./unified_sensor_linux -c thales_luna-config.yml

• Windows (PowerShell)

  POWERSHELL

  # Set environment variables
  $env:SENSOR_TOKEN = "your-sensor-token"
  
  # Run sensor
  .\\unified_sensor_windows.exe -c .\\thales_luna-config.yml

Remote Scan Execution Configuration Examples

• Basic Configuration

  YAML

  scan_config:
    plugins:
      - thales_luna
      - export
    config:
      thales_luna:
        name: thales_luna
        plugin_config:
          base_url: "<https://luna-hsm:8443>"
          username: "rest_api_user"
          password: "${env:LUNA_PASS}"
          api_version: 16

• With Specific Partitions and Concurrency

  YAML

  scan_config:
    plugins:
      - thales_luna
      - export
    config:
      thales_luna:
        name: thales_luna
        plugin_config:
          base_url: "<https://luna-hsm:8443>"
          username: "rest_api_user"
          password: "${env:LUNA_PASS}"
          api_version: 16
          partition_role: "co"
          partition_password: "${env:PARTITION_PASS}"
          partitions:
            - hsm_id: "hsm1"
              partition_id: "partition1"
              role: "co"
              password: "${env:PARTITION1_PASS}"
            - hsm_id: "hsm1"
              partition_id: "partition2"
          max_parallel_partitions: 2
          max_parallel_partition_tasks: 8

Known Limitations

REST API Required

• Description: The Luna HSM must have the REST API enabled. Older firmware versions may not support this feature.

Concurrency Limits

• Description: Setting max_parallel_partitions and max_parallel_partition_tasks too high may overwhelm the HSM. The total goroutine count is max_parallel_partitions × max_parallel_partition_tasks.

Troubleshooting

Common Errors

• CONFIG-404 — Unable to read/parse configuration file

  • Cause: The configuration file path is incorrect or the file is malformed.

  • Fix: Verify the config file path and validate JSON syntax.

• Thales Luna BaseURL is not configured

  • Cause: The base_url field is empty or missing.

  • Fix: Set base_url to the Luna HSM REST API URL.

• 401 Unauthorized

  • Cause: Invalid REST API credentials.

  • Fix: Verify the username and password are correct for the Luna REST API.

• Partition login failures

  • Cause: Incorrect partition role or password.

  • Fix: Verify the partition_role and partition_password settings. Check per-partition overrides if configured.

• Task polling timeouts

  • Cause: Async HSM operations taking longer than the configured task_wait_time.

  • Fix: Increase the task_wait_time value.

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact credentials)

• Log output

• Luna HSM details (URL, firmware version, API version)

Contact Support:

• Portal: https://support.keyfactor.com