🛡️ NetSentry

NetSentry is a lightweight, real-time Linux network bodyguard and threat sentinel. Running silently in the background or interactively via an htop-style terminal dashboard (TUI), NetSentry correlates network sockets with Linux processes, flags suspicious outbound connections (reverse shells, untrusted /tmp binaries, known malicious botnets/C2 nodes), and dispatches desktop notifications or executes firewall countermeasures.

✨ Features

• 🕵️ Process-Network Correlation: Maps every active socket to its PID, executable path, process name, and user.
• 🚨 Real-Time Threat Detection:
  • Reverse Shell Detection: Detects shells (bash, zsh, sh) or net tools (nc, socat) opening remote sockets.
  • Untrusted Path Execution: Flags binaries running from temporary directories like /tmp/, /dev/shm/, or /var/tmp/.
  • Suspicious Port Alerts: Identifies connections on backdoor ports (4444, 1337, 31337, 6667, etc.).
  • Threat Intelligence: Built-in and downloadable IP reputation feeds (Tor exits, botnet C2s, scanner IPs).
  • Data Exfiltration Detection: Alerts when processes transmit large amounts of outbound data at abnormal rates.
• 🖥️ Live Interactive Terminal Dashboard (TUI): Beautiful htop-style dashboard with live hotkeys (↑/↓ cursor, b block IP, k kill process, i deep inspector, ? help modal).
• 🔔 Multi-Channel Alert Dispatcher: Native Linux desktop notifications, Telegram Bot API, and Discord/Slack webhook rich embeds.
• 🧱 Next-Gen Firewall Engine: Native nftables, ufw, and iptables backends with automatic backend detection, IPv6 support, and temporary quarantine scheduling.
• ⚡ Kernel Tracing & eBPF Ready: Socket event monitoring with graceful polling fallback (netsentry bpf-status).
• ⚙️ Systemd Integration: Single-command user service setup (netsentry install-service).

🏗️ Architecture

                      ┌────────────────────────┐
                      │ Linux Kernel / Sockets │
                      └───────────┬────────────┘
                                  │
                                  ▼
               ┌─────────────────────────────────────┐
               │    Network Monitor (psutil/proc)    │
               │  Maps sockets to PID & Binary Path  │
               └──────────────────┬──────────────────┘
                                  │
                                  ▼
               ┌─────────────────────────────────────┐
               │         Threat Detector             │
               ├──────────────────┬──────────────────┤
               │ • Threat Intel   │ • Port Blacklist │
               │ • Shell Sockets  │ • Untrusted Path │
               └──────────────────┬──────────────────┘
                                  │
                  ┌───────────────┼───────────────┐
                  ▼               ▼               ▼
           ┌────────────┐  ┌─────────────┐  ┌────────────┐
           │ Desktop UI │  │  SQLite DB  │  │  Firewall  │
           │ (notify)   │  │  (sentry.db)│  │ (iptables) │
           └────────────┘  └─────────────┘  └────────────┘

🚀 Quick Start

1. Installation

Via pipx (Recommended on Linux)

pipx install net-sentry

Via pip

pip install net-sentry

From source (for development)

git clone https://github.com/Lukasz-Szymanski/net-sentry.git
cd net-sentry

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

2. Launch Interactive TUI Dashboard

netsentry tui

3. Start Background Monitoring Daemon

# Start background daemon
netsentry start

# Check running status
netsentry status

4. Install GNOME Top Panel Indicator (Optional)

To show the live shield status on the Linux top panel:

netsentry install-extension

Log out and log back in (Wayland) or press Alt + F2 -> r (X11) to activate the shield in your top bar.

📖 CLI Commands

⚙️ Configuration

Configuration is automatically generated on first run at: ~/.config/netsentry/config.json

{
  "scan_interval_seconds": 2.0,
  "desktop_notifications": true,
  "notification_cooldown_seconds": 30,
  "auto_block_threats": false,
  "auto_kill_threats": false,
  "threat_score_threshold": 60,
  "telegram_enabled": false,
  "telegram_bot_token": "",
  "telegram_chat_id": "",
  "webhook_enabled": false,
  "webhook_url": "",
  "suspicious_ports": [23, 2323, 4444, 5555, 6667, 9001, 9050, 9051, 1337, 31337],
  "whitelist_ips": ["127.0.0.1", "::1", "0.0.0.0"],
  "whitelist_processes": ["systemd-resolved", "chronyd", "ntpd", "NetworkManager"]
}

🐧 Systemd Service (Autostart)

To enable NetSentry as a systemd user service with a single command:

netsentry install-service

To stop and remove the service:

netsentry uninstall-service

🧪 Testing

pytest -v

📜 License

Released under the MIT License.