Sentinel Alert — Network Security Dashboard¶

Version: 2026.06.001 (Debian / Ubuntu / Raspbian · RHEL 8 / 9 / 10)
Python: 3.13+

Sentinel Alert is a standalone real-time network security dashboard — completely independent of the Sentinel core. It runs on its own port (5056), its own SQLite database, and its own systemd service.

It was designed for one purpose: give you an instant, visual answer to "what is attacking me right now and how is my network doing?" A 3D globe shows live attacks from around the world. An SSH-based scanner audits every Linux host for CVEs and misconfigurations. A D3.js force graph maps your LAN topology. An uptime monitor tracks all your services.

Deploy it on any machine — a wall-mounted Raspberry Pi, a NOC workstation, or alongside Sentinel core. It works equally well in a home lab (home mode) and an office environment (work mode).

Feature Overview¶

Additional capabilities:

• Globe solo mode — /?solo=globe opens a fullscreen globe-only view in a new tab
• Blocked IPs — visualise a static blocklist file as attack arcs on the globe
• Sentinel Bridge — forward events to a central Sentinel server
• Honeypot — fake SSH (port 2222) and HTTP (port 8080) services that capture attacks
• ISP enrichment — background task enriches existing records via ip-api.com (plus offline dbip-asn.mmdb lookup)
• MikroTik blocking — one-click block adds the attacker to the router's blocked_ips address-list (a drop rule on the router does the rest); optional auto_block for honeypot attackers
• PiHole multi-instance — primary + secondary Pi-hole v6 monitored via REST API (session SID auth)

Architecture¶

  Browser
     │
     │ HTTP  WebSocket (/ws/live)
     ▼
  app.py (Flask · port 5056)
     │
     ├── collector.py  — SSH polling of fail2ban from monitored hosts (every N min)
     ├── honeypot.py   — fake SSH + HTTP listeners, log captured attacks
     ├── scanner.py    — ARP-scan for LAN device discovery
     ├── fsc.py        — Security Center SSH scanner (OS, CVEs, firewall)
     ├── geoip.py      — MaxMind GeoLite2 + ip-api.com fallback
     ├── bridge.py     — forward events to central Sentinel server
     └── blocklist.py  — static IP blocklist visualisation
     │
     ├── data/alerts.db (SQLite — attacks, bans, devices, service_checks)
     └── /etc/sentinel/sentinel-alert.conf (INI config)

Requirements¶

• Python 3.13+
• openssh-client, nmap (Security Center and collector)
• GeoLite2-City.mmdb (free MaxMind account — place in data/)
• GeoLite2-ASN.mmdb (optional — better ISP lookup; place in data/)

Installation¶

# 1. Clone the repository
git clone https://github.com/youruser/sentinel-alert.git
cd sentinel-alert

# 2. Full install (system packages + venv + interactive config + systemd)
sudo ./setup.sh

# Install only dependencies (configure later):
sudo ./setup.sh --deps

# Reconfigure existing installation:
sudo ./setup.sh --reconf

# Uninstall (removes systemd service, keeps config):
sudo ./setup.sh --uninstall

The setup script:

1. Detects the distro (Debian / Ubuntu / RHEL / Fedora) and installs system packages
2. Creates .venv/ and installs Python dependencies
3. Runs an interactive configuration wizard
4. Writes /etc/sentinel/sentinel-alert.conf
5. Initialises the SQLite database (data/alerts.db)
6. Generates an ed25519 SSH key for the fail2ban collector
7. Installs and enables a systemd service unit

Manual / development setup¶

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
python3 db_init.py
SENTINEL_CONF=/etc/sentinel/sentinel-alert.conf .venv/bin/python app.py

Authentication¶

The dashboard is split into two access levels:

Default credentials: admin / admin — change in the config before exposing to any network.

Sessions use HMAC-SHA256 signed cookies (7-day TTL). The secret key is auto-generated on first start if not set.

Configuration¶

All settings live in /etc/sentinel/sentinel-alert.conf (INI format).

[auth]
username = admin
password = CHANGE_ME
secret   =

[mode]
# "home" (default) or "work"
type     = home
ips_file =
who_file =

[server]
host     = 0.0.0.0
port     = 5056

[home]
lat      = 50.0835
lon      = 14.4341

[sentinel]
url      = https://sentinel.example.com
token    = <64-char-token>
hostname = my-node

[honeypot]
ssh_port  = 2222
http_port = 8080

[collector]
ssh_user      = root
hosts_file    = /etc/hosts
monitor_hosts =

[sniproxy]
server    =
ssh_user  = root
log_files = /var/log/sniproxy/https_access.log,/var/log/sniproxy/http_access.log

[scanner]
enabled = false

[security_center]
enabled    = true
ha_url     =
ha_token   =
ignore_ips = 192.168.2.1

[threat]
blocks_ips_file =

[mikrotik]
host       =            # RouterOS IP/hostname — empty disables the module
ssh_user   = admin
auto_block = false      # auto-block honeypot attackers

[pihole]
hosts    =              # comma-separated Pi-hole v6 hosts — empty disables
primary  =
password =

After editing, restart the service:

sudo systemctl restart sentinel-alert

Home mode vs. Work mode¶

Work mode adapts the dashboard for office deployments where LAN scanning is unavailable or unneeded.

Enable with type = work in [mode]. Pair with ips_file (blocked IPs visualised on globe) and who_file (CSV user list shown in Users panel).

GeoIP databases¶

Required for attack visualisation on the globe.

# Download from maxmind.com (free account required)
# Place both files in data/
data/GeoLite2-City.mmdb   # required — country, coordinates
data/GeoLite2-ASN.mmdb    # optional — ISP / org name

Without GeoLite2-City.mmdb the globe will not display attacks. Existing records with unknown ISP are enriched via ip-api.com as a background task on startup.

SSH key setup¶

The collector and Security Center use conf/id_ed25519 (generated by setup.sh).

# Distribute public key to all monitored hosts:
ssh-copy-id -i conf/id_ed25519.pub root@<HOST>

# Test connection:
ssh -i conf/id_ed25519 root@<HOST> 'fail2ban-client status'

Threat Map — Globe¶

Attack arcs use age-based colouring (bright and thick when fresh, fading over 24 h). Each new attack triggers a 3-wave shockwave ring at the origin and a 2-wave shield-hit ring at home.

Security Center¶

SSH-based scanner for each host in /etc/hosts (excluding ignore_ips):

• OS / kernel / distro / EOL status
• CPU, RAM, disk usage
• Pending updates split by CVE severity
• fail2ban status and firewall status
• Root SSH login allowed / passwordless users
• LXC / VM container detection

Hosts can be enabled / disabled individually from the UI.

Network Map¶

Interactive D3.js force-directed topology. Click any device to edit its type, connection type, ISP Gateway flag, or notification settings. Changes are persisted to data/topo.json.

Services (Uptime Monitor)¶

Available in home mode only.

Service state changes (up→down / down→up) are forwarded to the configured Sentinel Bridge.

API Reference¶

Data files¶

Logs & diagnostics¶

# Live log stream
journalctl -u sentinel-alert -f

# Last 100 lines
journalctl -u sentinel-alert -n 100 --no-pager

# Service status
systemctl status sentinel-alert

# Restart
sudo systemctl restart sentinel-alert

System logs are also visible in the dashboard System Logs panel (requires login).