Thales CTM Connector User Guide

Instructions for deploying the Thales CTM Connector to scan for cryptographic assets and deliver findings to the AgileSec Platform for processing and analysis.

Overview

The Thales CTM Connector integrates Thales CipherTrust Manager with Keyfactor's AgileSec Platform. This Connector allows discovery, inventory, and analysis of cryptographic keys managed by a Thales CipherTrust Manager instance.

What Gets Scanned

The Thales CTM Connector can discover the following cryptographic asset types:

• Cryptographic Keys: All symmetric and asymmetric cryptographic keys managed by CipherTrust Manager.

• Key Metadata: Key attributes, algorithms, sizes, states, usage operations, labels, aliases, and fingerprints.

• Public Key Material: RSA, DSA, and ECDSA public key components for asymmetric keys.

Prerequisites

Ensure you meet the following requirements to enable scanning.

Network Access

Ensure HTTPS network connectivity from AgileSec platform or remote execution machine to the CipherTrust Manager server.

Supported Authentication Methods

The Thales CTM Connector supports two authentication methods:

1. All Execution Methods: Basic Authentication (Username and Password)

Standard username/password authentication against the CipherTrust Manager is available for Platform, API, and Remote Scan Executions.

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

• domain defaults to root if not specified

2. Remote Scan Execution Only: mTLS Certificate Authentication

MTLS (certificate-based) authentication is available for Remote Scan Execution only:

• 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

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

• Using a Local CA from Thales CTM

• Using an External CA

init.sh

The init.sh script is provided below to gather the configuration parameters required for mTLS authentication. This script is not required; other methods may be used to create the authentication client and certificate materials.

The script will output the client_id, client_certificate path, client_private_key path, and root_ca.

#!/bin/bash

token="<Thales CTM token>"
url="<base_url>"
csr_file="<path/to/csr.pem>"
cert_file="<path/to/cert.pem>"
name="<token client name>"

usage() {
  echo "Usage: $0 --url $url --token $token (--csr $csr_file | --cert $cert_file) [--name $name]"
  exit 1
}

# Parse command-line arguments
while [[ "$#" -gt 0 ]]; do
    case $1 in
        --url) url="$2"; shift ;;
        --csr) csr_file="$2"; shift ;;
        --cert) cert_file="$2"; shift ;;
        --token) token="$2"; shift ;;
        --name) name="$2"; shift ;;
        *) echo "Unknown parameter passed: $1"; usage ;;
    esac
    shift
done

# Check if all required arguments are provided
if [[ -z "$url" || -z "$token" || ( -z "$csr_file" && -z "$cert_file" )]]; then
    usage
fi


if [[ "${url: -1}" != "/" ]]; then
  url="${url}/"
fi

if [[ ! -z "$csr_file" ]]; then
  # Read CSR file and replace newlines with \n, making it single line
  csr=$(sed ':a;N;$!ba;s/\n/\\n/g' "$csr_file")

  json_payload=$'{
    "name": "'"$name"'",
    "registration_token": "'"$token"'",
    "csr": "'"$csr"'"
  }'
else
  # Read cert file and replace newlines with \n, making it single line
  cert=$(cat $cert_file | jq -R --slurp)
  json_payload=$'{
    "name": "'"$name"'",
    "registration_token": "'"$token"'",
    "client_cert_params": {
      "certificate": '"$cert"'
    }
  }'
fi

echo ">>>"
echo "$json_payload"
echo "<<<"

response=$(curl -s -k "${url}api/v1/client-management/clients/" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  --data-binary "$json_payload" \
  --fail-with-body)
rc=$?
if [ $rc -ne 0 ]; then
  echo "The request failed, rc: $rc"
  curl -s -k "${url}api/v1/client-management/clients/" \
    -H "Content-Type: application/json" \
    -H "accept: application/json" \
    --data-binary "$json_payload" \
    -vvv
  exit 1
fi

# Extract the cert
echo -e "Saving certificate into cert.pem"
cert=$(echo "$response" | jq -r '.cert')
echo -e "$cert" | sed 's/\\n/\n/g' > cert.pem

# Extract the root ca
echo -e "Saving root ca certificate into rootca.pem"
rootca=$(echo "$response" | jq -r '.ca_cert')
echo -e "$rootca" | sed 's/\\n/\n/g' > rootca.pem

# Print the client_id required for connector.
id=$(echo "$response" | jq -r '.id')
echo -e "client_id: $id"

2.1 Using Local CA from Thales CTM

2.2 Using External CA

Thales CTM Required Access Rights

The authenticated user must have the following permissions:

Remote Execution Requirements

If running the Connector remotely using CLI, the remote execution machine must meet these requirements:

Running the Connector

AgileSec Thales CTM scans can be executed using the following methods:

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

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

3. Remote Scan Execution: Deploy and run the connector 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.

Configuration Fields

The following parameters are used to configure AgileSec Thales CTM scans.

Remote and API Scan Execution Parameters

In addition to the above, the following parameters are available for remote and API scan executions only.

Platform Scan Execution

Running scans 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

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

2. Log in with your credentials

3. Click on "Sensors" in the left navigation menu under Scan

   

4. Click "+ New Sensor".

   

5. Click on the correct card to open the configuration interface.

Configure Parameters and Start Scan

6. Fill in the required configuration parameters.

7. Click Save.

8. Click Action then Scan to begin a scan.
   Note: Click Edit to reconfigure parameters.

   

API Scan Execution

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.

Generate AgileSec API Access Token

1. Open your browser and navigate to AgileSec Platform UI

2. Log in with your Keyfactor credentials

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

4. Click "Generate Token" button

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

6. Click "Generate" and copy the generated token

   

AgileSec API Endpoint

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

Request Format

Headers

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

Request Body

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

Remote Scan Execution

Scans may be run on remote host machines with the AgileSec Remote Sensor Package.

Download Remote Sensor Package

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

2. Log in with your credentials

3. Click on "Sensors" in the left navigation menu under Scan

   

4. Click Remote Scan.

   

5. Click + Download Remote Sensor.

   

6. Download the sensor binary for your remote machine’s operating system

   

Generate Platform Token

7. In the Download Remote UI, click "Generate Token"

8. Copy the generated token

9. Store securely in an environment variable such as SENSOR_TOKEN:

    export SENSOR_TOKEN="your-generated-token"
   

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 Connector

Execute the Connector with your configuration file:

• Linux/macOS

  Bash

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

• Windows (PowerShell)

  PowerShell

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

Remote Scan Execution Configuration Examples

• Username/Password Auth Example

  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 Example

  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
  

Known Limitations

Authentication

mTLS authentication requires certificate and key files accessible at the specified paths on the machine running the Connector.

Pagination

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-500 – No Thales CTM scan target defined

  • Cause: A required configuration field is missing.

  • Fix: Ensure base_url is provided.

• Authorization Error

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

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

• 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:

• Connector version

• Configuration file (redact credentials and keys)

• Log output

• CipherTrust Manager details (URL, version)

Contact Support

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