FencePost

Multi-Host-UFW-Firewall-Dashboard. Verbindet sich per SSH zu Linux-Hosts, analysiert Firewall-Regeln und lauschende Ports, erklärt alles in einfacher Sprache und weist auf Sicherheitslücken hin.

Features

• Multi-Host-Übersicht – UFW-Status, Standardrichtlinien und aktive Dienste aller Hosts auf einen Blick
• Erklärungen in einfacher Sprache – jede Firewall-Regel wird in lesbare Beschreibungen mit VLAN- und Dienstnamen übersetzt
• Lückenerkennung – findet lauschende Ports ohne passende UFW-Allow-Regel, unterteilt nach externer vs. lokaler Exposition
• Verbindungsdiagnose – verfolgt eine Quell-IP und einen Zielport durch die Regelkette, um zu sehen, ob Datenverkehr erlaubt, blockiert oder abgelehnt würde
• Änderungserkennung – vergleicht den aktuellen Zustand mit dem letzten Snapshot und sendet Ereignisse (Regeln hinzugefügt/entfernt, UFW umgeschaltet, Hosts nicht erreichbar) an einen Webhook
• Docker-bewusst – markiert Docker-Hosts, bei denen iptables UFW umgehen kann

Screenshots

Pages

Route	Description
/	Übersichts-Dashboard mit Host-Karten, Dienst-Pills und Lückenzählern
/host/{name}	Host-Details mit Tab-Ansicht: erklärte Regeln, ungeschützte Ports, lauschende Ports, Rohausgabe
/diagnose	Verbindungsdiagnose-Tool mit Regel-für-Regel-Trace-Visualisierung
/login	Sitzungsbasierte Authentifizierung

Architecture

Browser --> Cloudflare Tunnel --> Reverse Proxy --> FencePost (:8890)
  FastAPI container
    |-- SSH --> Host 1 (ufw status, ss -tlnp)
    |-- SSH --> Host 2
    |-- SSH --> Host N
    '-- POST --> Notification webhook

FencePost ist schreibgeschützt – es ändert nie Firewall-Regeln, sondern berichtet nur darüber.

Quick Start

Voraussetzungen

• Python 3.12+ (lokale Entwicklung) oder Docker (Produktion)
• SSH-Schlüsselpaar (ed25519) mit öffentlichem Schlüssel, der auf den Ziel-Hosts bereitgestellt ist
• Sudoers-Eintrag auf jedem Host für den SSH-Benutzer:

  <user> ALL=(ALL) NOPASSWD: /usr/sbin/ufw status verbose, /usr/sbin/ufw status numbered, /usr/bin/ss -tlnp
  

1. Klonen und konfigurieren

git clone <repo-url> && cd fencepost

# Add your SSH key
cp ~/.ssh/your_key ssh/id_ed25519
chmod 600 ssh/id_ed25519

# Create your environment file from the template
cp .env.example .env
# Edit .env with real credentials

2. config.yaml bearbeiten

timezone: Australia/Melbourne

hosts:
  - name: My Server
    hostname: 192.168.1.10
    ssh_user: deploy
    ssh_port: 22
    is_docker_host: false

networks:
  "192.168.1.0/24": "LAN"

3. Ausführen

Lokale Entwicklung

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Load env vars (bash/zsh)
export $(grep -v '^#' .env | xargs)

uvicorn app.main:app --reload --port 8890

Öffne http://localhost:8890.

Hinweis: Im lokalen Modus wird der SSH-Schlüssel unter dem in config.yaml angegebenen Pfad (ssh.key_path) verwendet. Für die lokale Entwicklung kannst du dies überschreiben, um auf dein lokales ssh/id_ed25519 zu verweisen:

ssh:
  key_path: ssh/id_ed25519
  timeout: 10

Docker (Produktion)

docker compose up -d --build

Öffne http://localhost:8890. Der Container liest die Anmeldedaten automatisch über compose.yaml aus .env.

Konfiguration

config.yaml

Section	Purpose
timezone	IANA-Zeitzone für angezeigte Zeitstempel (z. B. Australia/Melbourne, UTC)
hosts	Array von SSH-Zielen: name, hostname, ssh_user, ssh_port, is_docker_host
ssh	key_path (Pfad zum privaten Schlüssel) und timeout in Sekunden
networks	CIDR-zu-Name-Zuordnung für VLANs – wird in Regelerklärungen und Diagnosen verwendet
devices	Benannte IPs für die Schnellauswahl-Schaltflächen der Diagnoseseite
notifications	Optionaler Webhook: url, channel (API-Schlüssel per Umgebungsvariable gesetzt)

Umgebungsvariablen (.env)

Variable	Default	Description
FENCEPOST_USERNAME	admin	Anmelde-Benutzername
FENCEPOST_PASSWORD	fencepost	Anmelde-Passwort
FENCEPOST_SECRET_KEY	change-me	Signaturschlüssel für Session-Cookies
FENCEPOST_CONFIG	config.yaml	Pfad zur Konfigurationsdatei
NOTIFICATIONS_API_KEY		Bearer-Token für den Benachrichtigungs-Webhook

Anmeldedaten werden in .env gespeichert (gitignored) und von compose.yaml referenziert. Übertrage niemals Geheimnisse in das Repository.

Stack

• Backend: Python 3.12 / FastAPI / Uvicorn
• SSH: Paramiko mit ed25519-Schlüsselauthentifizierung
• Templates: Jinja2 (serverseitig gerendert, kein JS-Framework)
• HTTP-Client: httpx (Webhook-Benachrichtigungen)
• Styling: Benutzerdefiniertes CSS, dunkles Theme, kein Framework
• Schriftarten: DM Mono (Daten), Anybody (Überschriften)

Projektstruktur

app/
  main.py           # FastAPI routes and auth
  models.py         # HostFirewallState, UFWRule, ListeningPort dataclasses
  parser.py         # Parses ufw status and ss output
  explainer.py      # Translates rules to plain English
  diagnose.py       # Connection diagnostic engine
  gap_detector.py   # Finds uncovered listening ports
  ssh_client.py     # Paramiko wrapper, parallel host fetching
  eventfeed.py      # Change detection and webhook posting
  templates/
    base.html       # Layout, CSS, navigation
    overview.html   # Host dashboard grid
    host_detail.html # Per-host tabbed detail view
    diagnose.html   # Connection diagnostic form and results
    login.html      # Authentication page
config.yaml         # Host definitions, VLANs, devices, timezone
compose.yaml        # Docker Compose service definition
Dockerfile          # Python 3.12 slim image
.env.example        # Template for environment variables
ssh/                # SSH key directory (key not committed)
data/               # Runtime state (last_state.json, not committed)

Einen Host hinzufügen

1. Füge einen Eintrag in config.yaml unter hosts: hinzu
2. Kopiere den öffentlichen SSH-Schlüssel auf den Host: ssh-copy-id -i ssh/id_ed25519.pub user@host
3. Erstelle /etc/sudoers.d/fencepost auf dem Host mit den erforderlichen NOPASSWD-Regeln
4. Neu erstellen: docker compose up -d --build

Benachrichtigungen

Wenn in config.yaml mit einer NOTIFICATIONS_API_KEY-Umgebungsvariable konfiguriert, sendet FencePost bei jeder Dashboard-Aktualisierung Änderungsereignisse:

• UFW aktiviert / deaktiviert
• Regeln hinzugefügt / entfernt (mit Regeldetails)
• Neue ungeschützte externe Ports
• Host wurde unerreichbar / wiederhergestellt

Die Ereignisse enthalten Idempotenzschlüssel, um Duplikate zu vermeiden.

Lizenz

MIT