A phased honeypot system that captures scam emails, engages scammers with AI-generated replies, fingerprints their clients, and produces threat intelligence reports.
# 1. Copy environment config
cp .env.example .env
# Edit .env with your OPENROUTER_API_KEY and a strong POSTGRES_PASSWORD
# 2. Start services
docker compose up -d
# 3. Test with swaks
swaks --to test@honepy.local --from scammer@test.com \
--server localhost:25 --body "Dear friend, I have a business proposal..."| Component | Tech | Port | Purpose |
|---|---|---|---|
| Honeypot | Python/Twisted | 25 (host) -> 2525 (container) | SMTP capture + AI replies |
| Backend | Node.js/Express | 3000 | REST API + analysis |
| PostgreSQL | postgres:16-alpine | 5432 | Single source of truth |
Scammer -> Port 25 -> Twisted ESMTP -> Parse Email -> Match/Create Session
-> Store in DB -> Generate AI Reply (OpenRouter) -> Send via Scammer's MX
- Phase 1: Core honeypot - SMTP capture, AI responses, session tracking
- Phase 2: Intelligence - metadata extraction, TTP analysis, threat enrichment
- Phase 3: Deception - CanaryTokens, browser fingerprinting, behavioral tracking
- Phase 4: Advanced - credential honeytraps, anomaly detection, context persistence
All configuration is via environment variables. See .env.example for the full list.
| Variable | Description |
|---|---|
POSTGRES_PASSWORD |
Database password |
OPENROUTER_API_KEY |
OpenRouter API key for AI responses |
HONEYPOT_DOMAIN |
Domain the honeypot listens on |
GET /api/sessions - List all captured sessions
GET /api/sessions/:id - Get session details with messages
POST /api/analysis/ttp/:id - Trigger TTP analysis for a session
GET /api/analysis/ttp/:id - Get TTP analysis results
GET /api/enrichment/ip/:ip - IP threat enrichment
GET /api/enrichment/domain/:d - Domain threat enrichment
GET /api/fingerprints/:id - Fingerprint data
# Logs
docker compose logs -f honeypot
docker compose logs -f backend
# Database shell
docker compose exec postgres psql -U honepy
# Run with CanaryTokens (Phase 3)
docker compose --profile canary up -d
# Run with dev tools (mailhog for testing outbound)
docker compose --profile dev up -dMIT