Venafi Sensor User Guide

The Venafi Sensor User Guide provides instructions for deploying and operating the Venafi 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 Venafi Sensor integrates Venafi TLS Protect with Keyfactor's AgileSec Platform. It retrieves X.509 certificates from the Venafi certificate inventory and transmits them to the AgileSec ecosystem for cryptographic visibility, risk assessment, and policy compliance.

Key Features

• Automated Certificate Retrieval: Fetches certificates from the Venafi TLS Protect API using paginated queries.

• Policy-Based Scoping: Retrieves certificates scoped to a configurable Venafi policy folder (recursive).

• De-Duplication: Queries OpenSearch for existing certificate thumbprints to avoid re-ingesting previously discovered certificates.

• Certificate Parsing: Downloads certificate data in DER format and encodes to PEM for enrichment by the unified sensor core.

What Gets Scanned

The sensor retrieves certificates from the Venafi TLS Protect inventory. Certificates are sent as PEM-encoded data to the unified sensor core, which parses and extracts:

• X.509 Certificates: Certificates managed within the configured Venafi policy folder

• Certificate Location: Venafi certificate DN and policy folder path, stored as finding source location

Prerequisites

Venafi Requirements

Remote Execution Requirements

If running the unified sensor remotely using CLI :

Supported Authentication Methods

The Venafi sensor uses token-based authentication:

• API Token (Bearer): Authenticate using a Venafi API token generated from the Venafi TLS Protect platform. The token must have certificate:manage scope.

Note: The token is passed as a Bearer token in the Authorization header for all API requests.

Required Access Rights

The Venafi API token must have the following permissions:

Running the Sensor

The Venafi sensor can be executed using 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. It enables on-demand or scheduled scans that run in a dedicated environment.

Benefits include:

• Runs on Keyfactor AgileSec Platform.

• For on-premise deployments, scans run on scan nodes, or backend nodes.

• For Kubernetes environments:

  • Leverages automatic resource provisioning and auto-scaling

  • Creates ephemeral sandbox pods for performing each scan.

Platform Scan Configuration

Step 1: Navigate to Sensors Setup Page

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.

Step 2: Select Venafi Sensor

2.1 Click the "Choose a Sensor" button.

2.2 Browse or search for "Venafi"

2.3 Click on the Venafi 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

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": "Venafi TLS Protect",
    "sensorConfig": {
       "url": "<venafi base url>",
       "policy": "\\VED\\Policy\\Your\\Folder",
       "token": "<venafi api token>"
    },
    "callbackId": "<callback id>",
    "labels": [
        {
            "<label name>": "<label value>"
        }
    ],
    "priority": "<priority>"
  }

API Field Descriptions

See Platform Scan Configuration Fields.

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., venafi-config.yml) with your scan settings. An example configuration can be found in config/sample-configs/venafi.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 venafi-config.yml

• Windows (PowerShell)

  POWERSHELL

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

Remote Scan Execution Configuration Examples

The remote sensor contains an example configuration file in the directory config/sample-configs/venafi.yml.

• Basic Configuration

  YAML

  scan_config:
    plugins:
      - venafi
      - export
    config:
      venafi:
        name: venafi
        plugin_config:
          url: "<https://venafi.company.com>"
          policy: "\\\\VED\\\\Policy\\\\Your\\\\Folder"
          token: "${env:VENAFI_TOKEN}"
          opensearch:
            address: "<https://127.0.0.1:9200>"
            username: "${env:OS_USER}"
            password: "${env:OS_PASS}"

Known Limitations

Venafi TLS Protect Only

• Description: This sensor integrates with Venafi TLS Protect via the WebSDK API (/vedsdk/certificates/).

OpenSearch Connectivity

• Description: This sensor requires connectivity to OpenSearch for de-duplication of certificate thumbprints. If OpenSearch is unreachable, the sensor will fail to start.

Troubleshooting

Common Errors

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

• status != 200 when retrieving the data, check token

  • Cause: Invalid or expired Venafi API token, or incorrect base URL.

  • Fix: Verify the token has certificate:manage scope and has not expired. Regenerate the token from Venafi TLS Protect if needed.

• No data returned from Venafi

  • Cause: The specified policy folder contains no certificates, or the policy path is incorrect.

  • Fix: Verify the policy folder path exists in Venafi and contains certificates.

• Certificate contains no X509 information, skipping...

  • Cause: A certificate in Venafi has no X509 data or serial number (error state in Venafi).

  • Fix: This is informational. The sensor skips these certificates automatically.

• failed to connect to OpenSearch

  • Cause: Network connectivity issue or invalid OpenSearch credentials.

  • Fix: Verify the OpenSearch address, username, and password. Ensure network connectivity from the sensor machine to OpenSearch.

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact tokens and credentials)

• Log output

• Venafi TLS Protect details (URL, version)

Contact Support:

• Email: support@keyfactor.com

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