Sensor configuration

The sensor is configured entirely by command-line flags and environment variables - there is no configuration file yet. Every flag has an environment equivalent, which is usually what you want in a service unit.

nextpki-sensor --help is authoritative; this page explains the ones with consequences.

Global

Flag	Environment	Default	Notes
--data-dir	NEXTPKI_DATA_DIR	platform-specific	Where the mTLS identity lives. See install
--log-level	NEXTPKI_LOG_LEVEL	info	trace, debug, info, warn, error
--log-format	NEXTPKI_LOG_FORMAT	json	json or text. Use text interactively

bootstrap

Run once, to exchange a token for an identity.

Flag	Environment	Notes
--token	NEXTPKI_BOOTSTRAP_TOKEN	Single-use, short-lived
--endpoint	NEXTPKI_BOOTSTRAP_ENDPOINT	Registration endpoint, host:9090
--machine-id	NEXTPKI_MACHINE_ID	Identifies this sensor. Must match the token’s hint if one was set

Pass the token by environment variable rather than on the command line where you can - a command line is visible in ps to every user on the host.

run

Flag	Environment	Default	Notes
--ingest-endpoint	NEXTPKI_INGEST_ENDPOINT	from identity	Override the reporting endpoint
--health-addr	NEXTPKI_HEALTH_ADDR	127.0.0.1:18080	Local /healthz. Keep it on loopback
--scan-profile	NEXTPKI_SCAN_PROFILE	conservative	See below
--targets	NEXTPKI_TARGETS	-	Comma-separated hosts, host:port, or IPv4 CIDRs
--include	NEXTPKI_INCLUDE	-	Restrict to these after expansion
--exclude	NEXTPKI_EXCLUDE	-	Never contacted, even if included elsewhere
--ports	NEXTPKI_PORTS	443, 465, 587, 993, 995, 25, 110, 143	Ports to try per host
--scan-interval-secs	NEXTPKI_SCAN_INTERVAL_SECS	3600	Seconds between full sweeps
--probe-timeout-ms	NEXTPKI_PROBE_TIMEOUT_MS	3000	Per-probe timeout

Scan profiles

The profile sets concurrency, and the default is deliberately timid. A discovery agent that saturates a customer’s firewall state table is a defect.

Profile	Concurrent connections	When
conservative	16	Default. Start here, always
standard	64	After a clean full sweep, if coverage is too slow
aggressive	256	Large flat networks with known-good middleboxes

A /24 at conservative with eight ports completes in a couple of minutes. The reason to raise it is a /16, not impatience.

Watch stateful firewalls and IDS: 256 concurrent TLS handshakes from one host is indistinguishable from a scan, because it is one. Tell the security team before raising the profile.

Excludes are absolute

--exclude wins over everything. An excluded address is never contacted and never reported. Use it for:

• Anything fragile - legacy SCADA, medical devices, embedded controllers that fall over on an unexpected handshake.
• Ranges whose hostnames are themselves sensitive, since observed hostnames are transmitted.
• Honeypots and IDS decoys, unless you enjoy the phone call.

Interval

The default hour is a reasonable compromise. Certificate estates change on the scale of days, so a sweep every hour is plenty to keep an inventory current, and frequent enough to notice a new deployment the same working day.

Do not set it very low to get faster change detection. The sensor is not a monitoring probe, and a tight interval multiplies scan traffic without improving the inventory.