Apppublic

Anand815353/honeypotApi

sourceHugging Faceupdated 8mo agoView on Hugging Face

0likes

App README

Agentic Honey-Pot for Scam Detection & Intelligence Extraction

AI-powered honeypot system that detects scam messages, handles multi-turn conversations, and extracts actionable intelligence without revealing detection.

Features

—Scam Detection: Detects scam intent from incoming messages using keyword matching and pattern detection
—Session Management: Tracks multi-turn conversations using in-memory session storage
—Intelligence Extraction: Extracts bank accounts, UPI IDs, phishing links, phone numbers, and suspicious keywords
—GUVI Callback Integration: Automatically sends extracted intelligence to GUVI evaluation endpoint
—API Key Authentication: Secured endpoints using x-api-key header

Project Structure

Agentic honeypot/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI app entry point
│   ├── models.py               # Pydantic request/response models
│   ├── auth.py                 # API key authentication middleware
│   ├── services/
│   │   ├── __init__.py
│   │   ├── scam_detector.py   # Scam detection logic
│   │   ├── intelligence_extractor.py  # Intelligence extraction
│   │   ├── session_manager.py # In-memory session management
│   │   └── callback_client.py  # HTTP client for GUVI callback
│   └── routers/
│       ├── __init__.py
│       └── message.py          # Main message endpoint router
├── .env.example                # Environment variables template
├── requirements.txt            # Python dependencies
└── README.md                   # This file

Setup Instructions

Option 1: Docker (Recommended)

Using Docker Compose (Local Testing)

1.Configure Environment Variables

Copy .env.example to .env and update with your values:

bash

   cp .env.example .env

Edit .env:

   API_KEY=your_secret_api_key_here
   GUVI_CALLBACK_URL=https://hackathon.guvi.in/api/updateHoneyPotFinalResult

1.Build and Run with Docker Compose

bash

   docker-compose up --build

The API will be available at http://localhost:8000

1.Stop the Container

bash

   docker-compose down

Using Docker Directly

1.Build the Docker Image

bash

   docker build -t agentic-honeypot .

1.Run the Container

bash

   docker run -d \
     --name agentic-honeypot-api \
     -p 8000:8000 \
     --env-file .env \
     -e PORT=8000 \
     agentic-honeypot

The API will be available at http://localhost:8000

1.Stop and Remove Container

bash

   docker stop agentic-honeypot-api
   docker rm agentic-honeypot-api

Option 2: Local Python Development

1.Install Dependencies

bash

   pip install -r requirements.txt

1.Configure Environment Variables

Copy .env.example to .env and update with your values:

bash

   cp .env.example .env

Edit .env:

   API_KEY=your_secret_api_key_here
   GUVI_CALLBACK_URL=https://hackathon.guvi.in/api/updateHoneyPotFinalResult

1.Run the Application

bash

   # Using uvicorn directly
   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

   # Or using Python
   python -m app.main

The API will be available at http://localhost:8000

Docker Deployment

Hugging Face Spaces

This application is configured for deployment on Hugging Face Spaces using Docker:

1.Create a new Space on Hugging Face Hub
2.Select Docker SDK as the SDK type
3.Push your code to the Space repository
4.Set Environment Variables in the Space settings:
5.API_KEY: Your secret API key
6.GUVI_CALLBACK_URL: The callback endpoint URL
7.PORT: Will be automatically set to 7860 by HF Spaces

The application will automatically use port 7860 (configured in README.md frontmatter) when deployed on Hugging Face Spaces.

Port Configuration

—Local Development: Port 8000 (default)
—Docker Local: Port 8000 (configurable via PORT env var)
—Hugging Face Spaces: Port 7860 (automatically set by HF Spaces)

The application reads the PORT environment variable and defaults to 8000 if not set.

API Endpoints

Health Check

—GET / or /health
—Returns: {"status": "healthy"}

Process Message

—POST /api/message
—Headers:
—x-api-key: YOUR_SECRET_API_KEY
—Content-Type: application/json
—Request Body: See Request Format below
—Response: See Response Format below

Request Format

First Message (Start of Conversation)

json

{
  "sessionId": "wertyu-dfghj-ertyui",
  "message": {
    "sender": "scammer",
    "text": "Your bank account will be blocked today. Verify immediately.",
    "timestamp": "2026-01-21T10:15:30Z"
  },
  "conversationHistory": [],
  "metadata": {
    "channel": "SMS",
    "language": "English",
    "locale": "IN"
  }
}

Follow-Up Message

json

{
  "sessionId": "wertyu-dfghj-ertyui",
  "message": {
    "sender": "scammer",
    "text": "Share your UPI ID to avoid account suspension.",
    "timestamp": "2026-01-21T10:17:10Z"
  },
  "conversationHistory": [
    {
      "sender": "scammer",
      "text": "Your bank account will be blocked today. Verify immediately.",
      "timestamp": "2026-01-21T10:15:30Z"
    },
    {
      "sender": "user",
      "text": "Why will my account be blocked?",
      "timestamp": "2026-01-21T10:16:10Z"
    }
  ],
  "metadata": {
    "channel": "SMS",
    "language": "English",
    "locale": "IN"
  }
}

Response Format

json

{
  "status": "success",
  "scamDetected": true,
  "engagementMetrics": {
    "engagementDurationSeconds": 420,
    "totalMessagesExchanged": 18
  },
  "extractedIntelligence": {
    "bankAccounts": ["XXXX-XXXX-XXXX"],
    "upiIds": ["scammer@upi"],
    "phishingLinks": ["http://malicious-link.example"],
    "phoneNumbers": ["+91XXXXXXXXXX"],
    "suspiciousKeywords": ["urgent", "verify now", "account blocked"]
  },
  "agentNotes": "Scammer used urgency tactics and payment redirection"
}

Testing the API

Using curl

bash

curl -X POST "http://localhost:8000/api/message" \
  -H "x-api-key: your_secret_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "test-session-123",
    "message": {
      "sender": "scammer",
      "text": "Your bank account will be blocked today. Verify immediately.",
      "timestamp": "2026-01-21T10:15:30Z"
    },
    "conversationHistory": [],
    "metadata": {
      "channel": "SMS",
      "language": "English",
      "locale": "IN"
    }
  }'

Using Python requests

python

import requests

url = "http://localhost:8000/api/message"
headers = {
    "x-api-key": "your_secret_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "sessionId": "test-session-123",
    "message": {
        "sender": "scammer",
        "text": "Your bank account will be blocked today. Verify immediately.",
        "timestamp": "2026-01-21T10:15:30Z"
    },
    "conversationHistory": [],
    "metadata": {
        "channel": "SMS",
        "language": "English",
        "locale": "IN"
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

API Documentation

Once the server is running, visit:

—Swagger UI: http://localhost:8000/docs
—ReDoc: http://localhost:8000/redoc

How It Works

1.Request Received: API receives incoming message with sessionId
2.Session Management: Gets or creates session for the conversation
3.Scam Detection: Analyzes message and history for scam indicators
4.Intelligence Extraction: Extracts bank accounts, UPI IDs, links, phone numbers, keywords
5.Session Update: Updates session with new message and intelligence
6.Metrics Calculation: Calculates engagement duration and message count
7.Callback: If scam detected and sufficient engagement, sends callback to GUVI endpoint (async)
8.Response: Returns structured JSON with all extracted data

Notes

—Session data is stored in-memory (will be lost on server restart)
—Callback to GUVI endpoint is sent asynchronously to avoid blocking responses
—Scam detection uses keyword matching (can be enhanced with ML models)
—Intelligence extraction uses regex patterns (can be improved)
—Agent logic for conversation handling will be added later

Next Steps

—[ ] Integrate AI agent for conversation handling
—[ ] Enhance scam detection with ML models
—[ ] Improve intelligence extraction patterns
—[ ] Add persistent session storage (database)
—[ ] Add logging and monitoring
—[ ] Add unit tests

License

This project is developed for the hackathon.