AWS KMS Connector User Guide

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

Overview

The AWS KMS Connector integrates AWS Key Management Service with Keyfactor's AgileSec Platform. This Connector allows users to discover, inventory, and analyze cryptographic keys managed by AWS KMS across multiple AWS accounts.

What Gets Scanned

The AWS KMS Connector can discover the following cryptographic assets and asset information:

• Public Key Data: Enumerates all asymmetric (RSA, ECC) KMS keys in a specified AWS region.

• Key Metadata: Key specification and usage metadata, aliases, and resource tags for each key; public key material is retrieved for asymmetric keys only.

• Key Aliases: Human-readable alias names associated with keys.

• Resource Tags: AWS resource tags applied to KMS keys.

Scanned Data Fields

The following data fields are scanned for AWS KMS 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 AWS KMS endpoints.

Supported Authentication Methods

The AWS KMS Connector uses AWS Access Key authentication:

• Access Key ID + Secret Access Key: Standard IAM user credentials scoped to the target AWS account and region.

AWS KMS Required Access Rights

The IAM user or role must have the following AWS KMS permissions:

Remote Execution Requirements

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

Running the Connector

AgileSec AWS KMS 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 Options

The following parameters are used to configure AgileSec AWS KMS scans.

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": "AWS KMS",
    "sensorConfig": {
       "akid": "<aws access key id>",
       "secret_key": "<aws secret key>",
       "region": "<aws region>"
    },
    "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., awskms-config.yml) with your scan settings. An example configuration can be found in config/sample-configs/awskms.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 awskms-config.yml
  

• Windows (PowerShell)

  PowerShell

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

Remote Scan Execution Configuration Examples

• Basic Configuration

  YAML

  scan_config:
    plugins:
      - awskms
      - export
    config:
      awskms:
        name: awskms
        plugin_config:
          akid: "${env:AWS_ACCESS_KEY_ID}"
          secret_key: "${env:AWS_SECRET_ACCESS_KEY}"
          region: "us-east-1"
  

Known Limitations

Symmetric Key Material Is Not Extractable

Symmetric KMS keys (SYMMETRIC_DEFAULT and the HMAC_224/256/384/512 specs) are inventoried with their algorithm, size, key usage, and supporting metadata. However, AWS KMS never releases symmetric key material, so these findings carry no raw key bytes. Their fingerprint_sha256 is derived from the immutable key ARN (unique per key, stable across scans) rather than from key material. Only asymmetric keys (RSA, ECC) expose public key material, from which the fingerprint is computed directly.

Single Region

Each scan covers a single AWS region. To scan multiple regions, configure multiple Connector instances.

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 (e.g., akid, secret_key, region) is missing.

  • Fix: Ensure all required fields are present in the configuration.

• AWSKMS-201 – Failed ListKeys

  • Cause: Insufficient IAM permissions or invalid credentials.

  • Fix: Verify IAM permissions include kms:ListKeys and credentials are correct.

• AWSKMS-202 – Failed GetPublicKey

  • Cause: Unexpected failure retrieving the public key of an asymmetric key; the affected key is skipped. Expected cases (UnsupportedOperationException for keys without public material, AccessDeniedException) are logged without this code

  • Fix: This is expected for symmetric keys. For asymmetric keys, ensure kms:GetPublicKey permission.

• AWSKMS-205 – Failed DescribeKey

  • Cause: Unexpected failure reading key metadata. Without DescribeKey metadata, the affected key is skipped and cannot be reported. AccessDeniedException is logged without this code.

  • Fix: Ensure kms:DescribeKey permission is granted.

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact credentials)

• Log output

• AWS details (region, account ID)

Contact Support

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