Architecture

VaultDEC's architecture is built around one principle: the data plane and management plane must never share a communication path.

Three-Port Design

INTERNET ←→ ROUTER ←→ [WAN 2.5G]──────────[LAN 2.5G] ←→ Protected Server
                            │    Data Plane    │
                            │   (Ghost Bridge) │
                            └──────br0─────────┘
                                                
                         [MGMT 1G]
                            │
                     Management Network
                            │
                       Your Laptop

Data Plane (WAN + LAN)

The two 2.5 Gigabit ports form an invisible Layer 2 bridge. This is the "ghost" that monitors traffic:

• No IP address — Nothing to connect to
• No ARP responses — Can't be discovered
• No IPv6 — No neighbor discovery
• No STP — No bridge protocol announcements
• Promiscuous mode — Sees all traffic without participating

Traffic flows through the bridge as if it were a piece of wire. Your protected server's network configuration is completely unchanged.

Management Plane (MGMT)

The 1 Gigabit port operates on a completely separate network:

• Has an IP address (DHCP or static)
• Sends outbound heartbeats
• Accepts SSH forced-commands for dashboard access
• Never carries or has access to data plane traffic

Hardware Separation

This isn't just a software configuration. The NanoPi R6S physically separates these ports:

The data plane ports are on the PCIe bus. The management port is on the SoC's native GMAC. Different silicon, different bus, different interrupt paths.

Kernel-Level Isolation

Software separation reinforces the hardware separation using Linux Network Namespaces.

Namespace Architecture

At boot, VaultDEC creates two isolated network universes:

Vault Namespace (Data Plane):

• Contains: eth0 (WAN), eth1 (LAN), br0 (bridge)
• IP forwarding: disabled
• Routing table: empty
• Default gateway: none
• Internet access: impossible

Default Namespace (Management Plane):

• Contains: eth2 (MGMT)
• Has IP address and gateway
• Runs heartbeat and SSH listener
• Cannot see or access bridge interfaces

These are not firewall rules. Interfaces in one namespace literally do not exist from the other namespace's perspective. A process running in the management namespace cannot enumerate, route to, or interact with the bridge interfaces. They are in separate kernel network stacks.

Process Architecture

VaultDEC runs as two separate binaries:

guardian-core

• Runs inside the vault namespace
• Launched via: ip netns exec vault /usr/bin/guardian-core
• Capabilities: CAP_NET_RAW, CAP_NET_ADMIN (minimum required for packet capture)
• Responsibilities: packet capture, 5-Rule Engine evaluation, connection kill

guardian-mgmt

• Runs in the default namespace
• Heavily sandboxed via systemd
• No network capabilities
• Responsibilities: heartbeat transmission, SSH command handling, ephemeral dashboard

Inter-Process Communication

The two processes communicate over a Unix Domain Socket at /run/vaultguardian/core.sock:

• Permissions: 0660 root:vaultguardian
• Protocol: allowlisted commands only
• No arbitrary command execution
• No shell access

guardian-core pushes status updates (ARMED, KILLED, speed metrics) through the socket. guardian-mgmt reads these for the heartbeat and dashboard. The socket is the only crossing point between the two planes.

Ephemeral Dashboard

VaultDEC has no permanently running web interface. The dashboard is activated on demand:

1. User sends SSH forced-command: ssh vaultdec@<ip> enable-dashboard 30m
2. guardian-mgmt receives the command via SSH
3. Web server starts on the management interface with a TTL
4. Timer expires → web server stops automatically
5. No standing HTTP listener between sessions

This means the management port's attack surface is: SSH (key-only, forced-command, no shell) and nothing else, unless the dashboard is temporarily active.

Heartbeat System

guardian-core sends an internal "alive" ping every second through the Unix socket to guardian-mgmt.

guardian-mgmt translates this into external heartbeat states:

If the heartbeat stops entirely, the device is assumed to be powered off or experiencing a hardware failure.