Venafi Connector User Guide

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

Overview

The Venafi Connector integrates Venafi TLS Protect with Keyfactor's AgileSec Platform. This Connector retrieves X.509 certificates from the Venafi certificate inventory and transmits them to the AgileSec ecosystem for cryptographic visibility, risk assessment, and policy compliance.

What Gets Scanned

The Venafi Connector can discover the following cryptographic asset types from the Venafi TLS Protect inventory:

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

• Certificate Locations: Extracts Venafi certificate DN and policy folder path for finding’s source location.

Prerequisites

Ensure you meet the following requirements to enable scanning.

Network Access

• Ensure HTTPS network connectivity from AgileSec platform or remote execution machine to Venafi TLS Protect instance.

Supported Authentication Methods

The Venafi Connector uses token-based authentication:

• API Token (Bearer): Authenticate using a Venafi API token generated from the Venafi TLS Protect platform.

Required Access Rights

The Venafi API token 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 Venafi 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 Venafi scans.

Remote Execution Configuration

In addition to the above, the following parameters are available for remote execution 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": "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>"
  }

Remote Scan Execution

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

Download Remote Sensor Package

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

• Windows (PowerShell)

  PowerShell

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

Remote Scan Execution Configuration Examples

The remote Connector 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

This Connector integrates with Venafi TLS Protect via the WebSDK API (/vedsdk/certificates/).

OpenSearch Connectivity

Requires connectivity to OpenSearch for de-duplication of certificate thumbprints. If OpenSearch is unreachable, the Connector 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 Connector 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 Connector machine to OpenSearch.

Getting Support

Collect diagnostic information:

• Connector version

• Configuration file (redact tokens and credentials)

• Log output

• Venafi TLS Protect details (URL, version)

Contact Support

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