Network requirements

Outbound

Purpose	Destination	Port	When
Registration	api.nextpki.com	443/TCP, HTTPS	Once, at install
Download and self-update	sensor.nextpki.com	443/TCP, HTTPS	Install, then on the update schedule
Reporting	ingest endpoint from the identity	443/TCP, HTTPS with a client certificate	Every scan cycle

Registration and downloads are ordinary HTTPS on 443, which most networks already allow outbound. All three are outbound only. No inbound connection to the sensor is ever required - do not open a port for it. The local health endpoint binds to loopback by default and should stay there.

Reporting is mutually authenticated: the sensor presents the client certificate it got at registration, over ordinary HTTPS on 443. The edge terminates TLS, verifies that certificate against our internal CA, and passes the verified identity up to the API - the sensor keeps its mTLS identity without a second credential, and there is no special port to open. The sensor verifies the edge with the normal public certificate roots, the same as any HTTPS client.

For the firewall change request

Everything a sensor needs, in the form a change request asks for. Copy it as is.

Direction:  outbound only (no inbound rule required)
Protocol:   TCP 443 (HTTPS)
Source:     <the sensor host>
Destinations:
  api.nextpki.com
  sensor.nextpki.com

Two names, one port, one direction. There is no IP allowlist to maintain: both names sit behind our edge and their addresses can change. If your policy demands addresses rather than names, ask us and we will tell you the current ones - but expect to revisit them.

api.nextpki.com carries both registration and reporting; sensor.nextpki.com serves the download and the signed self-update. If you disable self-update (NEXTPKI_NO_SELF_UPDATE=1, common in banks that ship software through their own distribution), sensor.nextpki.com is only needed at install time and can be closed again afterwards.

Through a corporate proxy

If the sensor host has no direct egress, point it at your proxy. All three outbound paths - registration, reporting and self-update - then use it.

NEXTPKI_PROXY=http://proxy.corp.example:3128

Set it at install time (NEXTPKI_PROXY=... ./install.sh) or afterwards in /etc/nextpki-sensor/env, then restart the service. Basic authentication in the URL works (http://user:password@proxy:3128); the sensor logs the proxy at startup with the credentials removed, so you can confirm it is in play without exposing them.

Do not rely on exporting HTTPS_PROXY in a shell. A systemd or launchd service does not inherit your environment: the manual run would work and the service would silently not. That is why the setting belongs in the service’s own environment file. NEXTPKI_NO_PROXY=1 forces direct egress on a host that has it.

Kerberos or NTLM proxy authentication is not supported. If your proxy requires either, the sensor needs an exception or an authenticating relay in front of it.

If your proxy inspects TLS

This is the case worth checking before you deploy. A proxy can handle HTTPS in two ways:

• CONNECT tunnel (the normal case): the proxy forwards bytes and never sees inside the TLS session. Everything works, including the client certificate.
• TLS interception: the proxy terminates TLS itself and re-encrypts with its own CA. Reporting then fails by design - the interception point cannot present the sensor’s client certificate, so we cannot verify who is reporting.

Interception is not a bug we can work around: the client certificate is the sensor’s identity, and an intermediary that cannot present it is, from our side, indistinguishable from someone else. Exempt api.nextpki.com from TLS interception on the sensor hosts. That is a narrow exception for one hostname, and it is the same exception such proxies already carry for certificate-pinned software.

Inbound to scanned hosts

The sensor connects to the ports you configured on the targets you configured. From the target’s point of view this looks like an ordinary TLS client that disconnects after the handshake.

If your network has intrusion detection, tell it about the sensor before the first sweep. A host opening TLS connections across a whole subnet is exactly the pattern IDS rules are written for, and conservative still means 16 concurrent connections.

Segments with no route outbound

You do not need to grant every sensor host its own internet access. Three ways, in the order most people want them:

Your existing proxy. In most networks this is the answer: the segment has no direct egress, but it does have a proxy. Point --proxy at it (see above) and you are done - nothing else to install.

A sensor as the relay. If there is no proxy, a sensor that does have egress can forward for the others:

# On the host with egress:
nextpki-sensor run --relay-listen 0.0.0.0:8888 --targets ...

# On each sensor without egress:
nextpki-sensor run --proxy http://<relay-host>:8888 --targets ...

The relay is deliberately unexciting. It forwards CONNECT and nothing else, only to the NextPKI endpoints that relay itself is configured with - so a private deployment relays to its own control plane, on its own port, and a request for anywhere else is refused and logged. It never terminates TLS: your sensor’s mTLS session runs through it untouched, end to end, so the relay host never holds anything that would let it read or forge a report. That is the whole design. A relay that terminated would move the trust boundary into your network, and taking over one host would be enough to file whatever it liked.

It is also not a general-purpose proxy, and that is on purpose: an open relay on an internal network gets found and gets used. It caps concurrent tunnels, it refuses ports it was not told about, and it answers anything that is not a CONNECT with a 400.

Or route around it. Put the sensor on a host that has egress and let it scan the segment across the routed boundary, or allow egress from the sensor hosts to the destinations above only - a narrow rule: two names, port 443, outbound.

Whichever you choose, the sensor detail page shows it under Reports via: either the relay or proxy it goes through, or direct. Credentials in a proxy URL are stripped by the sensor before it is sent, so they never reach us.

Verifying what leaves

Once the source is published, you will not have to take the above on trust. The report client is a single file, and the report structure is a small JSON document defined alongside it in the same repository. See data it sends.