Services & Listeners

0 How to read this document

This reference names concrete mechanisms, not adjectives. For each item it gives the class that opens the socket, the port it uses, the setting that controls it, and the default on/off value that decides whether the socket opens at all. Anything that is an optional add-on rather than a default is labelled as such. You should be able to write a host firewall policy, an outbound allow-list, and a pause/purge runbook from this page alone, without reading the source.

1 Runtime surface at a glance

CrossConnect is a single Spring Boot application (Java 21, Spring Boot 3.4.0) backed by PostgreSQL, with an optional formal-analysis sidecar. While it runs, it has four kinds of moving part: a thin HTTP/UI layer that hands work to services; a set of passive network listeners that take in data the network offers; a group of scheduled jobs on timers; and a few outbound dispatchers that send events out. Four facts frame every control on this page.

flowchart LR
  subgraph NET["CUSTOMER NETWORK · exporters & gear"]
    direction TB
    EXP["Flow exporters
NetFlow v5/v9/IPFIX · sFlow v5"]
    TRP["SNMP agents
v1/v2c traps"]
    AVG["AV / Bonjour gear
mDNS announcements"]
    DHC["DHCP relay
option-55 / option-60"]
    OPS["Operators / collectors
browser · REST"]
  end
  subgraph APP["CROSSCONNECT APPLICATION · single deployable"]
    direction TB
    FL["FlowListener
2055/UDP · 6343/UDP"]
    ST["SnmpTrapListener
162/UDP"]
    MD["MdnsListener
224.0.0.251:5353"]
    DH["DhcpFingerprintListener
67/UDP"]
    WEB["HTTP app port
8080 · REST · UI"]
    SVC["~228 @Service beans
own all repository access"]
    JOBS["~18 @Scheduled jobs
collect · alert · purge"]
  end
  PG[("PostgreSQL
system of record")]
  BF["Batfish sidecar
(optional)"]
  OUT["Outbound dispatch
webhooks · SIEM/chat · IdP · LLM"]
  EXP --> FL
  TRP --> ST
  AVG --> MD
  DHC --> DH
  OPS --> WEB
  FL --> SVC
  ST --> SVC
  MD --> SVC
  DH --> SVC
  WEB --> SVC
  JOBS --> SVC
  SVC --> PG
  SVC <--> BF
  SVC --> OUT
  classDef app fill:#173a6b,stroke:#0f2a4f,color:#ffffff;
  classDef store fill:#e3f3f6,stroke:#1797b3,color:#173a6b;
  classDef gate fill:#fdf0dd,stroke:#e0892a,color:#173a6b;
  classDef ext fill:#ffffff,stroke:#9aa8c0,color:#173a6b;
  class WEB,SVC app;
  class FL,ST,MD,DH,JOBS gate;
  class PG,BF store;
  class EXP,TRP,AVG,DHC,OPS,OUT ext;
  

2 The service-bean surface

The application is built in layers. The HTTP controllers (around 115 @RestController classes) and the Vaadin UI views stay thin and hand their work to services, and the services are the only code that touches the database. The codebase carries roughly 228 @Service beans. That count is high on purpose: each service handles one concern, which keeps every piece small and easy to test. Internal collectors, schedulers, and shared plumbing are services too, but they are not user features. A check in the build enforces that every user-facing capability shows up on the UI, the catalog, the glossary, and the AI surfaces; genuinely internal beans simply omit the marker that triggers that check.

3 Network listeners & bind ports

Five passive receivers can open a UDP socket or join a multicast group to take in data the network already sends. Each one is off by default: a fresh install opens none of these ports. When enabled, a receiver reads only the protocol metadata, matches the sender to a known device, and queues an observation through a service. It never reads packet contents and never captures traffic. The two flow receivers (NetFlow and sFlow) share one bean (FlowListener) but use two sockets.

Besides these sockets, the flow path can also accept an HTTP push instead of the UDP receivers, and external systems can submit claims over HTTP to the inbound trust gate. Both are covered in §6.

4 How a listener is gated & toggled

A listener is enabled in one of two ways, depending on how it is meant to be operated. Infrastructure-level receivers are set once at deploy time with a Spring property. Segment-level receivers are switched on per segment from the UI while the app runs. Either way, no socket opens until the listener is enabled.

flowchart LR
  subgraph PROP["Property-gated · set at deploy"]
    direction TB
    P1["crossconnect.integrations.flow.enabled = false
crossconnect.integrations.snmptrap.enabled = false"]
    P2["@ConditionalOnProperty
bean not instantiated until true"]
    P3["+ …flow.tenant / …snmptrap.tenant
UUID must name the attributed tenant"]
    P1 --> P2 --> P3
  end
  subgraph RUNTIME["Runtime-gated · flipped in UI"]
    direction TB
    R1["CollectorSettingsService
DB-backed mdns / dhcp flag"]
    R2["bean loads, socket stays closed
applySettings() opens it when enabled"]
    R3["idempotent · no restart
tenant = override or sole tenant"]
    R1 --> R2 --> R3
  end
  BIND["Socket binds
and stages observations"]
  P3 --> BIND
  R3 --> BIND
  classDef gate fill:#fdf0dd,stroke:#e0892a,color:#173a6b;
  classDef app fill:#173a6b,stroke:#0f2a4f,color:#ffffff;
  class P1,P2,P3,R1,R2,R3 gate;
  class BIND app;
  

5 Scheduled jobs & cadence

Scheduling is handled by SchedulingConfig (@EnableScheduling, controlled by crossconnect.scheduling.enabled, on by default; tests turn it off). Eighteen jobs keep the data current and the tables tidy. The cadences below are the resolved defaults of ${property:default} placeholders, and every interval is tunable. Collection jobs are controlled by a database flag and stay off by default; the housekeeping purges are always on; automation and the BI export are opt-in.

6 Inbound HTTP receivers

All HTTP traffic arrives on the single application port (default 8080, or 443 behind your TLS terminator). Beyond the ordinary create/read/update/delete endpoints, a handful of controllers under /api/v1/* act as inbound receivers: external systems push facts in, but those facts are never silently accepted as truth. Several of these stay off until a property enables them, and the occupancy webhooks require an issued API key rather than just a tenant header.

7 Outbound dispatchers & egress

Three components carry events out of the system. All three are driven by the internal event bus, and all are safe by default: with no destination configured, nothing leaves. These three are the entire outbound surface you need to allow-list.

flowchart LR
  REC["record change
create · update · delete"] --> BUS["EventBus
RecordChangeEvent"]
  BUS --> AUD["Audit chain
always records"]
  BUS --> WH{"WebhookDispatcher
per-tenant subscriptions?"}
  BUS --> SK{"OutboundSinkService
SIEM / chat URL set?"}
  WH -- "HMAC-SHA256 · retry/backoff" --> RX["Your receiver
HTTPS"]
  SK -- "fire-and-forget POST" --> SIEM["SIEM / chat
HTTPS"]
  classDef app fill:#173a6b,stroke:#0f2a4f,color:#ffffff;
  classDef store fill:#e3f3f6,stroke:#1797b3,color:#173a6b;
  classDef gate fill:#fdf0dd,stroke:#e0892a,color:#173a6b;
  classDef ext fill:#ffffff,stroke:#9aa8c0,color:#173a6b;
  class BUS app;
  class AUD store;
  class WH,SK gate;
  class REC,RX,SIEM ext;
  

8 Firewall & runbook cheat sheet

The short version: everything an operator needs to write a host firewall policy and a pause/purge runbook.

A Appendix, listener bind matrix

B Appendix, scheduled-job matrix

C Appendix, enable-flag reference

The main properties that decide whether a listener or job is live. The defaults aim for a quiet, safe out-of-the-box posture. Ports and intervals are tunable through the matching …port / …interval-ms keys.