Thales CTM Sensor User Guide

The Thales CTM Sensor User Guide provides instructions for deploying and operating the Thales CTM 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 CTM Sensor integrates Thales' CipherTrust Manager with Keyfactor's AgileSec Platform. This sensor allows you to discover, inventory, and analyze cryptographic keys managed by Thales CipherTrust Manager HSM partitions.

Key Features

• HSM Key Discovery: Enumerates cryptographic keys across CipherTrust Manager partitions.

• Dual Authentication: Supports both username/password and mTLS certificate-based authentication.

• Continuous Scanning: Supports interval-based continuous scanning or single-execution mode.

• Paginated Retrieval: Handles large key inventories with configurable page limits.

What Gets Scanned

The sensor queries the CipherTrust Manager API to discover:

• Cryptographic Keys: Symmetric and asymmetric keys managed by CipherTrust Manager

• Key Metadata: Key attributes, algorithms, sizes, and usage information

• Partition Information: HSM partition assignments and organization

Prerequisites

Thales CTM Requirements

Remote Execution Requirements

If running the unified sensor remotely using CLI:

Supported Authentication Methods

The Thales CTM sensor supports two authentication methods:

Username and Password Authentication

Standard username/password authentication against the CipherTrust Manager.

• Configure username, password, domain, and optionally auth_domain fields

• domain defaults to root if not specified

mTLS Authentication

Mutual TLS (certificate-based) authentication:

• Requires a client_id (obtained during client registration)

• Requires client_certificate and client_private_key file paths

• Optionally specify root_ca to verify the CipherTrust Manager server certificate

See mTLS Setup for detailed instructions.

Running the Sensor

The Thales CTM sensor can be executed using the following methods:

1. Platform Scan Execution: Configure and execute scans directly though the Keyfactor AgileSec web UI with on-demand or scheduled execution options.

2. Using API: Programmatically trigger scans through REST API calls, enabling integration with CI/CD pipelines and automation workflows.

3. 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.

Platform Scan Execution

Running the sensor through the user interface is the simplest and fastest way to get started. The platform enables running on-demand or scheduled scans in a dedicated environment.

Platform Scan Configuration

Step 1: Navigate to Sensors Setup Page

1.1 Open your browser and navigate to the Keyfactor AgileSec Platform Web URL

1.2 Log in with your credentials

1.3 Click on "Sensors" in the navigation bar.

Step 2: Select Thales CTM Sensor

2.1 Click the "Choose a Sensor" button.

2.2 Browse or search for "Thales CTM"

2.3 Click on the Thales CTM sensor card

This will open the sensor configuration interface.

Step 3: Configure Sensor Parameters

3.1 Fill in the required configuration parameters:

Platform Scan Configuration Fields

Note: Either username/password or client_id/client_certificate/client_private_key must be provided.

Scan Execution Using API

Scans may be programmatically triggered through REST API calls, enabling seamless integration with CI/CD pipelines, automation workflows, and custom applications. API execution provides flexibility for developers to incorporate cryptographic scanning into their existing development and deployment processes.

Note: For complete API reference, see the API document.

API Access Token

1. Open your browser and navigate to the AgileSec Platform UI.

2. Log in with your Keyfactor credentials.

3. Click "Access Tokens" in the main navigation menu.

4. Click "Generate Token".

5. Set Token Type to API Token and provide the required details.

6. Click "Generate" and copy the generated token.

API Endpoint

POST https://<platform-url>/v3/scan/create

Request Format

Headers

Content-Type: application/json
isg-api-token: <your-api-token>

Request Body

The complete request body contains sensor configuration in the sensorConfig field, i.e:

  {
    "sensorName": "<sensor name>",
    "sensorType": "Thales CTM",
    "sensorConfig": {
       "base_url": "<ciphertrust manager url>",
       "username": "<username>",
       "password": "<password>",
       "domain": "root",
       "auth_domain": "root"
    },
    "callbackId": "<callback id>",
    "labels": [
        {
            "<label name>": "<label value>"
        }
    ],
    "priority": "<priority>"
  }

API Field Descriptions

See Platform Scan Configuration Fields for 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_ctm-config.yml) with your scan settings. An example configuration can be found in config/sample-configs/thales_ctm.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_ctm-config.yml

• Windows (PowerShell)

  POWERSHELL

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

Remote Scan Execution Configuration Examples

Note: The following variables are available for Remote Scan Configurations:

• client_certificate: Path to client certificate file for mTLS authentication.

• client_private_key: Path to client private key file for mTLS authentication.

• root_ca: Path to root CA certificate file. If not specified, server certificate is not verified.

• interval: Interval in minutes between continuous scans. Falls back to global interval setting (default: 60 minutes).

• page_limit: Number of results per API page for pagination.

• Username/Password Auth

  YAML

  scan_config:
    plugins:
      - thales_ctm
      - export
    config:
      thales_ctm:
        name: thales
        plugin_config:
          base_url: "<https://ciphertrust.company.com>"
          username: "${env:CTM_USER}"
          password: "${env:CTM_PASS}"
          domain: "root"
           # auth_domain: ""
           # client_id: ""
           # client_certificate: "/path/to/cert.pem"
           # client_private_key: "/path/to/privateKey.pem"
           # root_ca: "/path/to/rootca.pem"
           # interval: 60
           # page_limit: 100

• mTLS Auth

  YAML

  scan_config:
    plugins:
      - thales_ctm
      - export
    config:
      thales_ctm:
        name: thales
        plugin_config:
          base_url: "<https://ciphertrust.company.com>"
          client_id: "3ec05d42-72f0-45aa-8196-f17d73a2f9f0"
          client_certificate: "/path/to/cert.pem"
          client_private_key: "/path/to/privateKey.pem"
          root_ca: "/path/to/rootca.pem"
          # auth_domain: ""
          # root_ca: "/path/to/rootca.pem"
          # interval: 60
          # page_limit: 100

mTLS Setup

There are two methods to setup mTLS authentication for the Thales CTM Sensor:

• Using a Local CA from Thales CTM

• Using an External CA

Using Local CA from Thales CTM

1. Create a new registration token.

   1. Inside the Thales CTM UI, go to Access Management > Registration Tokens.

2. Register a new client by sending a CSR to Thales:

   1. Create a CSR (CA > CSR Generator). Fill in Common Name, algorithm, name, etc.

   2. Download the private key and the CSR from the UI: CSR.pem, privateKey.pem

   3. Run the provided init.sh to get the certificate and root CA from Thales:

      BASH

      ./init.sh --csr "/path/to/csr.pem" --url "<https://url.com/>" --token "<registration token>"

3. In the UI, set the ISG_ThalesCTM client groups (Access Management > Client Hub).

Using External CA

Enabling an External CA

1. Add the External CA to Thales CTM through the Thales CTM UI.

   1. Go to CA > External > Click Add External CA

   2. Set the Client Auth permission for the External CA to Enabled.

2. Add the External CA as a Trusted CA.

   1. Go to Admin Settings > Interfaces > View/Edit web > scroll down to add the External CA to External Trusted CA.

3. Create a Registration Token for the External CA.

   1. Go to Access Management > Registration Tokens > Add Registration Token > At Select CA choose the External CA.

4. Restart Thales CTM to enable changes.

Creating Client

1. You should have a Private Key and Client Certificate signed by the External CA.

2. The Client Certificate should have the Common Name in the subject.

3. Grant the required permission (e.g., Key Admins) to the created Client (Access Management > Client Hub).

4. Run the provided init.sh to create the client and download the root CA from Thales:

   BASH

   ./init.sh --url https://thales.ctm.local --token <Registration Token> --cert <client cert file> --name <cert common name>

5. Update configuration with the received client_id, certificate paths, and, optionally, root_ca.

Known Limitations

Authentication

• Description: mTLS authentication requires certificate and key files accessible at the specified paths on the machine running the sensor.

Pagination

• Description: Very large key inventories may require tuning the page_limit setting for optimal performance.

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.

• CONFIG-422 — Required attribute not found

  • Cause: A required configuration field is missing.

  • Fix: Ensure base_url and either username/password or mTLS fields are provided.

• THALES-101 — Failed Authentication

  • Cause: Invalid credentials, expired certificate, or incorrect client_id.

  • Fix: Verify credentials or regenerate client certificate. Check domain and auth_domain settings.

• THALES-102 — Failed fetching HSM list

  • Cause: Insufficient permissions or network issue.

  • Fix: Verify the client has appropriate permissions in CipherTrust Manager.

• No Thales CTM scan target defined

  • Cause: base_url is empty.

  • Fix: Set the base_url to the CipherTrust Manager URL.

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact credentials and keys)

• Log output

• CipherTrust Manager details (URL, version)

Contact Support:

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