🛡️ Ghostwarden

Linux Network Guardian — nftables · Bridges · Firewalls · Visibility

Like ufw++ but for Linux bridges, nftables, iptables, and policies

## Overview

Ghostwarden is a Rust-powered network security orchestrator that unifies nftables, Linux bridges, and container/VM networks under a single declarative and human-friendly CLI.

It helps you see, manage, and enforce what your containers, VMs, and hosts can talk to — across NAT, VLANs, VXLANs, and SDN bridges — with rollback-safe, zero-trust policies.

Ideal for Arch Linux, Proxmox, and developer labs, Ghostwarden acts as your network's guardian angel: translating YAML/CLI configs into live, auditable firewall and routing state.

✨ Features

Unified Networking UX

• Define bridges, NATs, and VLANs in a simple YAML topology
• Apply in one command (gwarden apply --commit)
• Rollback automatically on disconnects or errors

nftables Policy Engine

• Layer-3 firewall & NAT management via JSON rulesets
• Dynamic port-forwards & per-network profiles
• CrowdSec/Wazuh hooks for ban decisions

Troubleshooting & Diagnostics

• gwarden doctor - Comprehensive network diagnostics
• Automatically checks nftables/iptables rules, Docker networking, bridge configuration
• Identifies kernel modules, sysctl settings, and common misconfigurations
• Provides actionable suggestions and fix commands

Observability & Visualization

• Built-in Prometheus /metrics exporter
• gwarden graph --mermaid for live topology diagrams
• See which containers/VMs are talking and how

Cluster-Aware (Future)

• Integrates with Proxmox SDN bridges and libvirt networks
• Detects vmbr*, tap*, veth*, and vxlan* interfaces automatically

Safe by Default

• Transactional apply/rollback
• Zero-trust profiles (e.g. routed-tight, public-web)
• Whitelists, TTLs, and conflict detection

📦 Components

Component	Description
gward	Core daemon — applies nftables & manages state
net-core	Topology model, diff planner, rollback engine
net-nft	nftables JSON builder/verifier
net-dhcpdns	dnsmasq/CoreDNS management
net-bridge	Handles Linux bridge/VLAN/VXLAN creation
integrations/	CrowdSec, Wazuh, Prometheus exporters
net-cli	gwarden commands (powered by clap)

🚀 Quick Start

# Build
cargo build --release

# Preview your current network plan
gwarden plan

# Apply network definitions (with rollback safety)
gwarden apply --commit --confirm 30s

Example Topology (/etc/ghostnet/workstation.yml)

version: 1
interfaces:
  uplink: enp6s0

networks:
  br_work:
    type: bridge
    iface: br-work
    vlan: 20
    members:
      - vm: devbox-01
      - vm: devbox-02

  nat_dev:
    type: routed
    cidr: 10.33.0.0/24
    dhcp: true
    dns: true
    masq_out: enp6s0
    forwards:
      - { public: ":4022/tcp", dst: "10.33.0.10:22" }

🧠 Example CLI

# Create and apply a NAT network
gwarden net create nat/dev --cidr 10.33.0.0/24 --dhcp --dns --masq via enp6s0

# Add a port forward
gwarden forward add nat/dev --dst 10.33.0.10:22 --public :4022/tcp

# Troubleshoot networking issues (NEW!)
gwarden doctor                    # Run all diagnostics
gwarden doctor nftables          # Check firewall rules
gwarden doctor docker            # Check Docker networking
gwarden doctor bridges           # Check bridge configuration

# Generate a live diagram
gwarden graph --mermaid

# Monitor metrics
curl localhost:9138/metrics

🗺 Roadmap

• MVP: nftables + dnsmasq orchestration
• Prometheus metrics + live graph
• Proxmox/libvirt integration
• CrowdSec + Wazuh ban sync
• VXLAN peer management
• eBPF traffic sampling dashboard

🧱 Stack

• 🦀 Rust 2024 edition
• 🧩 neli, serde_yaml, nftables-json, clap, axum, prometheus
• ⚙️ Optional: systemd integration, journald logging
• 🧠 Future: Ratatui TUI dashboard for live network map

📜 License

MIT © 2025 CK Technology / GhostKellz