README.md

---
title: Honeypot API
emoji: 🛡️
colorFrom: blue
colorTo: red
sdk: docker
app_port: 7860
pinned: false
---

# Honeypot API

## Description

Honeypot API is a Flask-based conversational honeypot that talks to scammers for several turns, extracts all sensitive intelligence they reveal (phone numbers, bank accounts, UPI IDs, links, emails, case IDs, policy and order numbers), and then submits a final JSON summary for scoring.  
The focus is on:
- Reliable scam detection using a fine-tuned BERT phishing model
- Robust regex/NLP-based intelligence extraction
- High-quality engagement so the scammer keeps replying

## Tech Stack

- Language/Framework: Python, Flask
- Key Libraries: `torch`, `transformers`, `requests`, `re`, `logging`
- Models Used:
  - BERT sequence classification model (local: `model/phising_model`) for scam detection

## Setup Instructions

1. Clone the repository  
2. Create and activate a virtual environment (optional but recommended)

   ```bash
   python -m venv venv
   venv\Scripts\activate  # Windows
   # or
   source venv/bin/activate  # Linux/macOS
   ```

3. Install dependencies

   ```bash
   pip install -r requirements.txt
   ```

4. Set environment variables (or edit `.env`)

   ```env
   HONEYPOT_API_KEY=your-api-key-here
   PORT=8000
   ```

5. Run the application (local)

   ```bash
   python -m src.main
   ```

   Or with Gunicorn (as used in Docker):

   ```bash
   gunicorn -b 0.0.0.0:7860 honeypot_api:app --timeout 120
   ```

## API Endpoint

- URL: `https://your-deployed-url.com/honeypot`
- Method: `POST`
- Authentication: `x-api-key` header (must match `HONEYPOT_API_KEY`)

### Request Body

```json
{
  "sessionId": "uuid-v4-string",
  "message": {
    "sender": "scammer",
    "text": "URGENT: Your account has been compromised...",
    "timestamp": "2025-02-11T10:30:00Z"
  },
  "conversationHistory": [
    {
      "sender": "scammer",
      "text": "Previous message...",
      "timestamp": 1739270400000
    },
    {
      "sender": "user",
      "text": "Your previous response...",
      "timestamp": 1739270460000
    }
  ],
  "metadata": {
    "channel": "SMS",
    "language": "English",
    "locale": "IN"
  }
}
```

### Response Body (per turn)

```json
{
  "status": "success",
  "scamDetected": true,
  "confidence": 0.97,
  "reply": "I'm a bit confused about this. Can you explain this clearly?",
  "engagementScore": 96
}
```

## Approach

- **Scam Detection**
  - Uses a fine-tuned BERT model on each incoming message to classify phishing/scam content.
  - The model output drives internal scoring, while final `scamDetected` in the callback is always `true` (all evaluation scenarios are scams).

- **Intelligence Extraction**
  - A single regex-based extractor runs on every scammer message.
  - It extracts:
    - `phoneNumbers`, `bankAccounts`, `upiIds`, `phishingLinks`, `emailAddresses`
    - Additional IDs such as `caseIds`, `policyNumbers`, `orderNumbers`
  - Results are accumulated over the session and returned in `extractedIntelligence` in the final callback JSON.

- **Engagement Strategy**
  - The honeypot acts as a confused but cooperative victim.
  - It uses progressive, generic questions (e.g. “Can you explain this clearly?”, “Is this really urgent?”, “Can you confirm your official ID?”) to keep scammers talking.
  - An engagement scoring function rewards:
    - Depth of conversation (number of turns)
    - Balanced back-and-forth between scammer and honeypot
    - Frequent question marks in agent messages
    - Scammer persistence
  - Final engagement metrics are included in the callback as `engagementMetrics` and `engagementDurationSeconds`.