Honeypot SSH

An interactive and realistic SSH honeypot designed to capture and analyze intrusion attempts, while providing a web dashboard (via Flask) for log visualization.

Table of Contents

1. Project Overview
2. Directory Structure
3. Key Features
4. Prerequisites
5. Installation and Configuration
6. Redirecting Port 22 to Port 2222
7. Running the Project
8. Usage Example
9. Web Dashboard
10. Security and Isolation
11. Contributing
12. License

---

Project Overview

This SSH honeypot aims to simulate a full Linux environment:

• A rich virtual filesystem containing sensitive files.
• An interactive shell supporting internal commands (cd, ls, cat, cp, mv, mkdir, rm, rmdir, touch, echo, etc.), auto-completion (Tab), and pipeline handling.
• An SSH server listening on a non-privileged port (default 2222).
• A web dashboard (Flask) to monitor intrusion attempts and executed commands in real time.

---

Directory Structure

project-root/
├── src/
│   ├── honeypot.py          # Main script (example)
│   ├── alert.log            # Alert logs (exploits, brute force, etc.)
│   ├── auth.log             # Authentication logs (login attempts)
│   ├── commands.log         # Logs of commands executed by attackers
│   ├── server.key           # Persistent SSH key (generated if missing)
│   ├── Makefile             # Makefile (optional)
│   └── requirements.txt     # List of Python dependencies
├── venv/                    # Virtual environment (optional)
├── LICENSE
└── README.md                # This file

Note: File names may vary depending on your setup. The key elements are the logs (auth.log, commands.log, alert.log), the honeypot script, and the SSH key (server.key), which can also be generated using ssh-keygen.

Note: The logs folder contains all log files when the honeypot is running over the SSH tunnel.

---

Key Features

1. Virtual Linux Environment

   • Realistic directory structure with /etc, /home, /root, /var, etc.
   • “Sensitive” files (passwords, SQL dumps, private keys, etc.).

2. Interactive Shell

   • Internal commands: ls, cd, cat, cp, mv, mkdir, rm, rmdir, touch, echo, etc.
   • Pipeline (|) support and auto-completion (Tab).

3. SSH Server

   • Based on Paramiko.
   • Default listening port 2222 (configurable).

4. Web Dashboard

   • Flask for real-time log display.
   • Enhanced interface with Bootstrap.

5. Intrusion Detection

   • Advanced logging in auth.log, commands.log, and alert.log.
   • Brute force detection (IntrusionDetector).
   • Detection of common exploits (SQL injection, XSS, RCE).

---

Prerequisites

• Python 3.8+
• pip (or pip3)
• iptables (for port redirection, Linux only)

---

Installation and Configuration

1. Clone or Copy the Repository

   git clone https://github.com/Amayes985-stack/Honeypot-SSH
   cd Honeypot-SSH/src

2. Create a Virtual Environment (optional but recommended)

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

   pip install -r requirements.txt

4. Check SSH Key The script automatically checks for server.key. If missing, it will generate one. Make sure permissions are correct:

   chmod 600 server.key

---

Redirecting Port 22 to Port 2222

By default, the honeypot listens on port 2222. To expose it on port 22, follow these steps:

1. Enable IP Forwarding

   sudo sysctl -w net.ipv4.ip_forward=1

   To make it permanent:

   echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf

2. Add Redirection Rule (iptables)

   sudo iptables -t nat -A PREROUTING -p tcp --dport 22 -j REDIRECT --to-port 2222

3. Save Rules

   sudo apt install iptables-persistent -y
   sudo netfilter-persistent save

---

Running the Project

1. Start the Honeypot

   python3 honeypot.py

   or

   make honeypot

   You will see:

   SSH Honeypot active on port 2222
   

2. Start the Web Dashboard (Flask) The honeypot.py script includes starting the dashboard (start_dashboard) as a daemon thread, default port 5000. Access it via:

   http://<your-ip>:5000
   

---

Usage Example

• SSH Connection from an external machine:

  ssh user@<your-server-IP> -p 22

  (Traffic will be redirected from port 22 to 2222.)

• Execute Commands: Attackers can run commands like ls, cd /root, cat secrets.txt, etc. The honeypot logs all commands in commands.log.

• Check Logs:

  • auth.log : Login attempts (IP addresses, passwords tried).
  • commands.log : Executed commands.
  • alert.log : Detected suspicious activity (e.g., brute force, exploits).

---

Web Dashboard

The Flask dashboard, accessible at http://<your-ip>:5000, displays the 10 latest commands from commands.log:

• Time : Command timestamp.
• IP : Attacker’s IP address.
• Command : Exact command entered.
• Country : Origin country (via IP-API).

---

Security and Isolation

• Honeypot Isolation: Use a virtual machine or dedicated Docker container.
• Firewall: Block all unnecessary ports and monitor traffic to port 22.
• Active Monitoring: Regularly check logs (auth.log, commands.log, alert.log) and the dashboard for suspicious activity.
• Updates: Keep Kali Linux (or your distribution) updated and regularly check Python dependencies.

---

Contributing

1. Fork the repository.
2. Create a new branch for your changes.
3. Submit a Pull Request with your improvements.

Suggestions for new internal commands, auto-completion improvements, or exploit detection modules are especially welcome!

---

License

This project is licensed under the MIT License. See the LICENSE file for more details.

---

Contact:

• Author: Amayes DJERMOUNE
• Email: [amayes.djermoune2002@gmail.com]
• GitHub: https://github.com/Amayes985-stack/Honeypot-SSH