tamamo

tamamo

tamamo is an LLM-driven web honeypot that mimics the behavior of real internal admin pages to lure and observe attackers. It generates realistic login screens, dashboards, API endpoints, and server signatures using LLM, then serves them as fully functional decoy sites — capturing every interaction for analysis.

The name "tamamo" comes from Tamamo-no-Mae (玉藻の前), a legendary fox spirit in Japanese mythology known for its shape-shifting abilities. Just as Tamamo-no-Mae disguised itself to deceive, this tool disguises honeypots as legitimate services to deceive attackers.

Getting Started

The fastest way to try tamamo — generate a scenario and start serving it in one command:

go run github.com/secmon-lab/tamamo@latest serve \
  --llm-provider openai \
  --llm-api-key $OPENAI_API_KEY

Then open http://localhost:8080 in your browser. You'll see a realistic-looking admin login page generated by LLM, ready to capture any interaction.

Features

• LLM-powered scenario generation — Generates complete honeypot scenarios including login pages, dashboard pages, API routes, and server signatures using LLM agents
• Multi-provider LLM support — OpenAI, Claude (Anthropic), and Gemini (Google Cloud)
• Realistic authentication simulation — Configurable auth strategy that rejects initial login attempts before succeeding, mimicking real systems
• Event emission — Captures all attacker interactions and reports via structured logging, webhook (with HMAC-SHA256 signature), and/or Google Cloud Pub/Sub
• Scenario portability — Scenarios are exported as ZIP files and can be shared, versioned, and deployed independently

Install

go install github.com/secmon-lab/tamamo@latest

Quick Start

Generate a scenario

# Generate with default settings (random site type, style, taste)
tamamo generate --llm-provider openai --llm-api-key $OPENAI_API_KEY

# Customize the scenario
tamamo generate \
  --llm-provider claude \
  --llm-api-key $ANTHROPIC_API_KEY \
  --site-type "Employee directory & HR portal" \
  --site-style "corporate-minimal" \
  --site-taste "Looks like it was built 10 years ago and never updated" \
  --site-lang "Japanese" \
  --output my-scenario.zip

Serve a scenario

# Serve a pre-generated scenario
tamamo serve --scenario my-scenario.zip --addr 0.0.0.0:8080

# Auto-generate and serve in one step
tamamo serve \
  --llm-provider openai \
  --llm-api-key $OPENAI_API_KEY \
  --addr 0.0.0.0:8080

Validate a scenario

tamamo validate --scenario my-scenario.zip

Commands

tamamo generate

Generate a honeypot scenario using LLM.

For Gemini provider:

tamamo serve

Start the honeypot HTTP server.

All generate flags are also available when --scenario is omitted.

tamamo validate

Validate a scenario for correctness. Reports all errors at once.

Scenario Structure

A scenario is a ZIP file (or directory) containing:

scenario.json       # Metadata (name, server signature, headers)
routes.json         # Route definitions (paths, methods, responses)
pages/
  login.html        # Login page
  dashboard.html    # Perpetual loading dashboard
  logo.svg          # (optional) Generated images/assets

Authentication Strategy

Login endpoints support an auth field in routes.json that simulates realistic authentication behavior:

{
  "path": "/api/auth/login",
  "method": "POST",
  "status_code": 200,
  "headers": {"Content-Type": "application/json"},
  "body": "{\"success\": true, \"redirect\": \"/dashboard\"}",
  "auth": {
    "min_failures": 3,
    "success_probability": 0.2,
    "failure_status_code": 401,
    "failure_body": "{\"success\": false, \"error\": \"Invalid credentials\"}",
    "failure_headers": {"Content-Type": "application/json"},
    "credential_fields": ["username", "password"]
  }
}

The server tracks unique credential submissions per source IP. The first min_failures unique credentials always fail. After that, each new unique credential has a success_probability chance of succeeding — making the timing unpredictable and realistic. The same credential always returns the same result. Only fields listed in credential_fields are used to determine uniqueness (other fields like CSRF tokens are ignored). Both JSON and form-urlencoded submissions are supported.

Event Notification

All attacker interactions are captured and emitted as structured events:

{
  "timestamp": "2026-03-20T12:34:56Z",
  "node_id": "honeypot-01",
  "event_type": "http_request",
  "source_ip": "203.0.113.1",
  "method": "POST",
  "path": "/api/auth/login",
  "headers": {"User-Agent": "..."},
  "body": {"username": "admin", "password": "P@ssw0rd"},
  "scenario": "acme-corp-admin"
}

• Log (always active): Structured log output via slog
• Webhook: HTTP POST with X-Tamamo-Signature: sha256=<hex> header (HMAC-SHA256)

License

Apache License 2.0