FMC-Trap

A low-interaction honeypot that mimics a Cisco Secure Firewall Management Center (FMC) web surface and captures unauthenticated Java serialization-style attack traffic (CVE-style insecure deserialization probes).

• Safe by design: the application does not deserialize Java objects; it detects \xac\xed\x00\x05 (and Base64 rO0AB…) and extracts shell or URL strings using regular expressions and heuristics.
• No command execution: second-stage URLs are retrieved only with Python requests into a non-executable downloads volume.
• Production-oriented stack: Docker Compose with Gunicorn and optional Caddy (HTTPS, Let’s Encrypt).

Why run it?

Single-line JSON logs (compatible with Splunk and ELK), optional Telegram alerts, hashed second-stage artifacts, and a non-root container user. The project is intended for researchers who require a focused FMC-style trap without additional integration code.

Requirements

Quick start (approximately five minutes)

1. Clone

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

2. Configure environment

cp .env.example .env

Edit .env as required (see Environment variables). For deployments behind the bundled Caddy, set TRUST_X_FORWARDED_FOR=1 so that client IP addresses in logs reflect the original client.

3. Point Caddy at your domain

Edit Caddyfile: replace the placeholder hostnames with your domain (and www if applicable):

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

Optionally, uncomment the global email [email protected] block in Caddyfile for Let’s Encrypt expiry notices.

4. DNS and firewall (HTTPS)

• Create A (and AAAA if applicable) records: yourdomain.com to your server’s public IP, and www if used.
• Allow inbound TCP 80 and TCP 443 on the host (cloud security group and host firewall, for example ufw allow 80,443/tcp).

5. Data directories (required)

The application runs as UID 10001 inside the container. The bind-mounted ./data directory must be writable:

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

Without correct ownership, exploit POST requests may return 500 (Permission denied when writing logs or raw blobs).

6. Start

docker compose up -d --build

7. Verify

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

Expect HTTP/2 200 (or 301 or 302) and Via: Caddy. In a browser, https://yourdomain.com/ should display the simulated FMC login page.

For where to read events, payloads, and Docker output, see Finding logs, downloads, and service output and Common operations.

Finding logs, downloads, and service output

Everything below is relative to your project directory (the folder that contains docker-compose.yml, usually FMC-Trap after you clone). Paths are on the host; Docker bind-mounts them into the container.

When something appears in the log file: fmc-trap.json receives one JSON object per line when a request matches deserialization probe behavior (magic bytes in a POST). Ordinary GET requests to the fake login page are not written to this file by default.

When the downloads folder has files: entries appear only if the pipeline extracts a URL from a probe and the harvester successfully fetches allowed remote content within MAX_DOWNLOAD_MB. If the directory stays empty, there may be no qualifying URLs yet, or fetches may be blocked by policy in the application.

Pretty-printing JSON (optional): for a single line, pipe through python -m json.tool or use jq if installed.

Common operations

Architecture

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

• Only Caddy publishes 80 and 443 to the host; the application container is not exposed directly (see expose: "5000" in Compose).
• Caddy uses public DNS resolvers (1.1.1.1, 8.8.8.8) inside the container so that Let’s Encrypt succeeds on hosts where the VPS resolver is unreachable from Docker (a common limitation on some cloud providers).

Environment variables

Compose passes these variables into the fmc-trap service; refer to docker-compose.yml for details.

JSON log fields (reference)

Each line in data/logs/fmc-trap.json is one JSON object. Common keys include timestamp, event_type, src_ip, headers, raw_payload_hash, extracted_commands, and downloaded_file_hash when a file was stored. Saved blobs under data/downloads/ use mode 0400 (read-only for the owner).

Troubleshooting

Optional: expose the application on localhost (debugging)

To reach Gunicorn directly without Caddy, add the following under fmc-trap in docker-compose.yml:

ports:
  - "127.0.0.1:5000:5000"

Do not bind the application to 0.0.0.0 in production when Caddy terminates TLS.

Security

• Deploy on a dedicated VPS or isolated network. The service handles malicious traffic and may download malware for analysis.
• Store Telegram tokens and other secrets only in .env on the host (never commit .env).
• Restrict the firewall to the minimum required ports (80 and 443 for HTTPS).

Legal and ethical use

Deploy only on systems you own or on which you are explicitly authorized to deploy instrumentation. Honeypots may collect attack traffic and malware; comply with applicable law and organizational policy. This software is intended for security research.