Local scan

Introduction

Local scan discovery uses the Horizon Client agent (horizon-cli) to inventory the certificates present on the machine it runs on — files on disk and, on Windows, the certificate stores — and feed them back to Horizon. It's the simplest way to find certificates on a host without opening network access to it.

This guide walks through configuring a discovery campaign, running a local scan, viewing the results, and the advanced options for tuning what gets scanned and on what schedule.

Prerequisites

The agent must be installed and configured on the host you want to scan before you start. Follow Installing the Horizon Client to install the agent and create its configuration (API ID/key and endpoint), then confirm it can reach Horizon:

horizon-cli ping

If ping succeeds, the agent is ready to run scans.

Configure the campaign

A discovery campaign is the object in Horizon that scan results are fed into. Create it in the Horizon web interface, under the Discovery section, before running the agent.

When creating the campaign, set:

• Name — a unique name. It must not contain dots (for example local-scan-servers, not local.scan). The agent references the campaign by this name.
• Description — optional, for your own reference.
• Enabled — leave the campaign enabled so it can receive results.
• Authorization levels — who is allowed to search the campaign's results and who is allowed to feed it. Each can be set to everyone, authenticated, or authorized. Make sure the account the agent authenticates as is allowed to feed the campaign.
• Grading policies (optional) — attach one or more grading policies so that discovered certificates are graded automatically as they come in. Without a grading policy on the campaign, discovered certificates are recorded but left ungraded.

The Hosts and Ports fields apply to network scans and aren't needed for a local scan — a local scan always targets the machine the agent runs on.

Run the local scan

On the host where the agent is installed, run the local scan and point it at your campaign:

horizon-cli localscan --campaign=<campaign-name>

Run the command with root (Linux) or administrator (Windows) privileges — without them, the agent will likely be unable to read all certificate locations and may miss certificates.

By default the scan looks in commonly used locations:

• Linux/Unix: /usr/local/etc, /etc, and /opt
• Windows: the user store, the machine store, ProgramData, Program Files, and Program Files (x86)

A certificate is reported when it is a PEM- or DER-encoded certificate file in a scanned path, or (Windows only) is held in a Machine or User "MY" certificate store. CA certificates are skipped.

See the results in the dashboard

Once the scan finishes, the agent feeds its findings to Horizon:

• The run is recorded as discovery events (success, warning, or failure, according to the campaign's event settings), so you can confirm the scan completed and review any warnings.
• The discovered certificates appear in Horizon with their discovery metadata (the host they were found on and where), and in your certificate inventory.
• If you attached grading policies to the campaign, each discovered certificate shows its grade, so you can immediately spot weak or non-compliant certificates.

To track discovery over time, add a certificate or discovery chart to a dashboard in Horizon — for example, discovered certificates by grade or by expiry window — so the inventory stays visible at a glance.

Advanced local discovery

Scan keystores

To inventory certificates inside keystores, provide the passwords to try when the agent encounters one:

horizon-cli localscan --campaign=<campaign-name> --containers-passwords=<password1>,<password2>

If a keystore can't be opened, the agent raises a warning event with code HCL-LOCALSCAN-KS-001.

Control which folders are scanned

To skip the default locations (for example when you only want to scan specific configured paths), use:

horizon-cli localscan --campaign=<campaign-name> --exclude-default-paths

If a configured certificate path contains an environment variable, the agent raises a warning event with code HCL-LOCALSCAN-ENV-001.

Schedule recurring scans

Rather than running scans by hand, create a periodic task so the agent scans on a schedule:

horizon-cli localscan --campaign=<campaign-name> --create-periodic-task --period=monthly

The --period value can be:

• daily — every day between 00:00–04:00 UTC
• weekly — every Sunday between 00:00–04:00 UTC
• monthly — the first day of each month between 00:00–04:00 UTC

On Linux you can run the task under a specific account with --user:

horizon-cli localscan --campaign=<campaign-name> --create-periodic-task --period=monthly --user=horizon-cli

To remove a scheduled task:

horizon-cli localscan --campaign=<campaign-name> --remove-periodic-task

Get command help

Every command supports --help for the full list of options:

horizon-cli localscan --help