diff --git a/docs/concepts.md b/docs/concepts.md index c88213e..f4948ad 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -246,10 +246,12 @@ Certificate discovery is the process of automatically finding existing certifica **How it works:** There are two discovery modes. *Filesystem discovery* — agents scan configured directories (configured via `CERTCTL_DISCOVERY_DIRS`) for certificate files. On startup and every 6 hours, the agent walks directories recursively, parses PEM and DER files, extracts metadata, and reports findings to the control plane. *Network discovery* — the control plane itself probes TLS endpoints across configured CIDR ranges and ports (enabled via `CERTCTL_NETWORK_SCAN_ENABLED=true`). It connects to each endpoint, extracts certificates from the TLS handshake, and feeds results into the same discovery pipeline. This finds certificates on services you may not have agents on. In both cases, the server deduplicates by fingerprint and stores discovered certs with a status: **Unmanaged** (discovered but not yet managed), **Managed** (linked to a control plane cert), or **Dismissed** (operator decided not to manage it). This gives you a three-step triage workflow: -1. **Discover** — Agents find all existing certs on your infrastructure -2. **Triage** — Operators review discoveries and decide: claim it (enroll for management), or dismiss it (not worth managing) +1. **Discover** — Agents scan filesystems and the server probes network endpoints to find all existing certs +2. **Triage** — Operators review discoveries in the **Discovery** dashboard page and decide: claim it (link to a managed certificate) or dismiss it (not worth managing). The dashboard shows a summary stats bar (Unmanaged/Managed/Dismissed counts), filters by status and agent, and provides one-click claim and dismiss actions. 3. **Baseline** — Once triaged, you have a complete baseline of what's deployed, what you're managing, and what's unmanaged +Network scan targets are managed from the **Network Scans** dashboard page — create CIDR ranges and ports to probe, enable/disable targets, trigger on-demand scans, and view results. Discovered certificates from network scans appear in the same Discovery triage page alongside filesystem discoveries. + This is a prerequisite for multi-CA migration, compliance audits, and building confidence that you've found all the certificates that matter. ### Observability diff --git a/docs/connectors.md b/docs/connectors.md index ecf7fe8..edc4b5f 100644 --- a/docs/connectors.md +++ b/docs/connectors.md @@ -716,7 +716,7 @@ The agent scans these directories on startup and every 6 hours, looking for cert 1. **Scan**: Agent recursively walks directories, extracts certificates 2. **Deduplicate**: Control plane deduplicates by SHA-256 fingerprint (same cert in multiple locations is one discovery) 3. **Store**: Discovered certificates stored with metadata (agent ID, file path, found date, fingerprint) -4. **Triage**: Operators query discovered certs via API, claim to link to managed certificates, or dismiss false positives +4. **Triage**: Operators review discovered certs in the **Discovery** dashboard page (or via API) — claim to link to managed certificates, or dismiss false positives. The dashboard shows summary stats, filters by status and agent, and provides one-click claim/dismiss actions. ### API Endpoints @@ -764,10 +764,10 @@ export CERTCTL_NETWORK_SCAN_INTERVAL=6h # default ### Creating Scan Targets -Network scan targets define which CIDR ranges and ports to probe: +Network scan targets can be managed from the **Network Scans** dashboard page (create, edit, enable/disable, trigger on-demand scans) or via the API. Targets define which CIDR ranges and ports to probe: ```bash -# Create a scan target for your internal network +# Create a scan target for your internal network (or use the dashboard's "+ New Target" button) curl -s -X POST http://localhost:8443/api/v1/network-scan-targets \ -H "Content-Type: application/json" \ -d '{ @@ -787,7 +787,7 @@ curl -s -X POST http://localhost:8443/api/v1/network-scan-targets \ 3. **Extract**: Certificate metadata extracted from TLS handshake (CN, SANs, serial, issuer, key info, fingerprint) 4. **Pipeline**: Results fed into the same `DiscoveryService.ProcessDiscoveryReport()` as filesystem discovery 5. **Deduplicate**: Sentinel agent ID (`server-scanner`) with source_path as `ip:port` ensures proper dedup -6. **Triage**: Discovered certs appear in `GET /api/v1/discovered-certificates` with `agent_id=server-scanner` +6. **Triage**: Discovered certs appear in the **Discovery** dashboard page (and via `GET /api/v1/discovered-certificates`) with `agent_id=server-scanner` ### API Endpoints