WhiteOwl Networks — Product Security Overview

1. Architecture Overview

WhiteOwl Networks is a self-hosted network monitoring and observability platform deployed as a set of Docker containers orchestrated via Docker Compose. All components run within the customer's infrastructure — no data leaves the network unless explicitly configured (e.g., AI features or S3 archival).

Core Services

Container	Function	Exposed Ports
Backend (Node.js)	REST API, authentication, business logic	3001 (internal)
Frontend (React)	Web UI served via Nginx	443 (HTTPS), 80 (redirect)
ClickHouse	Time-series flow data storage	9000, 8123 (internal only)
PostgreSQL	Configuration, users, credentials, device inventory	5432 (internal only)
Kafka	Message streaming for flow ingestion	9092 (internal only)
GoFlow2	NetFlow/sFlow/IPFIX collector	2055/UDP (NetFlow), 6343/UDP (sFlow)
SNMP Poller (Go)	Device metric collection via SNMP	None (outbound only)
SNMP Discovery (Go)	Automated device discovery	None (outbound only)
Redis	DNS resolution cache, session data	6379 (internal only)
Probes (optional)	Remote network monitoring agents	WireGuard VPN tunnel

Network exposure: Only the web UI (443/tcp), flow collectors (2055/udp, 6343/udp), and optionally the WireGuard VPN endpoint are exposed externally. All database and message bus ports are internal to the Docker network.

2. Authentication & Authorization

User Authentication

Users authenticate via username and password through the web UI
Passwords are hashed using bcrypt before storage in PostgreSQL
Authentication sessions are managed via JSON Web Tokens (JWT)
JWTs are signed with a server-side secret and include expiration
Session tokens are transmitted via secure HTTP-only cookies or Authorization headers

Role-Based Access Control (RBAC)

Role	Permissions
Admin	Full access: user management, device configuration, credential management, job execution, system settings
Viewer	Read-only access: dashboards, reports, flow data, device status

All write operations enforce requireWriteAccess middleware
Administrative operations additionally enforce requireAdmin middleware
API endpoints validate JWT tokens and role membership on every request

API Key Authentication

API keys support scoped access for programmatic integrations
Keys are hashed before storage — the plaintext key is shown only once at creation
Each key can be assigned specific scopes limiting which endpoints it can access
Keys can be revoked at any time through the admin interface

3. Credential Management

Encryption at Rest

All sensitive credentials are encrypted before storage using AES-256-GCM (Galois/Counter Mode), an authenticated encryption algorithm that provides both confidentiality and integrity.

Credential Type	Storage Location	Encryption
SNMP community strings	PostgreSQL `snmp_credentials`	AES-256-GCM
SNMPv3 auth passwords	PostgreSQL `snmp_credentials`	AES-256-GCM
SNMPv3 priv passwords	PostgreSQL `snmp_credentials`	AES-256-GCM
SSH passwords	PostgreSQL `devices`	AES-256-GCM
Enable passwords	PostgreSQL `devices`	AES-256-GCM
API integration tokens	PostgreSQL `integrations`	AES-256-GCM
MaxMind license key	PostgreSQL `settings`	AES-256-GCM

Encryption format: iv:authTag:ciphertext (all hex-encoded)

128-bit random IV per encryption operation (no IV reuse)
128-bit authentication tag for integrity verification
256-bit encryption key derived from the ENCRYPTION_KEY environment variable

Key management: The master encryption key is a 64-character hex string (32 bytes) stored as an environment variable, not in the database. It is never logged, transmitted, or exposed through the API. Customers should protect this key using OS-level secret management or container orchestration secrets.

SNMPv3 Credentials

Full SNMPv3 USM (User-based Security Model) support:

Auth protocols: MD5, SHA, SHA-224, SHA-256, SHA-384, SHA-512
Privacy protocols: DES, AES-128, AES-192, AES-256
Security levels: noAuthNoPriv, authNoPriv, authPriv
In-UI credential testing before saving — verify connectivity without storing invalid credentials
Credentials are decrypted only in-memory at time of use by the poller and discovery services

Credential Testing

The SNMP credential modal includes a Test function that validates credentials against a live device before saving. This ensures:

No invalid or mistyped credentials are stored
The correct auth/priv protocol combination is verified
Network connectivity (ACL, firewall, routing) is confirmed

4. Data Security

Flow Data Storage

Network flow data (NetFlow, sFlow, IPFIX) is stored in ClickHouse
ClickHouse is authenticated with username/password (not exposed externally)
Data retention is managed via TTL policies — raw data is automatically aged out
Aggregated data uses separate retention periods for long-term trending
Optional S3 archival encrypts data at rest using AES-256 server-side encryption

Database Access

PostgreSQL requires authenticated connections with username/password
ClickHouse requires authenticated connections with username/password
Both databases are accessible only within the Docker network (no external port binding)
Database credentials are configured via environment variables, not hardcoded

Backup Security

ClickHouse backups via clickhouse-backup automatically mask dictionary passwords as [HIDDEN] in backup metadata
The install/restore script re-applies credentials from environment variables during restoration
Backup files should be stored with appropriate filesystem permissions and encrypted at the storage layer

5. AI Integration Security

Data Masking

WhiteOwl includes a Data Masking feature that anonymizes sensitive network information before it is sent to any AI provider:

IP Address Masking: All IP addresses (source, destination, device management IPs) are replaced with anonymized placeholders before transmission
Hostname Masking: Device names and hostnames are replaced with generic identifiers
Masking is applied at the application layer before any API call to the AI provider

AI Feature Controls

All AI features can be independently enabled or disabled:

Feature	Setting	Default
AI Chat Assistant	`assistant_enabled`	Configurable
Executive Report AI Summaries	`exec_reports_enabled`	Configurable
Alert Intelligence (AI context)	`alerting_ai_enabled`	Configurable
Data Masking	`mask_data`	Configurable

AI features are opt-in — administrators explicitly enable each capability
When disabled, no data is sent to any external AI provider
AI provider API keys are encrypted at rest using AES-256-GCM
All AI interactions are processed through the backend — the frontend never communicates directly with AI providers

AI Provider Configuration

Supports configurable AI provider endpoints (not locked to a single vendor)
API keys are stored encrypted and never exposed through the UI after initial entry
Administrators can switch providers or revoke access at any time

6. Network Security

Transport Encryption

Web UI is served over HTTPS (TLS) via Nginx reverse proxy
Internal container-to-container communication occurs over the Docker bridge network
Remote probe connectivity is secured via WireGuard VPN tunnels

WireGuard VPN (Remote Probes)

Remote probes connect back to the central server via WireGuard
WireGuard uses modern cryptography: ChaCha20 for symmetric encryption, Curve25519 for key exchange, BLAKE2s for hashing, SipHash24 for hashtable keys
Each probe has a unique key pair — compromising one probe does not affect others
Probe keys can be revoked from the central management interface
All SNMP, flow, and metric data from remote sites traverses the encrypted tunnel

Exposed Ports Summary

Port	Protocol	Service	Required
443	TCP	HTTPS Web UI	Yes
80	TCP	HTTP → HTTPS redirect	Optional
2055	UDP	NetFlow/IPFIX collector	Yes (if using NetFlow)
6343	UDP	sFlow collector	Yes (if using sFlow)
514	UDP	Syslog collector	Optional
51820	UDP	WireGuard VPN	Optional (remote probes)

All other ports (databases, Kafka, Redis, internal APIs) are not exposed outside the Docker network.

Firewall Recommendations

Restrict port 443 to authorized management networks
Restrict flow collector ports (2055, 6343) to known network device IPs
Restrict WireGuard port to known probe public IPs
No inbound connectivity is required for the SNMP poller or discovery services — they initiate outbound connections only

7. Audit Logging

Audit Trail

All administrative and write operations are logged with:

Timestamp
User identity (from JWT)
Action type (create, update, delete, execute)
Resource affected
Source IP address

Audited operations include:

User login/logout
Device creation, modification, deletion
Credential creation and deletion
Configuration job execution (dry-run and live)
Discovery triggers
SNMP credential changes
Alert rule modifications
System settings changes

Audit logs are stored in PostgreSQL and accessible through the admin interface.

8. Configuration Management Security

Ansible Integration

Configuration deployment to network devices uses Ansible over SSH
SSH credentials are encrypted at rest (AES-256-GCM)
Dry-run mode (--check) allows previewing changes before applying
All configuration jobs are logged with full output capture
Pre-change and post-change configuration snapshots are stored for rollback capability
Configuration diffs are available for review before and after deployment

Template Security

Jinja2 templates are stored in the database, not on the filesystem
Template variables are validated before rendering
Rendered configurations are written to temporary files and cleaned up after use

9. Container Security

Image Hardening

Backend containers use Alpine Linux base images (minimal attack surface)
Go services are compiled as static binaries with CGO disabled
Only required packages are installed (no compilers or dev tools in production images)
Containers run with minimal required capabilities

Container Isolation

Each service runs in its own container with dedicated resource allocation
Inter-container communication is restricted to the Docker bridge network
No containers run in privileged mode (except where Docker socket access is required for orchestration)
Container images are built from pinned base image versions

10. Environment Variable Security

The following sensitive environment variables must be protected:

Variable	Purpose	Format
`ENCRYPTION_KEY`	Master credential encryption key	64 hex characters (32 bytes)
`JWT_SECRET`	JWT signing secret	Random string
`PG_PASSWORD`	PostgreSQL password	String
`CH_PASSWORD`	ClickHouse password	String
`SNMP_ENCRYPTION_KEY`	Legacy SNMP encryption (deprecated)	32 ASCII characters

Recommendations:

Store environment variables in a .env file with restrictive permissions (chmod 600)
Do not commit .env files to version control
Consider using Docker secrets or a vault solution for production deployments
Rotate the ENCRYPTION_KEY only with a coordinated re-encryption of all stored credentials

11. Autodiscovery Security

SNMP autodiscovery is disabled by default on new installations
Administrators must explicitly enable discovery and configure subnets
Discovery only scans explicitly configured subnet ranges — no unsolicited network scanning
Discovery credentials are the same encrypted SNMP credentials used for polling
Discovered devices require manual or policy-based approval before being added to monitoring

12. Compliance Considerations

Data Sovereignty

Fully self-hosted — all data remains within the customer's infrastructure
No telemetry or usage data is sent to WhiteOwl Networks or any third party
AI features (when enabled) send data only to the customer-configured AI provider, with optional masking

Data Retention

Flow data retention is configurable via TTL policies (default: raw data 24 hours, aggregated data 5 days)
Customers can extend or reduce retention based on compliance requirements
S3 archival provides long-term storage with customer-managed encryption keys
Audit logs are retained indefinitely by default

Access Control

RBAC enforces least-privilege access
All API endpoints require authentication
Admin operations require elevated role membership
API keys support scoped access for integrations

13. Security Recommendations for Deployment

Network segmentation: Deploy WhiteOwl on a dedicated management VLAN/subnet
TLS certificates: Use valid certificates from a trusted CA (not self-signed) for the web UI
Strong passwords: Use unique, complex passwords for all database and service accounts
Key rotation: Periodically rotate the ENCRYPTION_KEY and re-encrypt stored credentials
Backup encryption: Encrypt backup files at the storage layer (filesystem or S3 SSE)
Access restriction: Limit web UI access to authorized management workstations via firewall rules
SNMP ACLs: Configure SNMP access lists on network devices to only permit the WhiteOwl server IP
Monitor audit logs: Regularly review audit logs for unauthorized access attempts
Update regularly: Keep Docker images and base OS packages updated for security patches
AI data review: If AI features are enabled, review and enable data masking before use

Contact

For security questions, vulnerability reports, or compliance inquiries, contact your WhiteOwl Networks account representative.

1. Architecture Overview​

Core Services​

2. Authentication & Authorization​

User Authentication​

Role-Based Access Control (RBAC)​

API Key Authentication​

3. Credential Management​

Encryption at Rest​

SNMPv3 Credentials​

Credential Testing​

4. Data Security​

Flow Data Storage​

Database Access​

Backup Security​

5. AI Integration Security​

Data Masking​

AI Feature Controls​

AI Provider Configuration​

6. Network Security​

Transport Encryption​

WireGuard VPN (Remote Probes)​

Exposed Ports Summary​

Firewall Recommendations​

7. Audit Logging​

Audit Trail​

8. Configuration Management Security​

Ansible Integration​

Template Security​

9. Container Security​

Image Hardening​

Container Isolation​

10. Environment Variable Security​

11. Autodiscovery Security​

12. Compliance Considerations​

Data Sovereignty​

Data Retention​

Access Control​

13. Security Recommendations for Deployment​

Contact​