153 lines
3.3 KiB
Markdown
153 lines
3.3 KiB
Markdown
# 🚨 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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
### With arguments
|
||
|
||
```bash
|
||
python main.py -w 5m -m 10
|
||
```
|
||
|
||
### With config file
|
||
|
||
```bash
|
||
python main.py -c config.toml
|
||
```
|
||
|
||
---
|
||
|
||
## 🧩 Configuration
|
||
|
||
You can configure via CLI or TOML file.
|
||
|
||
### Example `config.toml`
|
||
|
||
```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
|
||
|
||
```text
|
||
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:
|
||
|
||
```python
|
||
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.
|