Network Discovery Scanner

CertTracker's Network Discovery Scanner sweeps an IP range on your internal network, finds every TLS-bearing service (HTTPS, mail, LDAP, databases, custom-port admin consoles), and lets you add the new endpoints as monitors with one click. It's the fastest way to onboard an environment you didn't build — a fresh acquisition, a customer takeover, or just the corner of your network the previous admin "managed."

The most common outcome of a first run: three to five forgotten certs that have been silently expired for months. Webmin on a backup server, Synology admin on a NAS, vCenter LDAPS, a forgotten Graylog node. None of them flagged by external monitoring because they live behind the firewall; none of them documented because nobody remembered they were issued.

What it does

Given a target spec — a CIDR like 192.168.1.0/24, a hyphen range like 10.0.0.1-50, or a comma-separated mix — the scanner:

1. Port-scans every IP against a configurable port list (defaults cover HTTPS, SMTPS, IMAP/S, POP3/S, LDAPS, and major admin-console ports).
2. Reverse-resolves the IPs that responded so the results show real hostnames.
3. Pulls the leaf certificate from each open port (using the right STARTTLS dance — SMTP EHLO+STARTTLS, IMAP a001 STARTTLS, PostgreSQL SSLRequest, MySQL HandshakeV10, Microsoft SQL Server TDS PRELOGIN, etc).
4. Cross-references existing CertTracker monitors so already-monitored endpoints are marked green and new ones are marked addable.
5. Submits the whole result set to CertTracker via the API, where it persists in scan history and feeds the /discovery web page.

Three scan depths

For a first audit of an unfamiliar network, Standard is the sweet spot — fast enough to run during a planning meeting, complete enough to surface every expired cert.

Running the scanner

Download the compiled binary from the Discovery page in CertTracker — there's a Linux and a Windows tile at the top of the page. Both are self-contained, signed during the build, and need nothing more than your CertTracker API token at runtime.

Windows — desktop app (recommended):

1. Double-click certtracker-scanner-windows.exe to open the scanner.
2. Paste your API token (from Administration → API Tokens). Tick Remember token to store it encrypted for this Windows user so you don't re-paste it next time.
3. Enter a Target — a CIDR (192.168.1.0/24), an IP range, a single host, or a comma-separated list — pick a Depth, and click ▶ Scan.
4. Results appear in the app row-by-row as it scans; with a token set, they also upload into your CertTracker account automatically.

Windows — command line (for automation):

The same .exe also runs headless when you launch it with arguments — handy for scheduled scans (Windows Task Scheduler) or scripting. Double-clicking still opens the desktop app; passing a target runs the scan and exits.

certtracker-scanner-windows.exe 192.168.1.0/24 ^
    --depth standard ^
    --token ct_live_yourActualToken

Run it from an open cmd/PowerShell window so the progress and summary print back to that terminal. All the flags below (--depth, --ports, --profile, --no-submit, etc.) work the same on Windows and Linux.

Linux / macOS — command line:

chmod +x certtracker-scanner-linux
./certtracker-scanner-linux 192.168.1.0/24 \
    --depth standard \
    --token ct_live_yourActualToken

Mint an API token under Administration → API Tokens before the first run. The scanner checks the token against the server on launch, so a revoked or wrong-plan token fails immediately rather than after a 30-minute scan.

Developer note: you can also run the source directly via python3 -m scanner … from the CertTracker repo (the cloud build pipeline uses exactly this entry point). The compiled binary is the supported path for customers.

You'll see phased progress on stderr (port scan → reverse DNS → cert pull) and the final scan summary on stdout:

# scanner 0.3.0 — scanning 254 IPs × 14 ports = 3556 probes
# portscan   3556/3556
# rdns       39/39
# certpull   34/34
# submitting to https://certtracker.12squared.com/api/v1/discovery/scans …
# ── summary ─────────────────────────────────────────────
#   cert_found           34
#   handshake_failed      4
#   no_cert               1
{"ok": true, "scan_id": 12, "totals": {"certs_found": 34, "new_monitors_eligible": 31, ...}}

The scan_id at the end is your handle into the web UI.

Working with results in the web UI

Browse to Discovery in the top nav. The list view shows every past scan newest-first with totals. Click any row's View → to drill into the per-host result table.

Each row is color-coded:

• Green — cert_found and already a CertTracker monitor. Nothing to do.
• Orange — cert_found and not monitored. Checkbox enabled. These are your "I had no idea" findings.
• Red — handshake_failed. Server is up on that port but TLS won't negotiate. Often a misconfigured cipher or a non-TLS service on a TLS-looking port. Worth investigating but not addable as a monitor.
• Grey — no_cert (port responded but no TLS) or port_open (Quick mode didn't try to pull a cert).

Select the orange rows you want to monitor (or click Select all addable), pick a poller and polling interval from the bottom bar, and + Add selected. The new monitors land on the Monitors page within seconds and get their first poll immediately.

Scan-depth + port profiles

The default port set covers four profiles:

Override with --profile web,mail,ldap,database to include the database profile, or pass --ports 443,8443,10000 for a custom list. Unknown ports (anything not in the protocol map) get probed with direct TLS — handy for one-off Webmin (10000), vendor admin consoles, mgmt VLANs.

Security and etiquette

• The scanner sweeps every IP × every port so a /24 with 14 ports is 3,556 connection attempts in roughly 30 minutes. That's slower than nmap (the default concurrency is 50 in-flight probes) but it's still scanner traffic. Run it during a maintenance window or coordinate with your security team if they have IDS rules that fire on outbound TCP scans.
• The TCP connect is benign — we never send TLS bytes to a port we don't think is TLS. The cert pull is just the standard handshake every real client does.
• MySQL/MariaDB pre-handshake rejection can mask cert presence. See Mail, LDAP & Database TLS for the host-grant gotcha (MySQL refuses unknown client hosts before sending its handshake, which looks like "no cert" to the scanner).
• CertTracker stores the full scan envelope in its DB so you can revisit /discovery/N weeks later, but raw scan data never leaves the customer's tenant. There's no cross-tenant cert observation sharing.

Permissions and plans

The scanner uses the standard CertTracker customer API token. Generate one under Administration → API Tokens. The Discovery feature is included with Business and Enterprise plans; lower tiers get HTTP 402 from the API and a friendly upgrade redirect from /discovery.

Adding a custom port permanently

If your environment has services on a port that isn't in the default profiles, add it via --ports for the scan. Once the cert lands in discovery_results, the bulk-add will set up the monitor on whatever port it found — no further config needed. Future scans will continue to pick up that port if you include it in --ports again, or add it to your team's saved scan recipe.

What this doesn't do

• It doesn't ping or fingerprint anything beyond TCP-connect + (optionally) TLS handshake. No service banner grabs, no OS detection, no version enumeration.
• It doesn't probe ports outside the list you give it (or the default set).
• It doesn't run continuously — you run it on demand. Scheduled re-runs are easy to wire up via the command line (cron on Linux/macOS, Task Scheduler on Windows — the Windows .exe takes the same flags); a built-in "rescan every N days" is on the roadmap.
• It doesn't auto-add monitors. Findings are always one explicit click — no chance of a scan surprising you with 50 new monitor rows you didn't want.