Certificate Discovery

Certificate Discovery helps you continuously locate and inventory certificates across your environments by scanning targets such as individual IPs, CIDR ranges, and DNS names. You can configure discovery to probe specific ports or port ranges, enabling coverage for both standard and custom TLS deployments.

When a certificate is found, Akeyless automatically creates a corresponding certificate record with all available metadata, including where it was discovered (target and endpoint details) and the certificate’s key attributes. You can also predefine expiration event settings so newly discovered certificates are immediately tracked and monitored without manual onboarding.

Certificate Discovery uses the Akeyless Gateway configuration management endpoint (:8000). If logs show akeyless-api-proxy, treat that as an internal Gateway component indicator, not as a standalone compatibility verdict.

Certificate Discovery visibility in the Akeyless Console depends on account permissions and enabled product capabilities.

Discovery Behavior by Source Type

Certificate Discovery behavior depends on the source type:

• Public domain sources use public certificate transparency data and certificate authority logs.
• Internal domain sources are queried directly by fully qualified domain name (FQDN).
• Internal subdomains must be provided explicitly. Discovery does not infer unregistered private subdomains.
• IP and CIDR sources follow direct network-based discovery from the gateway.

For internal and network-based sources, the gateway must have network and DNS access to each target endpoint.

Running a Certificate Discovery with the CLI

To run a certificate discovery using the CLI, run the following command:

akeyless certificate-discovery \
--hosts <IPs, CIDR ranges, or DNS names> \
--port-ranges[=443] <80,8080-8085> \
--target-location 'Discovery-Folder' \
--gateway-url 'https://<Your-Akeyless-GW-URL>:8000' \
--debug

Where:

• hosts: Required, A comma-separated list of IPs, CIDR ranges, or DNS names to scan.

• port-ranges[=443]: A comma-separated list of port ranges. Example: 80, 8080-8085.

• target-location: Required, The folder the certificates that were found in the scan will be saved at.

• expiration-event-in: How many days before the expiration of the certificate would you like to be notified. To specify multiple events, use argument multiple times: --expiration-event-in 1 --expiration-event-in 5.

• debug: Optional, Enables verbose troubleshooting output. Debug details are printed with the CLI command output stream in the terminal where the command runs. Use this flag to expose per-target processing details, endpoint connection attempts, and error context that is not shown in standard output. For runtime-side context, also review Gateway container logs.

UI and CLI field mapping

Use the following mapping when translating Console fields to CLI flags:

Setting a Certificate Discovery in the Akeyless Console

1. Log in to the Akeyless Console, and go to Discovery & Migration, then New, then Certificate Discovery.
2. Define a Name for the certificate discovery, and specify the Target Location as a path to the virtual folder where you want the scanned certificates to be saved in. If the folder does not exist, it will be created together with the scanned certificates.
3. Add the Sources of the scan, such as: IPs, CIDR ranges, or DNS names
4. Add the relevant ports, the default value is 443.
5. Press Finish.

Run the Certificate Discovery

To run the discovery, select the discovery item and choose Action Menu, then Start Scan. If the scan completes successfully, a new folder will appear under Items containing all the certificates that were found.

Troubleshooting Certificate Discovery

Use the following checks when discovery results are incomplete or unclear:

1. Confirm deployment type. Verify that the Akeyless Gateway has the configuration management endpoint (:8000) available.
2. Confirm network path from the gateway. Discovery traffic originates from the gateway container, not from the local client session.
3. Interpret akeyless-api-proxy version lines in logs as component-level information. Those lines alone do not indicate that the deployment is unsupported for discovery.
4. Check discovery and migration logs in the gateway Docker container:

# 1) Identify the Gateway container
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# 2) Review runtime logs from the container
docker logs <gateway-container-name> --tail 500

# 3) Follow live logs while running a discovery job
docker logs -f <gateway-container-name>

# 4) Search for discovery and migration-related entries from inside the container
docker exec -it <gateway-container-name> sh -lc "grep -RinE 'discovery|migration|certificate-discovery|error|failed' /var/akeyless 2>/dev/null | tail -n 200"

Focus on timestamp alignment between command execution and log entries, then capture relevant error lines for triage.
5. Run discovery with debug output:

akeyless certificate-discovery \
--hosts <IPs, CIDR ranges, or DNS names> \
--port-ranges[=443] <80,8080-8085> \
--target-location '<target-location>' \
--gateway-url 'https://<your-akeyless-gw-url>:8000' \
--debug

Use debug mode to correlate CLI output with Gateway log timestamps and isolate whether failures come from DNS resolution, network connectivity, TLS handshake, or scan target processing.

1. Interpret the discovery output counters. The CLI reports: Certificate discovery successfully finished. X new certificates, Y updated certificates, Z hosts, W failed. Each counter represents:
   • X (new): Newly discovered certificates that were created in Akeyless
   • Y (updated): Existing certificates that were found again and updated with new scan data
   • Z (hosts): Total number of targets that were scanned
   • W (failed): Targets that failed during processing. This does not indicate certificate import failures, but rather targets where the scan itself failed (DNS resolution, network connectivity, TLS errors, or timeout).
2. {#ai-insights-alt} Use AI Insights in the Active Directory migration flow when local file system certificate discovery is required for internal processes that are not reachable over the network. AI Insights enables natural-language assisted discovery and can help identify certificates on systems without direct network access by leveraging the --ai-certificate-discovery flag during migration configuration.

ℹ️

Note: Discovery and migration logs are currently written inside the gateway container.