Container Sensor User Guide

The Container Sensor User Guide provides instructions for deploying and operating the CContainer 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 Container Sensor integrates container registries (Docker Hub, Azure Container Registry, private registries, etc.) with Keyfactor's AgileSec Platform. This sensor allows you to discover, inventory, and analyze cryptographic assets embedded within container images.

Key Features

• Multi-Image Scanning: Scan multiple container images in a single execution.

• Registry Authentication: Supports username/password and token-based authentication for private registries.

• Deep Cryptographic Discovery: Automatically identifies certificates, private keys, keystores, and cryptographic libraries embedded in container filesystem layers.

• Incremental Scanning: Tracks container image digests to skip unchanged images on subsequent runs.

• Archive Extraction: Extracts and scans archived files found within container image layers.

What Gets Scanned

The sensor pulls container images and analyzes all files within the image layers to discover:

• X.509 Certificates: SSL/TLS certificates, code signing certificates, client authentication certificates

• Private Keys: RSA, DSA, EC private keys in PEM, DER, and PKCS8 formats

• Java Keystores: JKS, JCEKS, PKCS12 keystores

• Tokens: JWT and JWE tokens

• Cryptographic Libraries: OpenSSL, BouncyCastle, http://cryptography.io , and other crypto implementations

• Code Artifacts: Embedded certificates in compiled code (JAR, WAR, EAR files)

Prerequisites

Container Registry Requirements

Remote Execution Requirements

If running the unified sensor remotely using CLI:

Supported Authentication Methods

The Container sensor supports the following authentication methods:

• Username/Password: Standard registry credentials (e.g., Docker Hub username and password).

• Token-Based: Authentication using registry access tokens (e.g., for Azure Container Registry, AWS ECR).

• Anonymous: Public images can be scanned without credentials.

Note: If both username/password and token are provided, token-based authentication takes precedence.

Running the Sensor

The Container Sensor can be executed using the 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. The platform enables running on-demand or scheduled scans in a dedicated environment.

Platform Scan Configuration

Step 1: Navigate to Sensors Setup Page

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

1.2 Log in with your credentials

1.3 Click on "Sensors" in the navigation bar.

Step 2: Select Container Sensor

2.1 Click the "Choose a Sensor" button.

2.2 Browse or search for "Container"

2.3 Click on the Container sensor card

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": "Container",
    "sensorConfig": {
       "username": "<registry username>",
       "password": "<registry password>",
       "images": [
           "docker://docker.io/library/alpine:latest",
           "myregistry.io/myimage:v1.0"
       ]
    },
    "callbackId": "<callback id>",
    "labels": [
        {
            "<label name>": "<label value>"
        }
    ],
    "priority": "<priority>",
    "incrementalScan": true,
    "autoResolutionInterval": 5
  }

API Field Descriptions

See Platform Scan Configuration Fields for details.

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

• Windows (PowerShell)

  POWERSHELL

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

Remote Scan Execution Configuration Examples

• Scan Public Images

  YAML

  scan_config:
    plugins:
      - container_import
      - trigger_discover
      - export
    config:
      container_import:
        name: container
        plugin_config:
          images:
            - "docker://docker.io/library/alpine:latest"
            - "docker://docker.io/library/nginx:latest"

• Scan Private Registry with Auth

  YAML

  scan_config:
    plugins:
      - container_import
      - trigger_discover
      - export
    config:
      container_import:
        name: container
        plugin_config:
          username: "${env:REGISTRY_USER}"
          password: "${env:REGISTRY_PASS}"
          images:
            - "myregistry.io/myapp:v2.1"
            - "myregistry.io/backend:latest"

• Scan Private Registry with Token Auth

  YAML

  scan_config:
    plugins:
      - container_import
      - trigger_discover
      - export
    config:
      container_import:
        name: container
        plugin_config:
          token: "${env:REGISTRY_TOKEN}"
          images:
            - "myregistry.io/myapp:v2.1"

Incremental Scanning

When running through the unified sensor with incremental context enabled, the Container sensor tracks image manifest digests to avoid re-scanning unchanged images.

Refer to Incremental Scanning for more information.

Known Limitations

Image Size

• Description: Very large container images require significant disk space for extraction.

• Workaround: Ensure minimum 2x the total image size is available as disk space.

Transport Protocols

• Description: The sensor supports docker:// transport protocol for pulling images. Other transports may not be supported.

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.

• no container images were stated

  • Cause: The images array is empty or missing.

  • Fix: Add at least one container image reference to the images configuration.

• 401 Unauthorized from registry

  • Cause: Invalid credentials or token for a private registry.

  • Fix: Verify registry credentials are correct. Test with docker pull manually.

• Disk space errors during extraction

  • Cause: Insufficient disk space to extract container layers.

  • Fix: Ensure adequate disk space (2x total image size minimum).

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact credentials)

• Log output

• Container registry details (type, URL)

Contact Support:

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