Ports and networking

This page is for the people who run your network: what dpndncY needs opened, what it connects to, and why. Everything here was checked against a running installation.

#The short version

• dpndncY needs two web addresses and one outbound path to the internet (or none, if air-gapped).
• The two addresses are served on port 443 (HTTPS) by a reverse proxy. Nothing else is exposed.
• One address is for people (the console). The other is for machines (the CLI, CI pipelines and agents).
• Source code is uploaded by your pipelines to your own server. It does not leave your network.

#Inbound: what to open

That is the complete list. In particular, never publish ports 3000 or 3001 to the network: they are the application's own internal ports and speak plain HTTP.

#The two addresses

Choose two DNS names that point at the machine (or at your load balancer or ingress):

Why two? The web console serves the browser and does not pass other clients' requests through to the API. A deployment that publishes only the console works for people but pipelines and agents cannot reach it. Publishing the API on its own name is also what lets you restrict it separately, for example to your runners' address ranges.

   People ──── HTTPS 443 ───►  dpndncy.example.com  ──┐
                                                       ├─► reverse proxy ─┬─► console   :3000
   CLI · CI · agents ─ HTTPS 443 ─► api.dpndncy.example.com ─┘            └─► API       :3001
                                                                              │
                                                                    one data volume (database)

#Inside the machine (never exposed)

With Docker Compose these stay on a private container network. With Kubernetes they are Service ports reachable only through the Ingress.

#Outbound: what dpndncY connects to

Scanning needs vulnerability data and package information, so the machine makes outbound HTTPS (port 443) connections. Only package names and versions are sent. Your source code is never sent. If your network blocks the internet, use the offline mode and none of this applies (Running dpndncY without internet access (air-gapped)).

The product sends no telemetry. A daily licence check-in (licence id and totals only) is off unless you turn it on, and is always off in air-gapped mode.

#If your network uses a proxy

Set the usual proxy variables on the container and dpndncY will use them:

HTTPS_PROXY=http://proxy.corp.example:3128
HTTP_PROXY=http://proxy.corp.example:3128
NO_PROXY=.corp.example,10.0.0.0/8

The container starts with proxy support switched on when it sees these, and automatically keeps traffic to itself (127.0.0.1, localhost) out of the proxy. Allow the destinations in the table above on the proxy. If the proxy re-signs TLS traffic, the machine must trust its certificate authority. For Docker Compose put the variables in .env; for Kubernetes use extraEnv in the Helm values.

#Certificates

CI runners must trust whichever authority signs the API certificate. The CLI is a Node program, so NODE_EXTRA_CA_CERTS=/path/to/ca.pem points it at an extra certificate bundle.

#Load balancers and proxies in front

If a load balancer, WAF or ingress sits in front, set these:

#A note to send your network team

We are installing dpndncY, a software security scanner, on one server. Please publish two HTTPS names, dpndncy.<ours> and api.dpndncy.<ours>, both pointing at it, on TCP 443 (and TCP 80 if we use Let's Encrypt). Do not publish any other port. Allow the server to make outbound HTTPS to api.osv.dev, services.nvd.nist.gov, api.github.com, www.cisa.gov, and the package registries listed in the installation guide, or provide a proxy. Allow our CI runners to reach api.dpndncy.<ours> on TCP 443. Browsers reach dpndncy.<ours>.

#Checking it

From a laptop and from a CI runner:

curl -sS https://api.dpndncy.example.com/health          # {"status":"ok","version":"2.9.0",...}
curl -sSI https://dpndncy.example.com/login | head -1    # HTTP/2 200
curl -sS -o /dev/null -w "%{http_code}\n" https://api.dpndncy.example.com/api/scan-jobs    # 401: reachable, needs a token

#Mistakes we see