Vantage Collector

1Overview

The Vantage Collector is a self-contained appliance that receives flow telemetry from distributed sensors, folds it into a live dependency map of the network, and turns that map into segmentation policy — the passive-observation workflow of an Application Dependency Mapping (ADM) product, running on hardware you already own.

1.1About This Guide

This guide describes how to deploy, configure, verify and operate a single Collector node. Commands are shown for a Linux host running Docker Compose. Throughout, the following conventions apply:

• Monospace text such as ADM_INGEST_PORT denotes a variable, file, port or literal command.
• A leading $ in a code block marks a shell prompt; unprefixed lines are command output.
• Callouts labeled Note, Caution and Warning carry information that affects correctness or security.

1.2Product Overview

The Collector is a separate product, not a client of the central management portal ("Switchboard"). It maintains its own login, its own user store, its own session secret and its own database. The only traffic between the two is a periodic, machine-to-machine identity-sync pull that copies sensor identities and the fleet trust bundle down to the Collector. The Collector never signs certificates and never opens a session against the portal.

1.3Features at a Glance

2Architecture

2.1System Components

A deployment consists of the Collector node, one or more sensors, and the central Switchboard portal that owns the CA. The Collector runs a single container exposing two listeners: a human-facing login and dashboard, and a sensor-facing mTLS ingest.

Two sensor roles feed the Collector. The Vantage sensor is the primary telemetry source; the Vantage Deep node is an optional companion for packet retrieval. Existing network gear can also export flows directly, with no sensor to install.

A Vantage sensor tells you a dependency exists; a Vantage Deep node keeps the packets, so you can answer the question a flow map alone cannot: show me what actually crossed the wire.

          # control plane + CA (separate host)
          Switchboard :8443  ──────────────┐  identity-sync (pull, cron, every 5 min)
                                            │  { ca_bundle_pem, probes, probe_certs }
                                            ▼
  Sensors ──mTLS :8843──►  ┌──────────────────────────────────┐
  (Vantage flow sensor,    │        Vantage Collector          │
   Vantage Deep node,      │  :443   login + dashboard (humans)│
   IPFIX/NetFlow gear)      │  :8843  sensor mTLS flow ingest   │
  Operator ──HTTPS :443──► │  SQLite (WAL)  data/adm/adm.db     │
                           └──────────────────────────────────┘

2.2Flow Data Path

Raw flows are never persisted. At ingest, each batch is folded into dependency edges — one row per ordered (source, destination, port, protocol) tuple — and the individual flows are discarded. This reduces the volume by roughly four orders of magnitude while directly answering the question operators ask: what talks to what, on what port, since when. Packet-level detail is served separately from a Vantage Deep node's capture ring.

2.3Trust Model

Two listeners, two authentication models:

3Prerequisites

3.1Host Requirements

• A Linux host with Docker Engine and the Compose plugin.
• Small-tier sizing (up to ~8 sensors): 4 vCPU / 8 GB RAM. The container is capped at 6 GB.
• Disk sized for flow-edge history in data/adm/adm.db (WAL); retention defaults keep 30 days of hourly buckets.
• Outbound reachability to Switchboard for identity-sync, and inbound reachability from sensors on the ingest port.

3.2Port and Protocol Matrix

3.3Certificates and Trust Bundle

The Collector requires a server certificate/key pair for both listeners (mounted read-only), and the fleet CA bundle to validate sensor client certificates. The bundle is delivered by the identity-sync job to data/fleet-ca-bundle.pem and referenced by the ADM_CA_BUNDLE_FILE variable.

4Deploying the Collector

4.1Procedure

1. Provide certificates and configuration

   Place the server certificate and key under certs/ and ingest-certs/. Create sync_config.json with the Switchboard URL and the collector-sync token.

   # sync_config.json (root-only; keeps the token out of docker inspect)
   {"switchboard_url": "https://switchboard.example.net:8443", "token": "<collector-sync-token>"}

2. Build and start the container

   $ docker compose build
   $ docker compose up -d

3. Schedule identity-sync on the host

   Run the sync script from host cron (not inside the container) so it writes into the bind-mounted data/ directory.

   # /etc/cron.d — every 5 minutes
   */5 * * * * cd /opt/vantage-collector && /usr/bin/python3 sync_identity.py >> /var/log/vantage-sync.log 2>&1

4. Create the first administrator

   $ docker compose exec collector python -m backend.auth add admin '<password>' admin

4.2First-Boot Behavior

On first start the container generates a per-deployment session-signing secret and persists it to collector_secret.key (mode 0600). This value is unique to the node and is never shared with Switchboard, so a session cookie from one is never valid on the other.

5Configuration Reference

5.1Environment Variables

All runtime configuration is supplied through environment variables in the Compose file. Defaults are chosen for a single-node small-tier deployment.

5.2User Accounts

Users are stored locally with bcrypt-hashed passwords. Two roles exist: admin (full access) and operator. Manage accounts from the dashboard, or from the CLI:

$ python -m backend.auth add <username> <password> [admin|operator]

5.3Sensor Configuration

A single schema is the source of truth for everything a sensor can be configured with; the dashboard form, the installer and the agent all read it. Configuration is applied from the sensor's page in the dashboard, or by API:

PATCH /api/adm/probes/<probe-id>/config      # validated before it is saved
POST  /api/adm/probes/<probe-id>/validate    # dry-run: errors, warnings, sizing

Validation runs first, so the dashboard cannot save a configuration the agent would refuse to run. Use the validate call to preview errors, warnings and the sizing estimate before committing.

5.3.1 Capture modes

How the mirrored traffic physically reaches the sensor. Choose the mode your switch supports:

5.3.2 Interface layout rule

On a Raspberry Pi Vantage sensor the roles are fixed by default: capture on the onboard 1 GbE (eth0/end0, on the RP1 native path), management on the USB NIC (enx<MAC> or eth1). The capture NIC runs promiscuous, carries no address and has offloads disabled. Capture on the USB NIC is rejected unless interfaces_override is set — the escape hatch for a board whose second onboard NIC merely happens to be named like a USB one.

5.3.3 Key variables

5.3.4 Switch-side mirror (SPAN)

A Vantage sensor is passive: the switch must mirror the traffic to it. Connect the SPAN destination port to the sensor's onboard capture NIC.

Cisco IOS / IOS-XE (Catalyst)

monitor session 1 source interface GigabitEthernet1/0/1 - 24 both
monitor session 1 destination interface GigabitEthernet1/0/48

Cisco NX-OS (Nexus)

monitor session 1
  source interface Ethernet1/1-24 both
  destination interface Ethernet1/48
  no shut

Arista EOS

monitor session VANTAGE source Ethernet1 - 24
monitor session VANTAGE destination Ethernet48

5.3.5 Vantage Deep (pcap-node)

A Vantage Deep node is configured for retention rather than mirror layout. The relevant variables are pcapnode_capture_nic, pcapnode_backend (dumpcap is the implemented software backend), pcapnode_retention_hours (default 6) and pcapnode_link_gbps. It has no inbound channel from the Collector: it polls for capture jobs on its heartbeat and uploads the extracted pcap back.

5.4IPFIX / NetFlow Exporter Configuration

Network gear that already exports flow records can feed the map with no sensor to install. Enable the collector with ADM_IPFIX=1 (see Section 9 for the security implications) and point exporters at UDP 4739. Flows are attributed to ipfix:<exporter-ip> so their provenance stays distinct from a trusted sensor's.

Cisco IOS-XE — Flexible NetFlow (Catalyst)

flow record VANTAGE-REC
 match ipv4 source address
 match ipv4 destination address
 match transport source-port
 match transport destination-port
 match ipv4 protocol
 collect counter bytes long
 collect counter packets long
 collect timestamp sys-uptime first
 collect timestamp sys-uptime last
!
flow exporter VANTAGE-EXP
 destination <collector-ip>
 source Loopback0
 transport udp 4739
 export-protocol ipfix            ! or netflow-v9
 template data timeout 60
!
flow monitor VANTAGE-MON
 exporter VANTAGE-EXP
 record VANTAGE-REC
 cache timeout active 60
!
interface GigabitEthernet1/0/1
 ip flow monitor VANTAGE-MON input
 ip flow monitor VANTAGE-MON output

Cisco NX-OS (Nexus)

feature netflow
!
flow record VANTAGE-REC
  match ipv4 source address
  match ipv4 destination address
  match transport source-port
  match transport destination-port
  match ip protocol
  collect counter bytes
  collect counter packets
  collect timestamp sys-uptime first
  collect timestamp sys-uptime last
!
flow exporter VANTAGE-EXP
  destination <collector-ip> use-vrf management
  source mgmt0
  transport udp 4739
  version 9
!
flow monitor VANTAGE-MON
  record VANTAGE-REC
  exporter VANTAGE-EXP
!
interface Ethernet1/1
  ip flow monitor VANTAGE-MON input

Arista EOS — hardware flow tracking (IPFIX)

flow tracking hardware
   tracker VANTAGE
      exporter VANTAGE-EXP
         collector <collector-ip> port 4739
         local interface Management1
         template interval 60000
      record export on inactive timeout 15000
      record export on interval 60000
   no shutdown
!
interface Ethernet1
   flow tracker hardware VANTAGE

Fortinet FortiGate (FortiOS, NetFlow v9)

config system netflow
    set collector-ip <collector-ip>
    set collector-port 4739
    set source-ip <mgmt-ip>
    set active-flow-timeout 60
    set inactive-flow-timeout 15
end
config system interface
    edit "port1"
        set netflow-sampler both
    next
end

HPE Comware — NetStream (FlexNetwork / 5900-series)

ip netstream export version 9
ip netstream export host <collector-ip> 4739
ip netstream export source interface M-GigabitEthernet0/0/0
!
interface Ten-GigabitEthernet1/0/1
 ip netstream inbound
 ip netstream outbound

HPE / Aruba — sFlow-based platforms

6Verifying the Deployment

6.1Health Check

The Collector exposes an unauthenticated liveness endpoint. It returns HTTP 200 when ingest is listening (or deliberately disabled), and HTTP 503 when the mTLS listener is enabled but failed to start — the exact condition a missing CA bundle produces.

$ curl -sk https://localhost:443/healthz
{"ok":true,"ingest":{"enabled":true,"listening":true,"port":8843,
 "client_certs_required":true}}

The Compose service wires this endpoint to a container health check, so the runtime reports the container unhealthy whenever sensors cannot deliver flows:

$ docker inspect --format '{{.State.Health.Status}}' vantage-collector
healthy

6.2Sensor Ingest

Confirm the listener started (client certificates required) in the container log:

$ docker compose logs collector | grep mTLS
[adm_ingest_mtls] INFO ingest mTLS listening on :8843 (client certificates required)

6.3Identity Sync

A successful run reports the counts pulled and the bundle size:

$ tail -n1 /var/log/vantage-sync.log
identity-sync ok: 12 probes, 12 certs, bundle 3805 bytes

7Administration

7.1Backup and Export

A backup captures exactly what this node owns: its adm.db, its user store and the synced CA trust bundle. It deliberately excludes the session secret and all private-key material — a stolen backup cannot forge a session or a certificate. Backups can be downloaded, or pushed to a remote host over SCP or TFTP from the Backup page.

7.2Sensor Lifecycle

Sensors are registered, enrolled and have their certificates rotated on Switchboard, which holds the CA. The resulting identities and certificate-revocation state reach the Collector through identity-sync. To retire a sensor, revoke it on Switchboard; the Collector stops accepting its certificate after the next sync.

7.3Onboarding a Sensor Without Switchboard

Enrollment and signing normally happen on Switchboard (Section 1.2). A Collector deployed on its own has no Switchboard CA — but it can still onboard Vantage sensors, two ways, both from the dashboard Onboarding page (or the API). In both, the sensor's private key never leaves the sensor: only a CSR is signed or a signed certificate is registered.

Option A — the Collector's own CA (recommended)

Let the Collector be its own CA and sign sensor CSRs directly — no external CA to run.

1. Initialise the CA (once)

   Created and trusted at ingest automatically.

   POST /api/ca/init

2. Create the probe

   Under Sensors. With ADM_STANDALONE=1 (the appliance default), the Switchboard-only fields are not required.

3. Generate a CSR on the sensor

   openssl req -newkey rsa:2048 -nodes -keyout sensor.key \
     -out sensor.csr -subj "/CN=<probe-id>"

4. Sign & register the CSR

   POST /api/sensors/<probe-id>/issue    {"csr_pem": "<CSR PEM>"}

   Returns the signed certificate. The sensor presents sensor.key + that certificate and is accepted at mTLS ingest.

Option B — bring your own CA

If you already run a CA, sign the CSR with it offline and register the result.

1. Install the CA trust bundle

   POST /api/ca-bundle    {"bundle_pem": "<your CA cert(s) PEM>"}

2. Create the probe, then register the signed cert

   Sign the sensor CSR with your CA offline, then:

   POST /api/sensors/<probe-id>/cert    {"cert_pem": "<signed cert PEM>"}

In both options the certificate serial is normalised exactly as the ingest reads it, so case and leading-zero encoding never cause a false rejection.

Rotation and revocation

Manage a sensor's certificates from the Onboarding → Manage sensor certificates panel, or the API:

GET  /api/sensors/<probe-id>/certs                  # list serials, expiry, status
POST /api/sensors/<probe-id>/certs/<serial>/revoke   # revoke one certificate
POST /api/sensors/<probe-id>/revoke                 # revoke the whole sensor
POST /api/sensors/<probe-id>/reactivate             # un-park a revoked sensor

To rotate: issue a new certificate (Option A or B) and confirm the sensor is using it — both old and new are valid meanwhile, so there is no cut-over gap — then revoke the old serial. To decommission: revoke the whole sensor. To bring one back: reactivate it, then issue a fresh certificate — reactivation flips the sensor revoked → enrolled but deliberately leaves the old certificates revoked, so a retired sensor cannot return on a stale credential. A revoked serial is refused at the next mTLS handshake; a parked sensor is refused entirely. These operate on the Collector's own probe records only.

8Troubleshooting

9Security Considerations

• Session integrity. Cookies are signed with a per-node secret generated at first boot. The key file is mode 0600 and excluded from backups.
• Sensor authenticity. Flow ingest requires a client certificate signed by the fleet CA; the certificate — not the request body — establishes the sensor's identity. A body that claims a different sensor is rejected.
• Sync channel. identity-sync verifies Switchboard's TLS certificate against the synced fleet CA bundle. Only the very first sync of a fresh node, before any bundle exists, runs unverified; it logs a warning and is superseded on the next run.
• IPFIX provenance. IPFIX/NetFlow over UDP is unauthenticated. When enabled, every edge it produces is tagged ipfix:<exporter-ip> so told-by-an-exporter is never confused with observed-by-a-trusted-sensor.

10Caveats and Limitations

• Passive measurement only. A flow probe observes volume and endpoints. It cannot measure latency, packet loss or jitter; the map reports only values a probe actually observed. Synthetic checks are the sole active capability and are opt-in.
• No certificate authority on the Collector. The node validates certificates but never signs them. Enrollment, rotation and revocation are Switchboard functions; those endpoints are intentionally not served here.
• Revocation latency. Certificate-revocation state propagates only as fast as identity-sync (default five minutes).
• Deep capture is a distinct role. Packet retrieval requires a Vantage Deep node; a Vantage sensor records that a dependency exists, not the packets that crossed the wire.
• Single-node. This guide covers a standalone appliance. High-availability roles degrade gracefully to "single node, always active".