Security & Architecture Reference

0 How to read this document

This reference is built to answer the questions a security review asks, before you ask them. Each section names the actual mechanism, not just an adjective: the algorithm, the protocol, the port, the library and version, the exact behavior. Where a control is something you turn on at install rather than a default, it is labelled as such.

1 Posture at a glance

CrossConnect is a network source-of-truth and operational-intelligence platform. It builds one model of your network, the devices, IP space, VLANs, cabling, circuits, routing, and the live state behind them, and lets your team ask it questions in plain language. Four facts frame every control in this document:

2 System context & trust boundaries

CrossConnect is a single deployable application backed by PostgreSQL, plus an optional formal-analysis sidecar (a helper process for whole-network config analysis). It reaches into the customer network only with outbound, read-only connections. It accepts operator and API traffic only on its own inbound application port. The diagram marks every edge with its transport and direction.

flowchart LR
  subgraph CN["CUSTOMER NETWORK"]
    direction TB
    DEV["Switches / routers
SNMP · SSH · LLDP"]
    WL["Wireless / cloud-managed
vendor REST (HTTPS)"]
    AV["AV / media endpoints
mDNS / SSDP"]
    OP["Operators
browser / API via SSO"]
  end
  subgraph CC["CROSSCONNECT DEPLOYMENT, you control"]
    direction TB
    APP["CrossConnect app
REST · UI · collectors · grounded AI"]
    PG[("PostgreSQL
system of record")]
    BF["Batfish sidecar
(optional)"]
  end
  subgraph EXT["EXTERNAL SERVICES"]
    direction TB
    IDP["SSO IdP
OIDC"]
    SIEM["SIEM / webhook
HMAC-signed"]
    LLM["LLM endpoint
your key, optional"]
  end
  DEV -- "read-only · 161/UDP · 22 · 443" --> APP
  WL --> APP
  AV --> APP
  OP -- "inbound HTTPS (app port)" --> APP
  APP -- "JDBC / TLS" --> PG
  APP <-- "RPC" --> BF
  APP --> IDP
  APP --> SIEM
  APP --> LLM
  classDef store fill:#1797b3,stroke:#0d7d90,color:#ffffff;
  classDef ext fill:#ffffff,stroke:#9aa8c0,color:#173a6b;
  class PG store;
  class DEV,WL,AV,OP,IDP,SIEM,LLM,BF ext;
  

3 What we discover

CrossConnect collects network state and inventory facts. It does not collect user content, application payloads, or the contents of packets. Everything below is metadata about the network and the devices on it: facts the equipment already publishes through its control plane, read straight from there.

4 How we discover it, mechanisms & libraries

Every collection path is a real protocol implementation with a fast read timeout and a clean way to fail. A device it cannot reach is logged and counted, it does not block the rest of the sweep, and it never falls back to writing anything. The exact libraries and pinned versions are listed below so you can match them against your own CVE (vulnerability) feeds.

5 The collector security model

Most security teams turn here first, because this is a system that holds credentials and reaches into the network. CrossConnect is built so the answer to every concern is structural (something the design makes impossible) rather than procedural (something we promise to do).

flowchart LR
  CC["CrossConnect
read-only credentials
fast-timeout reads"]
  DEV["Network device
SNMP agent / SSH"]
  CC -- "GET / GETBULK · show running-config" --> DEV
  DEV -. "no config write path exists" .-x CC
  classDef app fill:#173a6b,stroke:#0f2a4f,color:#ffffff;
  classDef ext fill:#ffffff,stroke:#9aa8c0,color:#173a6b;
  class CC app;
  class DEV ext;
  

6 Ports, protocols & egress

This is the complete list of connections. The only things that come in to the platform are the application port and the internal database port. Everything that touches the network goes outward. The full matrix is in Appendix A.

7 Where data is stored

PostgreSQL is the single system of record. There is no secondary data lake, no analytics warehouse, and no copy held on the vendor side. Each kind of data is stored separately, so the protection can match how sensitive it is.

Multi-tenancy. The tenant is the line that keeps data separate. Every row carries a tenant_id, every query filters on it, and foreign-key constraints stop any row from belonging to the wrong tenant. A request filter rejects any /api/v1/* call that does not resolve to an active tenant. A single-organization deployment simply runs as one tenant, and the same boundary governs instances that serve many organizations.

8 The observed-vs-documented trust gate

A discovered fact is never quietly accepted as truth. Observations land in a staging area first, where they are compared against the documented model and given a confidence score. They move into the source of truth only by a human action or an explicit rule that confirms them. This gate is the platform’s central integrity boundary, and it is the reason an answer can be trusted.

flowchart LR
  O["1 · Observe
staging, untrusted"] --> G{"2 · Validate
confidence-score · commit"}
  G --> S["3 · Documented
source of truth"]
  S --> D["4 · Derived
pure functions"]
  D --> OUT["5 · Output
cited answers"]
  classDef gate fill:#fdf0dd,stroke:#e0892a,color:#173a6b;
  classDef truth fill:#173a6b,stroke:#0f2a4f,color:#ffffff;
  classDef store fill:#e3f3f6,stroke:#1797b3,color:#173a6b;
  class G gate;
  class S truth;
  class O,D,OUT store;
  

9 Encryption in transit

• Operator & API: HTTPS/TLS terminates at the application (or your load balancer). HSTS is set on HTTPS responses; security headers (X-Content-Type-Options, X-Frame-Options) are applied by a response filter. GA
• Database: the JDBC connection to PostgreSQL supports TLS. A TLS compose overlay and managed-DB TLS are documented, and we recommend them for any database link that is not on the local loopback. Configurable
• Device collection: SNMPv3 keeps the data private and unaltered on the wire (authPriv); SSH is encrypted by design; vendor APIs are HTTPS-only with redirects disabled. Configurable
• Outbound webhooks / SIEM: sent over HTTPS, and the payloads are also HMAC-SHA256 signed, so the receiver can confirm they are genuine even apart from the transport (§13). GA

10 Encryption at rest & key management

Encryption at rest works in layers. Storage-level encryption covers all data. On top of that, field-level envelope encryption protects secrets with managed keys you can rotate. The underlying algorithm is AES-256-GCM (AEAD), with a fresh 12-byte random IV (initialization vector) per value and a 128-bit authentication tag. If a value has been tampered with, the tag fails on decrypt, so the change is caught rather than silently accepted.

flowchart LR
  subgraph SRC["KEK source, priority order"]
    direction TB
    K1["1 · env variable (256-bit)"]
    K2["2 · command → KMS / Vault"]
    K3["3 · key file (0600)"]
    K4["prod + no key → fail closed"]
  end
  KEK(["KEK (master)
never in code"])
  DEK(["DEK
wrapped by KEK"])
  P["plaintext secret
in memory only"]
  CT["stored ciphertext
keyId : base64(IV ‖ ct ‖ tag)"]
  SRC --> KEK
  KEK -- "unwraps" --> DEK
  DEK -- "AES-256-GCM" --> P
  P --> CT
  classDef key fill:#1797b3,stroke:#0d7d90,color:#ffffff;
  classDef store fill:#e3f3f6,stroke:#1797b3,color:#173a6b;
  classDef plain fill:#ffffff,stroke:#2f6fb0,color:#173a6b;
  class KEK,DEK key;
  class CT store;
  class P plain;
  

Key resolution (no weak defaults)

The master key is looked up in priority order: (1) an explicit environment variable, (2) an external command (a hook with a 15-second time limit that can fetch the key from HashiCorp Vault, AWS or GCP KMS, or a secret manager) deployment option, (3) an auto-generated key file created with 0600 permissions on first boot. If a production profile starts with no key configured, the application fails closed and refuses to start, and a placeholder sentinel value always fails closed too. No encryption key is ever compiled into the build.

Key rotation

• KEK rotation (routine): a pre-flight check confirms the current KEK can decrypt every data key, the prior wrapped form is snapshotted so it can be rolled back, each DEK is re-wrapped under the new KEK with a round-trip check, and the event is written to the audit chain. No row ciphertext is touched. GA
• DEK rotation (only on a suspected compromise): a new data key is issued and the secret fields are re-encrypted under it, row by row, in a way that is atomic and can resume if interrupted. Because each value records its key version, the old and new forms can coexist while the migration runs. Configurable
• Restore: rotation is reversible from the pre-rotation snapshot; the prior KEK is retired only after the new key is confirmed in service. GA

11 Secrets & credential handling

No secret is stored in plaintext, written to application logs, or returned in an API response or AI answer. If you prefer, credentials can be pulled at runtime from your secret manager instead of the application database, using the same key-command mechanism described in §10. The platform admin secret is stored as a SHA-256 hash and compared in constant time (so timing cannot leak it); the token-signing secret is held as the HMAC key that signs sessions and the audit chain, and session signatures are likewise verified in constant time.

12 Identity, SSO, grouping & RBAC

Your identity provider says who the user is, their role says what they can do, and every request is scoped to the tenant. When SSO (single sign-on) is enabled, operators get no local passwords at all. The IdP (identity provider) stays the system of record for identity and group membership.

flowchart LR
  IDP["Your IdP
OIDC"] --> SSO["SSO + PKCE / nonce
groups → role claim"]
  SSO --> JWT["Signed session
tenant · role · user"]
  JWT --> RBAC{"RBAC + tenant filter
per request"}
  RBAC --> DATA["tenant-scoped data
least privilege"]
  classDef ext fill:#ffffff,stroke:#9aa8c0,color:#173a6b;
  classDef gate fill:#fdf0dd,stroke:#e0892a,color:#173a6b;
  classDef truth fill:#173a6b,stroke:#0f2a4f,color:#ffffff;
  classDef store fill:#e3f3f6,stroke:#1797b3,color:#173a6b;
  class IDP ext;
  class SSO,JWT truth;
  class RBAC gate;
  class DATA store;
  

Authentication

• SSO via OIDC behind one enterprise-connection model, so any standard OIDC identity provider is supported. The OIDC path uses the authorization-code flow with PKCE (S256) and validates iss, aud, exp, and nonce (which defends against replay attacks). Group and role claims map to platform roles. Configurable
• Sessions are signed (HMAC-SHA256), carry tenant, role, and user, and expire on a configurable TTL (default 8 hours). Signature verification is constant-time. GA
• IdP-governed access: when SSO is enabled, operators hold no local password and a session is minted only after a successful IdP sign-in, so revoking a user (or their group) in your directory stops them obtaining a new session here. The IdP stays the system of record for identity and group membership. Configurable

Authorization (RBAC + grouping)

Roles are rank-ordered, meaning an action requires at least a certain role, and request filters enforce this: any request that changes data requires Editor or above, user management requires Admin, and administrative endpoints sit behind a separate admin credential that can be set to fail closed if it is not configured. IdP groups map onto these roles, so access is governed centrally by the groups your directory already maintains. Every /api/v1/* request is also tied to an active tenant, and an optional hardening flag rejects any request that does not present a signed session or API key.

13 API keys & webhooks

API keys

• Issuance & scope: keys are tied to a tenant and a role, so each key carries only the access that role allows. Inbound integration endpoints (presence, telemetry, admin operations) require a properly issued key, not just a guessable identifier. Configurable
• Monitoring: key use, failures, and administrative actions are written to the audit trail with NTP timestamps, so issuance and use are reviewable. GA
• Rotation & revocation: keys carry expiry and revocation state and can be rotated without downtime by issuing a replacement and disabling the prior key. Configurable

Webhook signing & rotation

flowchart LR
  CC["CrossConnect
event payload"] --> H["HMAC-SHA256(secret,
raw body)"]
  H --> SIG["signed delivery
X-CrossConnect-Signature header"]
  SIG --> RX["Your receiver
verify constant-time"]
  classDef app fill:#173a6b,stroke:#0f2a4f,color:#ffffff;
  classDef store fill:#e3f3f6,stroke:#1797b3,color:#173a6b;
  classDef ext fill:#ffffff,stroke:#9aa8c0,color:#173a6b;
  class CC app;
  class H,SIG store;
  class RX ext;
  

The signing secret is stored encrypted, and each delivery carries the HMAC-SHA256 signature of the raw body in an X-CrossConnect-Signature header. On the receiving side, verification should use a constant-time comparison. Inbound webhooks the platform accepts (for example presence updates or facts asserted by another system) are themselves authenticated and held as proposals. They are never applied to the source of truth without passing the trust gate in §8.

14 Logging & tamper-evident audit

Every meaningful action, a record change, a config apply, a secret edit, a discovery run, a key rotation, an AI prompt, is captured in an audit trail. That trail is not just append-only: each entry is cryptographically linked to the one before it, so quiet tampering can be detected, not merely discouraged.

flowchart LR
  E1["entry n-1
hash = H(… · prev)
HMAC signature"] --> E2["entry n
hash = H(… · prev)
HMAC signature"]
  E2 --> E3["entry n+1
hash = H(… · prev)
HMAC signature"]
  classDef link fill:#fbfcfe,stroke:#1797b3,color:#173a6b;
  class E1,E2,E3 link;
  

• What is recorded: actor, action kind, timestamp, and a full before/after payload for each change; system events (discovery runs, key rotations) on a parallel global chain; every AI prompt, retrieval, and output on its own entry.
• Integrity: SHA-256 hash-chaining plus HMAC-SHA256 signing under the deployment signing secret. A verification routine walks the chain, recomputes the hashes, checks each link, and verifies the signatures in constant time. The result is a simple pass or fail you can show on screen or export as compliance evidence.
• Export & monitoring: tamper-evidence only helps if someone is watching, so the audit stream is meant to be shipped to your SIEM and monitored there. Outbound signed sinks and OpenTelemetry export are built to support that.
• Retention: chain-aware retention trims past the configured window while preserving link integrity (§18).

15 AI / LLM data handling

The assistant is grounded and tightly constrained. It answers questions about the source of truth, and it does not touch the network.

Provider & data flow. You choose the AI provider. It can run against a model endpoint you name, under your own API key, or you can switch it off entirely, in which case the platform falls back to fixed, non-AI responses. Only the question and the specific records needed to answer it are sent to the model. Secrets and ciphertext are never included. If data residency for AI matters to you, point the assistant at a private or in-region model endpoint. Configurable

16 Application security & SDLC

• Static analysis & dependency scanning: SpotBugs (which inspects the compiled bytecode for bugs) and OWASP Dependency-Check (which scans dependencies for known CVEs against the NVD) both run in the build and produce reports.
• Test discipline: we write property and invariant tests, not just example tests. Security-specific suites cover the JWT codec, admin-secret handling, RBAC enforcement, tenant isolation, the audit hash-chain math, encryption round-trips, and regressions in known CVE classes, all exercised against a real PostgreSQL in integration tests.
• Recent hardening (verified, in the codebase): the server-side request forgery (SSRF) risk on vendor-URL fetches is closed (HTTPS public targets only, no redirects, and RFC1918/loopback/metadata/CGN/ULA addresses rejected); a race condition in key material is fixed; a denial-of-service in the config parser is now bounded; webhook and admin endpoints no longer trust a bare identifier and require an issued credential; and UI actions that change data are gated by role.
• Secure-by-default options: opt-in flags make the deployment fail closed when the admin secret, the signing secret, or request credentials are missing, so a production misconfiguration is loud rather than silent.
• No secrets in code, no TODO placeholders in production paths are enforced engineering rules; keys and credentials come only from the environment, a key file, or your secret manager.

17 Vulnerability management & disclosure

• Dependency posture: pinned versions (§4) mapped against OWASP Dependency-Check; updates are driven by CVE disclosure and the scan output.
• Reporting a vulnerability: security issues can be reported to contact_us@cybriq.io; a coordinated-disclosure process and acknowledgement are provided on receipt.
• Patch handling: because you host the platform yourself, security updates arrive as new builds you roll out on your own schedule. Releases that close a security finding come with advisory notes.

18 Retention, deletion & residency

Residency. Because the deployment and its PostgreSQL live in the region and account you choose, data residency is whatever you set it to. No network data has to be processed on the vendor side. The only optional external data path is an AI model endpoint, which you pick (you can keep it in-region or private) or turn off.

19 Deployment & operational hardening

CrossConnect ships as a set of containers (the application, PostgreSQL, and the optional analysis sidecar) and runs under Docker Compose, Kubernetes, or a managed-database setup. The recommended production hardening checklist follows:

20 Compliance posture & framework alignment

We describe where we stand in precise, defensible language. CrossConnect’s controls line up with the recognized frameworks, and we claim no certification we do not actually hold.

A Appendix, ports & protocols matrix

B Appendix, read-only collection scope

The collector account needs only read access. SNMP collection issues GET / GETBULK against these MIB families, and the SSH path (opt-in) issues read-only show-class commands to capture the configuration text. No OID that would change state, and no configuration command, is ever issued.

C Appendix, pre-answered questionnaire map

Where the common assessment instruments (CAIQ/CCM, SIG Lite, VSAQ) ask, this document answers:

D Appendix, security configuration reference

Hardening is driven by environment settings. A representative set of controls follows. The defaults favor working out of the box, while a production setup turns on the fail-closed flags: