SSH Honeypot

⚠️ EDUCATIONAL USE ONLY - FOR CYBERSECURITY DEFENSE RESEARCH

This SSH honeypot is designed strictly for educational purposes and cybersecurity defense training. It helps security professionals understand attack patterns, learn about threat actors' techniques, and improve defensive security measures.

IMPORTANT: This tool must only be deployed in controlled, authorized environments. Unauthorized deployment or use for malicious purposes is strictly prohibited and may violate laws and regulations.

What is a Honeypot?

A honeypot is a security mechanism that creates a decoy system to attract attackers. By analyzing attacker behavior in the honeypot, security teams can:

• Study attack methodologies and tools
• Identify new threats and vulnerabilities
• Develop better defensive strategies
• Train security personnel

Features

• Full SSH protocol implementation using Rust
• Captures authentication attempts (passwords, public keys)
• Logs all commands executed by attackers
• Realistic fake shell environment
• JSON-based structured logging
• Docker containerization for isolation
• Production-grade async architecture

Architecture

src/
├── main.rs       - Entry point and connection handling
├── server.rs     - SSH protocol handler
├── session.rs    - Session data structures
└── logger.rs     - Attack logging and reporting

Setup Instructions

Prerequisites

• Docker and Docker Compose installed
• OR Rust 1.83+ installed locally

Option 1: Docker (Recommended)

1. Build and run the honeypot:

docker-compose up -d

2. View logs:

docker-compose logs -f

3. Stop the honeypot:

docker-compose down

The honeypot will listen on port 2222. Attack logs are stored in ./logs/ directory.

Option 2: Native Build

1. Build the project:

cargo build --release

2. Run the honeypot:

./target/release/ssh-honeypot

3. Optionally set custom address:

HONEYPOT_ADDR=0.0.0.0:2222 ./target/release/ssh-honeypot

Accessing Logs

Logs are stored in the logs/ directory in JSON Lines format:

• auth_YYYYMMDD.jsonl - Authentication attempts
• commands_YYYYMMDD.jsonl - Commands executed by attackers

Example log entry:

{
  "timestamp": "2025-10-08T12:34:56Z",
  "source_ip": "192.168.1.100",
  "auth_attempts": [
    {
      "username": "root",
      "method": "password",
      "credential": "admin123"
    }
  ]
}

Testing the Honeypot

Test locally with:

ssh -p 2222 localhost

Try various usernames and passwords to see them logged.

Security Considerations

1. Isolation: Always run in an isolated network environment
2. Monitoring: Regularly review logs for suspicious activity
3. Legal Compliance: Ensure deployment complies with local laws
4. Network Segmentation: Never connect to production networks
5. Data Protection: Secure logged data appropriately

Configuration

Environment variables:

• HONEYPOT_ADDR: Bind address (default: 0.0.0.0:2222)
• RUST_LOG: Logging level (info, debug, warn)

Limitations

This is an educational honeypot with intentional limitations:

• No actual shell executionx
• Simulated command responses
• Authentication always fails
• No data exfiltration capabilities

License

This project is provided as-is for educational purposes only.

Author

Kira ~ github.com/Bas3line

Disclaimer

THIS SOFTWARE IS FOR EDUCATIONAL AND DEFENSIVE CYBERSECURITY PURPOSES ONLY.

The authors and contributors are not responsible for any misuse or damage caused by this software. Users must ensure they have proper authorization before deploying this honeypot and must comply with all applicable laws and regulations.

By using this software, you acknowledge that:

• You will only use it in authorized, controlled environments
• You understand the legal implications of deploying honeypots
• You will not use it for malicious purposes
• You accept full responsibility for your use of this tool