SSHintel — Honeypot SSH leggero

Last Commit Repo Size

SSHintel è un honeypot SSH leggero realizzato con Python e Paramiko. Simula una finta shell Linux per registrare i tentativi di accesso non autorizzati, catturare le credenziali e analizzare il comportamento degli attaccanti in un ambiente controllato.

🔧 Funzionalità

Registra i tentativi di accesso SSH con IP, nome utente e password
Fornisce una shell Linux simulata (un ambiente fittizio in memoria)
Supporta un'ampia gamma di comandi di ricognizione e navigazione (ls, cd, pwd, cat, echo, grep, find, tree, head, tail, wc, stat, ps, df, free, env, id, whoami, ecc.)
Modalità opzionale --tarpit per rallentare gli attaccanti con output ritardato
Filesystem fittizio isolato per sessione con supporto alla creazione e alla lettura di file
Dashboard web locale per visualizzare la telemetria di sicurezza catturata (sessioni, comandi, tentativi di autenticazione, principali attaccanti)
Vista di analisi delle sessioni — seleziona qualsiasi sessione e ricostruisci cronologicamente la completa timeline dell'attacco, inclusi IP di origine, esito dell'autenticazione, ogni comando eseguito con la relativa directory di lavoro e la durata della sessione
Tutto è simulato — i comandi non vengono mai eseguiti sull'host, non accedono mai al filesystem reale e non effettuano richieste di rete.

SSHintel non è una shell Bash/Linux completa. Simula un sottoinsieme credibile di comandi comuni per raccogliere telemetria sugli attaccanti. I comandi vengono smistati tramite un registro leggero; aggiungere un comando significa aggiungere una piccola funzione handler.

🛠️ Installazione

1. 📦 Installa le dipendenze

pip install -r requirements.txt

Nota: La chiave host SSH viene generata automaticamente al primo avvio. Non è necessaria alcuna generazione manuale della chiave.

🚀 Esecuzione dell'Honeypot

Avvia l'honeypot con una porta, un nome utente e una password specifici:

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

La porta predefinita è 2222 e l'host è 0.0.0.0.

L'honeypot genera automaticamente una chiave host SSH in static/server.key al primo avvio se non ne esiste una. Non è necessaria alcuna generazione manuale della chiave.

Per abilitare la modalità tarpit:

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

Per disabilitare la telemetria SQLite (solo JSONL):

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

File di configurazione e variabili d'ambiente

Le impostazioni del sensore seguono l'ordine CLI > ambiente > file di configurazione > valori predefiniti. Solo i flag CLI forniti esplicitamente sovrascrivono le altre fonti. Questo vale per serve; i comandi dashboard/query mantengono le proprie impostazioni CLI.

Su Python 3.11+:

cp sshintel.toml.example sshintel.toml
chmod 600 sshintel.toml
python3 run.py serve

Su Python 3.8/3.10, utilizzare l'equivalente JSON senza dipendenze:

cp sshintel.json.example sshintel.json
chmod 600 sshintel.json
python3 run.py serve

Modifica il file copiato prima della distribuzione. TOML richiede Python 3.11+; le versioni precedenti falliscono con un'istruzione chiara di usare JSON. Senza un file esplicito, SSHintel cerca sshintel.toml, poi sshintel.json nella directory corrente. Usa serve --config /path/to/settings.json o HONEYPOT_CONFIG per selezionare un altro file (--config ha la precedenza). File espliciti mancanti, file malformati, chiavi sconosciute e valori non validi falliscono prima dell'avvio del server o del database. I percorsi dei file all'interno della configurazione sono relativi alla directory di lavoro del processo, non al file di configurazione.

Chiave del file	Variabile d'ambiente	Predefinito
`host`	`HONEYPOT_HOST`	`0.0.0.0`
`port`	`HONEYPOT_PORT` (alias legacy: `PORT`)	`2222`
`username`	`HONEYPOT_USERNAME`	`user1`
`password`	`HONEYPOT_PASSWORD`	`pass123`
`tarpit`	`HONEYPOT_TARPIT`	`false`
`tarpit_max_seconds`	`HONEYPOT_TARPIT_MAX_SECONDS`	`120`
`max_connections`	`HONEYPOT_MAX_CONNECTIONS`	`50`
`auth_timeout`	`HONEYPOT_AUTH_TIMEOUT`	`60`
`session_idle_timeout`	`HONEYPOT_SESSION_IDLE_TIMEOUT`	`300`
`sensor_id`	`HONEYPOT_SENSOR_ID`	non impostato
`db_path`	`HONEYPOT_DB_PATH`	`data/sshintel.db`
`no_db`	`HONEYPOT_NO_DB`	`false`
`fetch_payloads`	`HONEYPOT_FETCH_PAYLOADS`	`false` (riservato)

I booleani delle variabili d'ambiente accettano true/false, 1/0, yes/no e on/off. HONEYPOT_PORT ha la precedenza su PORT. Le porte devono essere 1–65535 e i limiti e i timeout devono essere interi positivi. Usa --no-tarpit, --db-enabled o --no-fetch-payloads per sovrascrivere un'impostazione true a priorità inferiore. I percorsi del database usano il flag CLI --db esistente. Il recupero dei payload non è implementato: abilitare fetch_payloads viene rifiutato anziché ignorato silenziosamente.

I file locali sshintel.toml/sshintel.json sono ignorati da Git ed esclusi dalle build Docker perché possono contenere credenziali. Monta invece un file di configurazione in sola lettura in un container. Docker consuma direttamente le variabili d'ambiente (senza interpolazione shell delle credenziali); i suoi ENV predefiniti esistenti hanno la precedenza su un file montato. Sovrascrivi quelle variabili secondo necessità o usa flag CLI espliciti.

🛡️ Limiti di connessione e timeout

SSHintel protegge dall'esaurimento delle risorse causato da molte connessioni simultanee o da connessioni mantenute attive indefinitamente. Questi sono configurabili tramite la CLI:

Flag	Predefinito	Scopo
`--max-connections`	`50`	Numero massimo di connessioni attive simultanee; le connessioni in eccesso vengono rifiutate e registrate come evento `connection_rejected`
`--auth-timeout`	`60` (s)	Tempo consentito per completare l'handshake/autenticazione SSH; i client bloccati vengono disconnessi
`--session-idle-timeout`	`300` (s)	Timeout di inattività per una shell autenticata; una sessione inattiva viene terminata, ma un attaccante che sta attivamente digitando non viene mai terminato

Esempio:

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

Quando sono aperte troppe connessioni, la connessione in eccesso viene chiusa immediatamente e un evento di sicurezza connection_rejected (con reason: connection_limit) viene scritto nel log JSONL. Un'autenticazione bloccata viene registrata come disconnessione con reason: auth_timeout; una shell inattiva termina con reason: idle_timeout.

La modalità tarpit invia intenzionalmente l'output lentamente per mantenere coinvolto un attaccante, quindi il ciclo del banner tarpit non è soggetto al timeout di inattività — ma le sessioni tarpit sono conteggiate ai fini del limite di connessioni.

📊 Dashboard

SSHintel include una dashboard web locale che visualizza la telemetria di sicurezza memorizzata in SQLite.

Avviare la dashboard

python3 run.py dashboard

Poi apri http://localhost:5000 nel tuo browser.

La dashboard legge dal database SQLite in data/sshintel.db per impostazione predefinita. Avvia prima l'honeypot in modo che la telemetria venga catturata, poi avvia la dashboard per osservarla popolarsi.

SSHintel

Più Popolari