SSHintel — Lightweight SSH Honeypot

SSHintel is a lightweight SSH honeypot built using Python and Paramiko. It simulates a fake Linux shell to log unauthorized access attempts, capture credentials, and analyze attacker behavior in a controlled environment.

🔧 Features

• Logs SSH login attempts with IP, username, and password
• Provides a simulated Linux shell (a fake, in-memory environment)
• Supports a broad set of reconnaissance and navigation commands (ls, cd, pwd, cat, echo, grep, find, tree, head, tail, wc, stat, ps, df, free, env, id, whoami, etc.)
• Optional --tarpit mode to slow down attackers with delayed output
• Per-session isolated fake filesystem with file creation and reading support
• Local web dashboard for visualizing captured security telemetry (sessions, commands, auth attempts, top attackers)
• Session investigation view — select any session and reconstruct the complete attack timeline chronologically, including source IP, authentication outcome, every command executed with its working directory, and session duration
• Everything is simulated — commands never execute on the host, never access the real filesystem, and make no network requests.

SSHintel is not a full Bash/Linux shell. It simulates a believable subset of common commands to gather attacker telemetry. Commands are dispatched by a lightweight registry; adding a command means adding a small handler function.

🛠️ Setup

1. 📦 Install Dependencies

pip install -r requirements.txt

Note: The SSH host key is automatically generated on first run. No manual key generation needed.

🚀 Running the Honeypot

Run the honeypot with a specific port, username, and password:

python3 run.py serve --port 2222 --username user1 --password pass123

Default port is 2222 and host is 0.0.0.0.

The honeypot automatically generates an SSH host key at static/server.key on first run if one doesn't exist. No manual key generation is needed.

To enable tarpit mode:

python3 run.py serve --port 2222 --username user1 --password pass123 --tarpit

To disable SQLite telemetry (JSONL only):

python3 run.py serve --port 2222 --username user1 --password pass123 --no-db

🛡️ Connection limits & timeouts

SSHintel guards against resource exhaustion from many concurrent connections or connections kept alive indefinitely. These are configurable via the CLI:

Example:

python3 run.py serve --port 2222 --username user1 --password pass123 \
  --max-connections 25 --auth-timeout 30 --session-idle-timeout 300

When too many connections are open, the extra connection is closed immediately and a connection_rejected security event (with reason: connection_limit) is written to the JSONL log. A stalled authentication is recorded as a disconnect with reason: auth_timeout; an idle shell ends with reason: idle_timeout.

Tarpit mode intentionally sends output slowly to keep an attacker engaged, so the tarpit banner loop is not subject to the inactivity timeout — but tarpit sessions do count against the connection limit.

📊 Dashboard

SSHintel includes a local web dashboard that visualizes the security telemetry stored in SQLite.

Start the dashboard

python3 run.py dashboard

Then open http://localhost:5000 in your browser.

The dashboard reads from the SQLite database at data/sshintel.db by default. Start the honeypot first so telemetry is being captured, then launch the dashboard to watch it populate.

What it displays

• KPI cards — total sessions, unique source IPs, authentication attempts, successful/failed authentications, and commands executed
• Activity chart — connections over time, grouped by hour
• Top commands — the most frequently run attacker commands
• Targeted usernames — which usernames attackers are trying
• Recent sessions — click any session ID to investigate it
• Recent activity — the latest telemetry events in a searchable table

Session investigation

Click a session ID (or navigate to /session/<session_id>) to open the session investigation view, which reconstructs a single attack chronologically:

• Session summary — source IP, username, start/end times, duration, authentication result, disconnect reason
• Attack timeline — every event (connect, auth attempts, commands, disconnect) in chronological order
• Command sequence — a compact $ command view of everything the attacker typed, with working directories

Example workflow

# Terminal 1: start the honeypot
python3 run.py serve --port 2222 --username user1 --password pass123

# Terminal 2: start the dashboard
python3 run.py dashboard

# Terminal 3: simulate an attacker
ssh user1@localhost -p 2222
# (run some commands, then exit)

Then open http://localhost:5000 to inspect the captured activity.

The dashboard supports live telemetry — it polls the honeypot every 2 seconds and updates automatically. New sessions, commands, and events appear in real-time without refreshing the page. A live indicator (● Live) shows the connection status.

🔐 Testing from Another Terminal

Open a second terminal and try connecting:

ssh user1@localhost -p 2222

If the credentials match, you’ll be dropped into the emulated shell.

🚑 Optional: Clear Known Hosts (If Reconnecting)

To remove stale SSH fingerprints:

notepad "%USERPROFILE%\.ssh\known_hosts"

Delete the relevant line containing localhost or the honeypot's IP.

📝 Logged Information

• Credentials are logged to creds_logger
• Shell commands are logged via funnel_logger
• Structured security events are written to log_files/events.jsonl as JSON Lines (JSONL) — one valid JSON object per line

Each JSONL event includes a UTC ISO-8601 timestamp, an event_type, a unique session_id, and the source_ip. Connection, authentication attempts/results, command execution, tarpit activation, and disconnects are all recorded as structured events.

Each incoming SSH connection is tracked as an independent session with its own session_id. A session records the source IP, connect/disconnect times, the authentication outcome, and the connection duration, and every event generated within that connection carries the same session_id (so authentication attempts, commands, and disconnects can be tied back to a single connection). Sessions are isolated per connection — no state is shared between concurrent clients.

Every session also receives its own isolated, in-memory fake filesystem — the simulated filesystem is created fresh for each connection and cleaned up when the connection ends. Files, directories, and the working directory created or changed by one attacker are never visible to another attacker connected at the same time. The entire filesystem is simulated in Python memory and never touches the real host filesystem.

Current event_type values: connect, auth_attempt, auth_success, auth_failure, command, disconnect, connection_rejected, tarpit.

📂 File Structure

SSHintel/
├── honeypot/                  # Core honeypot logic
│   ├── __init__.py
│   ├── main.py                # Accept loop + connection limiting
│   ├── handlers.py            # SSH transport setup + emulated shell
│   ├── server.py              # Paramiko server interface (auth)
│   ├── session.py             # Per-connection session tracking
│   ├── fs.py                  # In-memory fake filesystem (isolated per session)
│   ├── shell.py               # Fake shell: command registry + dispatcher
│   ├── limits.py              # Thread-safe concurrent connection limiting
│   ├── logger.py              # JSONL event logging + SQLite bridge
│   └── telemetry_store.py     # SQLite telemetry store + query layer
│
├── dashboard/                 # Local web dashboard
│   ├── app.py                 # Flask application + API routes
│   ├── templates/
│   │   ├── index.html         # Main dashboard template
│   │   └── session.html       # Session investigation template
│   └── static/
│       ├── style.css          # Dashboard styles
│       ├── dashboard.js       # Main dashboard JS (live updates)
│       └── session.js         # Session investigation JS
│
├── log_files/                 # Runtime logs (git-ignored)
│   ├── creds_audits.log       # Credential attempts
│   ├── cmd_audits.log         # Command audit trail
│   └── events.jsonl           # Structured JSONL security events
│
├── data/                      # SQLite database (git-ignored)
│   └── sshintel.db
│
├── static/                    # SSH host key (auto-generated)
│   └── server.key
│
├── .github/workflows/         # CI configuration
│   └── tests.yml
│
├── Dockerfile
├── README.md
├── requirements.txt           # Runtime dependencies (paramiko, flask)
├── requirements-dev.txt       # Test dependencies (pytest, pytest-cov)
└── run.py                     # CLI entrypoint

💪 Run with Docker (Alternative Method)

If you prefer to run the honeypot in a containerized environment, you can use the included Dockerfile.

🔨 Build the Docker Image

docker build -t sshintel .

This creates a Docker image named sshintel.

🚀 Run the Container

docker run -p 2222:2222 sshintel

This will:

• Automatically generate the SSH private key at static/server.key (if it doesn't already exist)
• Launch the honeypot on port 2222 with default credentials:
  username: user1, password: pass123

🔮 Test the Honeypot

Open a second terminal and connect via SSH:

ssh user1@localhost -p 2222

You’ll be dropped into the simulated shell if the credentials match.

🧼 Stop and Clean Up

To stop the container:

docker ps  # Find the container ID
docker stop <container_id>

To remove the image:

docker rmi sshintel

You can also export the image using docker save -o sshintel.tar sshintel and load it later with docker load -i sshintel.tar.

📄 License

This project is licensed under the MIT License.

👤 Author

Sonit Bahl
🔗 LinkedIn
🔗 Portfolio