🛡️ SSH Honeypot v2.0

Deception-based threat intelligence collection for cybersecurity researchers, SOC teams, and AI/ML enthusiasts.

Capture real attacker behavior → enrich with threat intel feeds → map to MITRE ATT&CK → analyze, alert, and learn.

Created by Jainam Maru

---

🔭 Overview: Why a Honeypot?

Real-world attack data is the single best training set for detection engineering, yet most defenders never see it. An SSH honeypot sits on the front lines and turns every credential-stuffing bot and manual intruder into structured intelligence:

• 📡 Collect — raw auth attempts, executed commands, and SFTP activity from real attackers
• 🌍 Enrich — geolocation (GeoIP2 / ip-api.com), threat scoring (AbuseIPDB, AlienVault OTX, VirusTotal)
• 🧠 Map — automatic classification to MITRE ATT&CK techniques (T1110, T1059, T1098…)
• 💾 Store — human-readable logs, structured JSON, and a queryable SQLite database
• 🔔 Act — webhook / Slack / Discord / email alerts with per-severity thresholds

This project is the data-collection layer of a full threat-intelligence pipeline — pair it with dark-sentinel for dark-web coverage or feed the JSON output into your own detection stack.

🏗️ Architecture

flowchart LR
    A[Attacker Bot / Manual Intruder] -->|TCP :2222| B

    subgraph HP[SSH Honeypot]
        B[Paramiko SSH Server<br/>Dynamic Banner Spoofing] --> C[Auth Attempt Capture<br/>username · password · key fp]
        C --> D[Fake Shell / SFTP<br/>command & file activity]
        C --> E[Rate Limiter +<br/>Auto-Ban]
    end

    D --> F[Log Parser & Enricher]
    E --> F
    F -->|GeoIP2 / ip-api| G[IP Geolocation<br/>city · country · ASN]
    F -->|AbuseIPDB · OTX · VT| H[Threat Scoring<br/>0-10 severity]
    F --> I[MITRE ATT&CK Mapper<br/>T1110 · T1059 · T1098 · ...]
    I --> J[(SQLite DB)]
    I --> K[attacks.json / attacks.log]
    J --> L[Web Dashboard<br/>FastAPI · live stats]
    K --> L
    L --> M[Alerting<br/>Webhook · Slack · Discord · Email]

Loading

Data flow: every keystroke an attacker types lands in attacks.json with an ATT&CK technique ID, a geolocation, and a severity score — ready for SIEM ingestion or ML analysis.

🚀 Quick Start

Option A — One-line installer (coming soon)

curl -sSL https://raw.githubusercontent.com/Dev9269/ssh-honeypot/main/install.sh | bash

Option B — Manual

git clone https://github.com/Dev9269/ssh-honeypot.git
cd ssh-honeypot
pip install -r requirements.txt

# Basic honeypot on :2222
python main.py

# With live dashboard on :8080
python main.py --dashboard

# With YAML config
python main.py --config honeypot.yaml

Docker Deployment

docker-compose up --build

# Or manually
docker build -t ssh-honeypot .
docker run -d -p 2222:2222 -p 8080:8080 ssh-honeypot

🆕 What's New in v2.0

• Fake Shell Interaction — Captures attacker commands in a realistic Linux shell environment
• IP Geolocation — Maps attacker IPs to city/country/ASN (GeoIP2 or ip-api.com fallback)
• Threat Intelligence — AbuseIPDB, AlienVault OTX, VirusTotal integration
• Real-time Alerts — Webhook, Slack, Discord, and email notifications
• Web Dashboard — FastAPI-based live monitoring UI with auth
• SQLite Database — Structured storage for querying and analysis
• MITRE ATT&CK Mapping — Auto-tags attacks with TTP IDs
• Rate Limiting — Per-IP connection throttling with auto-ban
• Dynamic Fingerprinting — Randomized SSH banners to avoid detection
• Log Rotation — Automatic rotation with size/backup limits
• YAML Configuration — Full config via honeypot.yaml
• Docker Support — Containerized deployment with docker-compose
• SFTP Simulation — Fake file transfer environment
• Prometheus Metrics — /metrics endpoint for monitoring

✨ Features

Feature	Description
SSH Simulation	Realistic OpenSSH banner spoofing with dynamic fingerprint rotation
Auth Logging	Captures username, password, key fingerprint, method, timestamp
Command Capture	Fake shell records every command attackers execute
Geolocation	IP → location mapping (offline GeoIP2 or free ip-api.com API)
Threat Scoring	Multi-source threat intelligence scoring (0-10)
MITRE ATT&CK	Auto-classifies attacks to TTP framework (T1110, T1059, T1098, etc.)
Alerts	Webhook, Slack, Discord, SMTP email notifications
Dashboard	Real-time web UI with stats, top IPs, recent attacks
Rate Limiting	Per-IP connection limit with automatic temp bans
IP Filtering	Whitelist/blacklist by IP or CIDR range
Database	SQLite for structured querying and analytics
Docker	Containerized via Dockerfile + docker-compose
macOS .app	Native macOS application support

🖥️ Console Output

[*] SSH Honeypot v2.0.0 listening on 0.0.0.0:2222
[*] Fake banner: SSH-2.0-OpenSSH_7.9p1 Debian-10
[*] Logs: logs/attacks.log, logs/attacks.json
[*] Database: logs/honeypot.db
[*] Geolocation: enabled
[*] Threat Intelligence: enabled
[*] Alerts: enabled
[*] Fake Shell: enabled (ubuntu-server)
[*] Dashboard: http://127.0.0.1:8080
[*] Press Ctrl+C to stop
[+] Connection from 192.168.1.100:54321 [New York, US] [threat: 6/10]
[+] Connection from 10.0.0.5:12345 [London, GB] [threat: 0/10]
[!] Rate limit exceeded for 203.0.113.5
[-] Connection closed from 192.168.1.100 (duration: 12.5s)

🐚 Fake Shell Example

When an attacker connects (the honeypot rejects auth but still serves a shell):

Linux ubuntu-server 5.15.0-91-generic #101-Ubuntu SMP Tue Nov 14 13:30:08 UTC 2025 x86_64 GNU/Linux

root@ubuntu-server:/root$ whoami
root
root@ubuntu-server:/root$ id
uid=0(root) gid=0(root) groups=0(root)
root@ubuntu-server:/root$ uname -a
Linux ubuntu-server 5.15.0-91-generic #101-Ubuntu SMP...
root@ubuntu-server:/root$ cat /etc/passwd
root:x:0:0:root:/root:/bin/bash
root@ubuntu-server:/root$ exit
logout

All commands are logged to attacks.log, attacks.json, and the SQLite database with MITRE ATT&CK classifications.

📁 Project Structure

ssh-honeypot/
├── honeypot/
│   ├── __init__.py
│   ├── server.py       # SSH server + client handler
│   ├── shell.py        # Fake shell with command responses
│   ├── config.py       # Configuration (YAML + defaults)
│   ├── logger.py       # Logging (.log, .json, rotation)
│   ├── db.py           # SQLite database backend
│   ├── geo.py          # IP geolocation (GeoIP2 + ip-api.com)
│   ├── intel.py        # Threat intelligence (AbuseIPDB, OTX, VT)
│   ├── alerts.py       # Alerting (webhook, Slack, Discord, email)
│   ├── ratelimiter.py  # Per-IP rate limiter with auto-ban
│   ├── analyzer.py     # MITRE ATT&CK framework mapping
│   ├── dashboard.py    # FastAPI web dashboard
│   └── sftp_server.py  # SFTP simulation
├── logs/               # Attack logs + database
├── main.py             # Entry point
├── honeypot.yaml       # YAML configuration
├── Dockerfile          # Docker build
├── docker-compose.yml  # Docker compose
├── requirements.txt    # Python dependencies
└── README.md

⚙️ Configuration (YAML)

All settings can be configured via honeypot.yaml:

server:
  host: 0.0.0.0
  port: 2222

rate_limit:
  max_connections: 10
  window: 60
  ban_duration: 300

alerts:
  enabled: true
  slack_webhook: "https://hooks.slack.com/services/..."
  discord_webhook: "https://discord.com/api/webhooks/..."
  min_severity: medium

See the full honeypot.yaml file for all options.

📊 Log Files

attacks.log (Human-readable)

2026-06-24 14:30:22,123 - IP: 192.168.1.100 | Username: root | Password: password123 | Method: password | MITRE: T1110:Brute Force
2026-06-24 14:30:45,678 - Activity | IP: 10.0.0.5 | command: whoami

attacks.json (Structured — SIEM/ML ready)

[
  {
    "event": "auth_attempt",
    "timestamp": "2026-06-24T14:30:22.123456",
    "ip": "192.168.1.100",
    "username": "root",
    "password": "password123",
    "method": "password",
    "mitre": "T1110:Brute Force"
  }
]

SQLite Database

Query attack data directly:

sqlite3 logs/honeypot.db "SELECT ip, username, password FROM auth_attempts ORDER BY timestamp DESC LIMIT 10;"

🎯 MITRE ATT&CK Coverage

Technique	ID	Detected By
Brute Force	T1110	Password auth attempts
Account Manipulation	T1098	SSH key auth attempts
Command & Scripting	T1059	Shell command execution
Network Discovery	T1046	Recon commands (nmap, etc.)
Remote Services	T1021	Lateral movement commands
Privilege Escalation	T1068	sudo/chown commands
Defense Evasion	T1562	rm -rf, shutdown, etc.
Data Collection	T1005	tar, zip, find commands

🏷️ Topics & Tags

honeypot · ssh · cybersecurity · threat-intelligence · deception · security-tools · mitre-attack · honeypot-ssh · intrusion-detection · network-security

🔒 Security Notice

This tool is for authorized security research and education only.

• Deploy only on networks you own or have permission to monitor
• Comply with all applicable laws
• The author assumes no liability for misuse

📄 License

MIT License — see LICENSE

🙏 Acknowledgments

• Paramiko — SSH protocol library
• MaxMind GeoIP2 — Geolocation data
• AbuseIPDB — Threat intelligence
• MITRE ATT&CK — TTP framework