Keyfactor Command Connector User Guide

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

Overview

The Keyfactor Command Connector integrates Keyfactor Command with Keyfactor's AgileSec Platform. This Connector allows users to discover, inventory, and analyze X.509 certificate metadata and other relevant cryptographic attributes.

What Gets Scanned

The Keyfactor Command Sensor can discover the following cryptographic assets:

• X.509 Certificates: SSL/TLS certificates, code signing certificates, client authentication certificates, and any other certificates in Command.

Prerequisite Requirements

Ensure you meet the following requirements to enable scanning.

Network Access

Ensure HTTPS network connectivity from AgileSec platform or remote execution machine to Keyfactor Command endpoints.

Supported Authentication Methods

The Keyfactor Command Connector supports three authentication methods.

1. Basic Auth

• Available for Platform, API, and Remote scan executions.

• Uses username and password to access Command API.

• In the configuration file, set only the username and password.

2. OAuth2

• Available for Platform, API, and Remote scan executions.

• State the OAuth Client ID, Client Secret, and Scope.

3. Kerberos

• Only available for Remote scan execution.

• Authenticate using AD/Windows Integrated Auth for Command On-Prem.

Required Access Rights

The Keyfactor authentication credentials must have /certificates/collections/read/ permissions.

Running the Sensor

AgileSec Keyfactor Command 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 Keyfactor Command scans.

Kerberos Auth Parameters

Kerberos authentication is permitted for Remote 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.

   

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.

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": "Keyfactor Command",
    "sensorConfig": {
       "url": "<keyfactor command api url>",
       "token_url": "<oauth2 token url>",
       "client_id": "<oauth2 client id>",
       "client_secret": "<oauth 2 client secret>"
       "scope": "<oauth 2 scope"
       "query_filter": "<keyfactor command query filter string>"
    },
    "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., keyfactor-command-config.yml) with your scan settings. An example configuration can be found in config/sample-configs/keyfactor.yml.

Step 4: Run the Sensor

Execute the sensor with your configuration file:

• Linux/macOS

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

• Windows (PowerShell)

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

Remote Scan Execution Configuration Examples

• OAuth 2 authentication

  scan_config:
    plugins:
      - keyfactor
      - export
    config:
      keyfactor:
        name: keyfactor
        plugin_config:
          url: "https://command.example.com/KeyfactorAPI"
          token_url: "https://login.microsoftonline.com/xxxxxxxxxxx/oauth2/v2.0/token"
          client_id: "xxxxxxxxxxxxxx"
          client_secret: "xxxxxxxxxxxx"
          scope: "api://xxxxxxxxxx/.default"
      local_export:
        name: local_export
        plugin_config:
          <<: *local_export_config
      export:
        name: export
        plugin_config:
          <<: *export_config
          sensor_name: "Remote Keyfactor Scan"
          sensor_type: "Keyfactor Command" # Do not edit this value.
          ran_by: "${env:USER}"
          url: "${env:INGESTION_URL}"
          token: "${env:SENSOR_TOKEN}"
  

Known Limitations

Incremental Scanning Modified Certificates

Incremental scanning will catch new certificates. If a previously-scanned certificate is modified, the modifications will not be discovered by AgileSec until a full scan happens.

Troubleshooting Common Errors

• KF-404 Invalid Keyfactor URL

  • Fix: Review and update the Keyfactor URL or ensure network access is configured correctly.

• KF-500 Failed to send request.

  • Fix: Check Network/TLS connectivity to Command or ensure firewall/proxy is not blocking HTTP API requests.

• KF-502 Unexpected status code from Keyfactor

  • Fix: Review and Correct Keyfactor credentials.

• KERB-401 Wrong keytab_path or file permissions

  • Fix: Review and update keytab_path or check if file permissions are blocking access.

• KERB-402 Failed to load krb5.conf

  • Fix: If using Kerberos, review and update krb5_conf_path or give another Kerberos auth parameter.

• KERB-403 Kerberos login failed

  • Fix: Review Kerberos login and update credentials.

• CONFIG-404 interval is less than 0

  • Fix: Update incremental scanning interval parameter to a positive number.

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact tokens)

• Log output

• Keyfactor Command config details (url, auth type, version)

Contact Support:

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