FMC-Trap

Um honeypot de baixa interação que imita a superfície web de um Cisco Secure Firewall Management Center (FMC) e captura tráfego de ataque não autenticado do tipo serialização Java (sondagens de desserialização insegura estilo CVE).

• Seguro por design: a aplicação não desserializa objetos Java; ela detecta \xac\xed\x00\x05 (e Base64 rO0AB…) e extrai strings de shell ou URL usando expressões regulares e heurísticas.
• Sem execução de comandos: URLs de segundo estágio são recuperadas apenas com Python requests em um volume de downloads não executável.
• Stack orientada à produção: Docker Compose com Gunicorn e Caddy opcional (HTTPS, Let's Encrypt).

Por que executá-lo?

Logs JSON de linha única (compatíveis com Splunk e ELK), alertas opcionais via Telegram, artefatos de segundo estágio com hash e um usuário de contêiner não root. O projeto é destinado a pesquisadores que precisam de uma armadilha focada no FMC sem código adicional de integração.

Requisitos

Item	Observações
Docker e Docker Compose v2	Instalar Docker
VPS ou host	Recomenda-se um segmento de rede dedicado ou isolado
Domínio (opcional)	Para HTTPS: configure DNS e permita conexões de entrada TCP 80 e TCP 443 no host

Início rápido (aproximadamente cinco minutos)

1. Clonar

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

2. Configurar ambiente

cp .env.example .env

Edite .env conforme necessário (veja Variáveis de ambiente). Para implantações atrás do Caddy incluído, defina TRUST_X_FORWARDED_FOR=1 para que os endereços IP dos clientes nos logs reflitam o cliente original.

3. Apontar Caddy para seu domínio

Edite Caddyfile: substitua os hostnames de exemplo por seu domínio (e www, se aplicável):

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

Opcionalmente, descomente o bloco global email [email protected] no Caddyfile para notificações de expiração do Let's Encrypt.

4. DNS e firewall (HTTPS)

• Crie registros A (e AAAA, se aplicável): seudominio.com para o IP público do seu servidor, e www se usado.
• Permita conexões de entrada TCP 80 e TCP 443 no host (grupo de segurança da nuvem e firewall do host, por exemplo, ufw allow 80,443/tcp).

5. Diretórios de dados (obrigatório)

A aplicação é executada como UID 10001 dentro do contêiner. O diretório montado por bind ./data deve ser gravável:

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

Sem a propriedade correta, requisições POST de exploração podem retornar 500 (Permissão negada ao gravar logs ou blobs brutos).

6. Iniciar

docker compose up -d --build

7. Verificar

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

Espere HTTP/2 200 (ou 301 ou 302) e Via: Caddy. No navegador, https://seudominio.com/ deve exibir a página de login simulada do FMC.

Para saber onde ler eventos, payloads e saída do Docker, veja Encontrar logs, downloads e saída do serviço e Operações comuns.

Encontrar logs, downloads e saída do serviço

Tudo abaixo é relativo ao diretório do seu projeto (a pasta que contém docker-compose.yml, geralmente FMC-Trap após clonar). Os caminhos são no host; o Docker os monta por bind no contêiner.

O quê	Caminho no host	Como abrir ou acompanhar
Log de eventos (linhas JSON)	data/logs/fmc-trap.json	tail -f data/logs/fmc-trap.json (fluxo ao vivo), ou abra em um editor, ou ingira no Splunk ou ELK
Payloads de segundo estágio baixados	data/downloads/	Os arquivos aparecem apenas quando o harvester salva uma resposta remota; cada arquivo é nomeado com seu hash SHA256 (64 caracteres hexadecimais), sem extensão. Liste com ls -la data/downloads (Linux ou macOS) ou Get-ChildItem data\downloads (Windows PowerShell)
Saída do processo da aplicação	Não é um arquivo; Docker	docker compose logs -f fmc-trap
Caddy (TLS, proxy, ACME)	Não é um arquivo; Docker	docker compose logs -f caddy
Alertas Telegram (opcional)	Não armazenado em data/	Defina TELEGRAM_BOT_TOKEN e TELEGRAM_CHAT_ID no .env; alertas são disparados quando eventos são registrados

Quando algo aparece no arquivo de log: fmc-trap.json recebe um objeto JSON por linha quando uma requisição corresponde ao comportamento de sonda de desserialização (bytes mágicos em um POST). Requisições GET comuns para a página de login falsa não são gravadas neste arquivo por padrão.

Quando a pasta de downloads tem arquivos: as entradas aparecem apenas se o pipeline extrair uma URL de uma sonda e o harvester conseguir buscar conteúdo remoto permitido dentro de MAX_DOWNLOAD_MB. Se o diretório permanecer vazio, pode não haver URLs qualificadas ainda, ou as buscas podem estar bloqueadas por política na aplicação.

Pretty-printing JSON (opcional): para uma única linha, canalize via python -m json.tool ou use jq se instalado.

Operações comuns

Objetivo	Comando ou ação
Ver se os contêineres estão em execução	docker compose ps
Reiniciar após editar .env ou Caddyfile	docker compose up -d --build (ou docker compose up -d --force-recreate se apenas o env mudou)
Parar a stack	docker compose down
Acompanhar novos eventos JSON continuamente	tail -f data/logs/fmc-trap.json
Inspecionar os últimos eventos	tail -n 50 data/logs/fmc-trap.json
Contar artefatos baixados	Abra data/downloads no gerenciador de arquivos, ou use uma contagem de arquivos no shell nesse diretório (os arquivos são nomeados pelo SHA256)
Confirmar que a página do honeypot carrega	Abra https://seudominio.com/ no navegador ou use curl -sI como no passo de verificação

Arquitetura

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

• Apenas o Caddy publica as portas 80 e 443 no host; o contêiner da aplicação não é exposto diretamente (veja expose: "5000" no Compose).
• Caddy usa resolvedores DNS públicos (1.1.1.1, 8.8.8.8) dentro do contêiner para que o Let's Encrypt funcione em hosts onde o resolvedor da VPS está inacessível a partir do Docker (uma limitação comum em alguns provedores de nuvem).

Variáveis de ambiente

Variável	Propósito	Padrão / observação
TRUST_X_FORWARDED_FOR	Usar o primeiro hop de X-Forwarded-For como src_ip	1 é recomendado com Caddy
DECEPTION_STATUS	200 retorna um corpo HTML; 302 retorna um redirecionamento	200
DECEPTION_REDIRECT_URL	Caminho de destino quando o status é 302	/
MAX_DOWNLOAD_MB	Limite do harvester por URL	16
TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID	Alertas opcionais	Vazio desativa alertas
FMC_SERVER_HEADER	Cabeçalho de resposta Server	nginx
VT_API_KEY	Reservado	Opcional

O Compose passa essas variáveis para o serviço fmc-trap; consulte docker-compose.yml para detalhes.

Campos do log JSON (referência)

Cada linha em data/logs/fmc-trap.json é um objeto JSON. Chaves comuns incluem timestamp, event_type, src_ip, headers, raw_payload_hash, extracted_commands e downloaded_file_hash quando um arquivo foi armazenado. Blobs salvos em data/downloads/ usam modo 0400 (somente leitura para o proprietário).