HoneyPot Agent

Stateful, agentic honeypot backend for scam engagement. The service receives incoming scammer messages, detects scam intent, transitions through a deterministic agent state machine, extracts intelligence via regex, and triggers a final callback exactly once when the session exits.

Key Capabilities

• Single public API endpoint for multi-turn engagement
• Strict per-session lifecycle with terminal closure rules
• Deterministic agent behavior driven by agent state
• Regex-only intelligence extraction with deduplication
• Exactly-once final callback dispatch on EXIT
• Optional redacted intelligence snapshot export
• Pluggable session store: in-memory or Redis + Postgres

Project Structure

.
|- app/
|  |- main.py                     # FastAPI app and request orchestration
|  |- agent/
|  |  |- controller.py            # State machine and transition signals
|  |  |- reply_service.py         # Persona/state-based reply generation
|  |- core/
|  |  |- scam_detection.py        # Scam detection scoring
|  |  |- intelligence.py          # Regex intelligence extraction
|  |  |- session.py               # Session schema and lifecycle manager
|  |- infrastructure/
|     |- session_store.py         # Memory / Redis+Postgres store wiring
|     |- callbacks.py             # Final callback dispatcher
|     |- intel_exporter.py        # Redacted export writer
|- docs/                          # Authoritative architecture and contracts
|- tests/                         # Pytest suite
|- tools/streamlit_app.py         # Streamlit test harness
|- docker-compose.yml
|- Dockerfile
|- requirements.txt

API Summary

Endpoint

• Method: POST
• Path: /honeypot/message
• Auth header: x-api-key

Request (shape)

{
  "sessionId": "optional-session-id",
  "message": {
    "sender": "scammer",
    "text": "Your account is blocked. Verify now.",
    "timestamp": 1738972800000
  },
  "conversationHistory": [],
  "metadata": {
    "channel": "WhatsApp",
    "language": "English",
    "locale": "IN"
  }
}

Response (current runtime model)

{
  "status": "success",
  "reply": "I am not sure. What should I do now?"
}

When a session is closed, the endpoint returns HTTP 409 with session summary details.

Health Check

• GET /health
• POST /health
• HEAD /health

Quick Start (Local)

1. Create and activate a virtual environment.

python -m venv venv
venv\Scripts\activate

2. Install dependencies.

pip install -r requirements.txt

3. Configure environment variables.

copy .env.example .env

At minimum set:

• HONEYPOT_API_KEY
• FINAL_CALLBACK_URL
• CALLBACK_API_KEY (if your callback endpoint requires it)

4. Start the API.

python -m app.main

5. Send a test request.

curl -X POST http://127.0.0.1:8000/honeypot/message \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d "{\"sessionId\":\"demo-1\",\"message\":{\"sender\":\"scammer\",\"text\":\"Your KYC is blocked. Share UPI now\",\"timestamp\":1738972800000}}"

Run with Docker Compose

docker compose up --build

Compose provisions:

• App on port 8000
• Redis session layer
• Postgres persistence

Intelligence exports are written to exports/intel_snapshots.jsonl when enabled.

Environment Variables

Use .env.example as the source of truth. Important variables include:

• ENVIRONMENT
• HONEYPOT_API_KEY
• SESSION_STORE (memory or redis_postgres)
• REDIS_URL
• POSTGRES_DSN
• FINAL_CALLBACK_URL
• CALLBACK_API_KEY
• USE_LLM, LLM_BACKEND, STRICT_LLM_MODE
• OPENAI_API_KEY / GEMINI_API_KEY (when using cloud LLM backends)
• INTEL_EXPORT_ENABLED, INTEL_EXPORT_PATH, INTEL_EXPORT_MAX_SAMPLES

Testing

pytest -v

Streamlit Tester

streamlit run tools/streamlit_app.py

Reference Docs

• docs/PLAN.md
• docs/SESSION_SCHEMA.md
• docs/AGENT_STATE_MACHINE.md
• docs/INTELLIGENCE_EXTRACTION_RULES.md
• docs/API_CONTRACT.md
• docs/IMPLEMENTATION_FLOW.md

Security and Operational Notes

• Keep sessions append-only and respect terminal flags
• Do not expose callback endpoints publicly without authentication
• Avoid logging raw sensitive intelligence values
• Prefer Redis + Postgres for durable deployments

License

No explicit license file is currently present in this repository.