FMC-Trap

Un honeypot a bassa interazione che simula la superficie web di un Cisco Secure Firewall Management Center (FMC) e cattura traffico di attacco non autenticato di tipo serializzazione Java (sonde di deserializzazione non sicura stile CVE).

• Sicuro per progettazione: l'applicazione non deserializza oggetti Java; rileva \xac\xed\x00\x05 (e Base64 rO0AB…) ed estrae stringhe di shell o URL utilizzando espressioni regolari ed euristiche.
• Nessuna esecuzione di comandi: gli URL di secondo livello vengono recuperati solo con Python requests in un volume di download non eseguibile.
• Stack orientato alla produzione: Docker Compose con Gunicorn e Caddy opzionale (HTTPS, Let’s Encrypt).

Perché eseguirlo?

Log JSON su singola riga (compatibili con Splunk e ELK), avvisi Telegram opzionali, artefatti di secondo livello hashati e un utente container non root. Il progetto è pensato per ricercatori che necessitano di una trappola mirata stile FMC senza codice di integrazione aggiuntivo.

Requisiti

Elemento	Note
Docker e Docker Compose v2	Installare Docker
VPS o host	Si consiglia un segmento di rete dedicato o isolato
Dominio (opzionale)	Per HTTPS: configurare DNS e consentire il traffico in entrata TCP 80 e TCP 443 verso l'host

Avvio rapido (circa cinque minuti)

1. Clonare

git clone https://github.com/Hassan-Pouladi/Cisco-FMC-honeypot
cd FMC-Trap

2. Configurare l'ambiente

cp .env.example .env

Modificare .env come richiesto (vedi Environment variables). Per distribuzioni dietro il Caddy incluso, impostare TRUST_X_FORWARDED_FOR=1 in modo che gli indirizzi IP dei client nei log riflettano il client originale.

3. Puntare Caddy al tuo dominio

Modificare Caddyfile: sostituire i nomi host segnaposto con il tuo dominio (e www se applicabile):

example.com, www.example.com {
	reverse_proxy fmc-trap:5000
}

Opzionalmente, decommentare il blocco globale email [email protected] in Caddyfile per gli avvisi di scadenza di Let's Encrypt.

4. DNS e firewall (HTTPS)

• Creare record A (e AAAA se applicabili): yourdomain.com verso l'IP pubblico del tuo server, e www se utilizzato.
• Consentire il traffico in entrata TCP 80 e TCP 443 sull'host (gruppo di sicurezza cloud e firewall host, ad esempio ufw allow 80,443/tcp).

5. Directory dati (richieste)

L'applicazione viene eseguita come UID 10001 all'interno del container. La directory montata ./data deve essere scrivibile:

mkdir -p data/logs data/downloads
sudo chown -R 10001:10001 data/logs data/downloads

Senza la proprietà corretta, le richieste POST di exploit potrebbero restituire 500 (Permission denied durante la scrittura di log o blob grezzi).

6. Avviare

docker compose up -d --build

7. Verificare

docker compose ps
curl -sI https://yourdomain.com/

Aspettarsi HTTP/2 200 (o 301 o 302) e Via: Caddy. In un browser, https://yourdomain.com/ dovrebbe mostrare la pagina di login FMC simulata.

Per sapere dove leggere eventi, payload e output Docker, vedere Finding logs, downloads, and service output e Common operations.

Finding logs, downloads, and service output

Tutto ciò che segue è relativo alla directory del progetto (la cartella che contiene docker-compose.yml, solitamente FMC-Trap dopo aver clonato). I percorsi sono sull'host; Docker li monta nel container.

Cosa	Percorso host	Come aprire o seguire
Log eventi (righe JSON)	data/logs/fmc-trap.json	tail -f data/logs/fmc-trap.json (stream live), o aprire in un editor, o importare in Splunk o ELK
Payload di secondo livello scaricati	data/downloads/	I file appaiono solo quando il raccoglitore salva una risposta remota; ogni file è nominato con il suo hash SHA256 (64 caratteri esadecimali), senza estensione. Elencare con ls -la data/downloads (Linux o macOS) o Get-ChildItem data\downloads (Windows PowerShell)
Output del processo applicativo	Non un file; Docker	docker compose logs -f fmc-trap
Caddy (TLS, proxy, ACME)	Non un file; Docker	docker compose logs -f caddy
Avvisi Telegram (opzionale)	Non memorizzato in data/	Impostare TELEGRAM_BOT_TOKEN e TELEGRAM_CHAT_ID in .env; gli avvisi vengono attivati quando gli eventi vengono registrati

Quando qualcosa appare nel file di log: fmc-trap.json riceve un oggetto JSON per riga quando una richiesta corrisponde al comportamento di sonda di deserializzazione (byte magici in un POST). Le richieste GET ordinarie alla pagina di login fittizia non vengono scritte in questo file per impostazione predefinita.

Quando la cartella dei download ha file: le voci appaiono solo se la pipeline estrae un URL da una sonda e il raccoglitore recupera con successo contenuti remoti consentiti entro MAX_DOWNLOAD_MB. Se la directory rimane vuota, potrebbero non esserci ancora URL qualificanti, o i recuperi potrebbero essere bloccati dalla politica nell'applicazione.

Stampa formattata JSON (opzionale): per una singola riga, inviarla tramite python -m json.tool o usare jq se installato.

Common operations

Obiettivo	Comando o azione
Verificare se i container sono in esecuzione	docker compose ps
Riavviare dopo aver modificato .env o Caddyfile	docker compose up -d --build (o docker compose up -d --force-recreate se è cambiato solo l'ambiente)
Fermare lo stack	docker compose down
Seguire i nuovi eventi JSON in modo continuo	tail -f data/logs/fmc-trap.json
Ispezionare gli ultimi eventi	tail -n 50 data/logs/fmc-trap.json
Contare gli artefatti scaricati	Aprire data/downloads nel gestore file, o usare un conteggio file shell su quella directory (i file sono nominati per SHA256)
Confermare che la pagina honeypot si carichi	Aprire https://yourdomain.com/ in un browser o usare curl -sI come nel passaggio di verifica

Architettura

Internet :443/:80 → Caddy (TLS, Let’s Encrypt) → fmc-trap:5000 (Gunicorn/Flask)
                              ↓
                    ./data/logs, ./data/downloads (bind mounts)

• Solo Caddy pubblica 80 e 443 sull'host; il container dell'applicazione non è esposto direttamente (vedi expose: "5000" in Compose).
• Caddy utilizza resolver DNS pubblici (1.1.1.1, 8.8.8.8) all'interno del container in modo che Let's Encrypt abbia successo su host dove il resolver VPS non è raggiungibile da Docker (una limitazione comune su alcuni provider cloud).

Environment variables

Variabile	Scopo	Default / nota
TRUST_X_FORWARDED_FOR	Usare il primo hop X-Forwarded-For come src_ip	1 è raccomandato con Caddy
DECEPTION_STATUS	200 restituisce un corpo HTML; 302 restituisce un reindirizzamento	200
DECEPTION_REDIRECT_URL	Percorso di destinazione quando lo stato è 302	/
MAX_DOWNLOAD_MB	Limite del raccoglitore per URL	16
TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID	Avvisi opzionali	Vuoto disabilita gli avvisi
FMC_SERVER_HEADER	Intestazione della risposta Server	nginx
VT_API_KEY	Riservato	Opzionale

Compose passa queste variabili al servizio fmc-trap; fare riferimento a docker-compose.yml per i dettagli.

JSON log fields (reference)