sshd-bruteforce-detector/README.md

🚨 sshd-bruteforce-detector

A lightweight, real-time SSH brute-force detection tool for Linux systems using systemd-journal.

It monitors sshd logs, groups failed login attempts by source IP, and alerts you when suspicious activity crosses a defined threshold.

Because manually reading logs is fun… until it isn’t.

---

✨ Features

• 📡 Real-time monitoring via systemd.journal
• 🔍 Detects repeated failed SSH authentication attempts
• 🌐 Groups events per remote host (IP)
• ⏱ Configurable time window (e.g. 5m, 1h)
• 🚦 Configurable max attempts threshold
• 🧾 Supports config file (.toml) and CLI args
• 🪶 Lightweight and dependency-minimal

---

⚙️ How It Works

1. Listens to sshd.service logs from systemd journal
2. Filters failed authentication messages
3. Groups attempts by rhost (IP address)
4. Keeps only recent attempts within a time window
5. Triggers alert if attempts ≥ threshold

---

🚀 Installation

git clone https://github.com/yourusername/sshd-bruteforce-detector.git
cd sshd-bruteforce-detector
pip install -r requirements.txt

Requires Linux with systemd and Python 3.11+ (for tomllib).

---

▶️ Usage

Basic run

python main.py

With arguments

python main.py -w 5m -m 10

With config file

python main.py -c config.toml

---

🧩 Configuration

You can configure via CLI or TOML file.

Example config.toml

window = "5m"
max_attempts = 5

Options

Option	Description	Default
--window, -w	Time window to group attempts (1h, 5m, 30s)	5m
--max-attempts, -m	Max failed attempts before alert	5
--config, -c	Path to TOML config file	—

CLI args override config file values.

---

📊 Example Output

INFO  Authentication failure from host 192.168.1.10 for user root on sshd
INFO  Authentication failure from host 192.168.1.10 for user admin on sshd
CRITICAL 5 authentication failure events from 192.168.1.10 on sshd in 42 seconds.

---

🧠 Detection Logic

The detection is intentionally simple:

len(recent_attempts) >= max_attempts

No AI, no magic. Just effective signal over noise.

---

🛑 Stopping the Program

Handles signals gracefully:

• Ctrl + C → exits with code 130
• SIGTERM → clean exit

---

📁 Project Structure

.
├── main.py            # Entry point
├── detector.py        # Detection logic
├── config.py          # CLI + config handling
├── message_parse.py   # Log parsing
├── utils.py           # Helpers (window parsing, filtering)

---

⚠️ Limitations

• Only works on systems using systemd
• Depends on log format consistency (authentication failure;)
• No automatic banning (yet 👀)

---

💡 Future Ideas

• Auto-ban IPs via iptables / nftables
• Export metrics (Prometheus)
• Web dashboard
• Alert integrations (Slack, email, etc.)

---

📜 License

MIT — do whatever you want, just don’t blame me if your server catches fire.