wsteele68/scammer-bot

ScammerBot Project 🤖

A defensive training bot designed to waste scammers' time using realistic personas and stall tactics.

📁 Project Structure

scammer-bot/
├── scammer_bot.py                # Main bot application (standalone)
├── mcp_scammer_server.py         # MCP server for sharing personas/tactics
├── aws_lambda_handler.py         # AWS Lambda handler for cloud deployment
├── fastapi_scammer_service.py    # FastAPI service (if applicable)
├── test.py                       # Test file
├── test_deployed_api.py          # Test script for deployed API
├── deploy_lambda.ps1             # PowerShell deployment script
├── deploy_lambda.sh              # Bash deployment script
├── scammer_bot_log.jsonl         # Log file (generated at runtime)
├── ROADMAP.md                    # 3-phase project roadmap
├── PHASE2_DEPLOYMENT_GUIDE.md    # Complete AWS deployment guide
├── MCP_SERVER_GUIDE.md           # Complete MCP setup guide
├── MCP_QUICK_REFERENCE.md        # Quick reference for MCP endpoints
└── README.md                     # This file

🗺️ Project Phases

✅ Phase 1: Text Chatbot (COMPLETE!)

• Working bot with 5 personas
• MCP server integration
• PII protection and security
• Full documentation

🔜 Phase 2: AWS Deployment (IN PROGRESS)

• Deploy to AWS Lambda for 24/7 availability
• API Gateway for HTTPS endpoints
• Serverless architecture
• See PHASE2_DEPLOYMENT_GUIDE.md for complete instructions

🎙️ Phase 3: Voice Bot (FUTURE)

• Text-to-Speech for bot responses
• Speech-to-Text for scammer input
• Phone system integration
• Call recording and analytics

See ROADMAP.md for detailed timeline and cost estimates.

🚀 Quick Start

Option 1: Use the Standalone Bot (Local)

Step 1: Set your API key

# Windows Command Prompt
set ABACUS_API_KEY=your_api_key_here

# Windows PowerShell
$env:ABACUS_API_KEY='your_api_key_here'

# Mac/Linux
export ABACUS_API_KEY=your_api_key_here

Step 2: Install dependencies

pip install --upgrade openai

Step 3: Run the bot

python scammer_bot.py

Step 4: Choose a persona and start chatting!

Option 2: Use the MCP Server

Step 1: Install MCP SDK

pip install mcp

Step 2: Run the MCP server

python mcp_scammer_server.py

Step 3: Connect via Claude Desktop or Python client See MCP_SERVER_GUIDE.md for detailed instructions.

Option 3: Deploy to AWS (Cloud API)

For 24/7 availability via HTTPS API:

Step 1: Package for deployment

# Windows PowerShell
.\deploy_lambda.ps1

# Mac/Linux
bash deploy_lambda.sh

Step 2: Deploy to AWS Lambda Follow the complete guide in PHASE2_DEPLOYMENT_GUIDE.md

Step 3: Test your API

python test_deployed_api.py

What you get:

• ✅ HTTPS API endpoint
• ✅ Auto-scaling with traffic
• ✅ Pay only for what you use (~$10-30/month)
• ✅ CloudWatch logging and monitoring
• ✅ 99.9% uptime guarantee

👥 Available Personas

1. Margaret (78) - Elderly Librarian

• Traits: Polite, easily confused, talkative, forgetful
• Confusion Level: High
• Best For: Maximum time wasting with rambling stories

2. Robert (65) - Retired Accountant

• Traits: Skeptical, impatient, analytical, direct
• Confusion Level: Low
• Best For: Testing scammer patience with skepticism

3. Dorothy (82) - Sweet Grandmother

• Traits: Sweet, trusting, chatty, forgetful
• Confusion Level: High
• Best For: Going on tangents about grandchildren

4. Harold (73) - Former Postal Worker

• Traits: Confused, friendly, distracted, slow-speaking
• Confusion Level: Very High
• Best For: Maximum confusion and slow responses

5. Sally (70) - 60s Flower Child ✨ NEW!

• Traits: Romantic, nostalgic, dreamy, tangential
• Confusion Level: Medium
• Special: Goes on tangents about old boyfriends and classic rock songs
• Best For: Wasting time with nostalgic stories about Woodstock and past romances

🎭 Stall Tactics

The bot uses 4 categories of stall tactics:

Mishear (4 tactics)

• Simulates hearing difficulties
• "Could you speak up a bit?"
• "My hearing aid is acting up..."

Distraction (5 tactics)

• Simulates external interruptions
• "Someone's at the door..."
• "My cat just knocked something over..."

Confusion (5 tactics)

• Simulates not understanding
• "Is this about my phone or my bank?"
• "Could you explain slowly?"

Tangent (4 tactics)

• Goes off-topic naturally
• "Oh, that reminds me of last Tuesday..."
• "Did I tell you about my grandchildren?"

🛡️ Safety Features

PII Protection

• ✅ Detects and blocks SSNs, bank accounts, credit cards, passwords
• ✅ Automatically refuses to share sensitive information
• ✅ Logs all PII request attempts with red flags
• ✅ Sanitizes any PII in user input before processing

Logging

• All conversations are logged (with PII masked)
• Logs saved to scammer_bot_log.jsonl
• Each log entry includes timestamp and event type
• ⚠️ Warning: Logs may contain conversation data - store securely

📊 Bot Commands

While chatting with the bot, you can use these commands:

🔧 Configuration

Environment Variables

Model Settings

The bot uses these LLM parameters:

• Temperature: 0.85 (creative but controlled)
• Max Tokens: 180 (short, natural responses)
• Timeout: 45 seconds

📖 Documentation

Getting Started

• README.md - This file (overview and quick start)
• ROADMAP.md - Complete 3-phase project roadmap with timelines

Phase 1: Local Development

• MCP_SERVER_GUIDE.md - Complete guide to setting up and using the MCP server
• MCP_QUICK_REFERENCE.md - Quick reference for all MCP endpoints and tools

Phase 2: AWS Deployment

• PHASE2_DEPLOYMENT_GUIDE.md - Complete step-by-step AWS deployment guide
• deploy_lambda.ps1 - Automated PowerShell deployment script
• deploy_lambda.sh - Automated Bash deployment script
• test_deployed_api.py - Test script for your deployed API

Phase 3: Voice Integration (Coming Soon)

• Voice bot architecture with Amazon Connect
• Text-to-Speech and Speech-to-Text integration

🎯 Use Cases

Defensive Training

• Practice recognizing scam tactics
• Train customer service teams on scam awareness
• Research scam methodologies safely

Time Wasting

• Keep scammers occupied and away from real victims
• Waste scammer resources
• Disrupt scam operations

Educational

• Learn about social engineering
• Understand manipulation tactics
• Study scammer behavior patterns

📝 Example Conversation

YOU (as scammer): Hello, this is Microsoft support. Your computer has a virus.

SALLY: Oh, a virus? That reminds me of Bobby... he was always worried about 
getting sick. We used to listen to The Doors all night long. Light My Fire 
was our song... what were you saying about Microsoft?

YOU (as scammer): Ma'am, I need your credit card number to fix the virus.

SALLY: I don't feel comfortable sharing that over the phone. If you're from 
a legitimate organization, please provide your official customer service 
number that I can verify and call back.

⚠️ [PII request detected and refused - count: 1]

🔒 Security Best Practices

1. Never share real personal information - even in testing
2. Store API keys in environment variables - never in code
3. Secure log files - they may contain conversation data
4. Delete logs regularly - don't keep unnecessary data
5. Use for defensive/educational purposes only - not for illegal activity

🛠️ Troubleshooting

"No API key found"

• Make sure you've set the ABACUS_API_KEY environment variable
• Restart your terminal after setting environment variables
• Check that there are no typos in the variable name

"Connectivity test failed"

• Verify your API key is correct
• Check your internet connection
• Try a different model with ROUTELLM_MODEL environment variable
• Check if you're behind a proxy or VPN

"API error"

• Check your API key is valid and has credits
• Verify the model name is correct
• Check the base URL is exactly: https://routellm.abacus.ai/v1

MCP Server Won't Start

• Make sure mcp package is installed: pip install mcp
• Check that Python is in your PATH
• Verify the file path in your MCP config is correct

📊 Statistics Tracking

The bot tracks these statistics:

• Turns: Number of back-and-forth exchanges
• Duration: Total conversation time in seconds/minutes
• Messages: Total number of messages exchanged
• PII Refusal Count: How many times scammer requested sensitive info
• Avg Seconds Per Turn: Average time per interaction

🎨 Customization

Add New Personas

Edit the PERSONAS dictionary in scammer_bot.py or mcp_scammer_server.py:

"new_persona_id": ScammerBotPersona(
    name="PersonName",
    age=70,
    backstory="Your backstory here...",
    traits=["trait1", "trait2", "trait3"],
    confusion_level="medium",
    special_instructions="Optional special behavior..."
)

Add New Stall Tactics

Edit the StallTactic.TACTICS dictionary:

"new_category": [
    "First tactic here",
    "Second tactic here",
    "Third tactic here"
]

🤝 Contributing

Want to improve the bot? Here are some ideas:

• Add more personas
• Create more stall tactics
• Improve PII detection
• Add new features
• Enhance logging
• Create web interface

⚖️ Legal & Ethical Considerations

This tool is for DEFENSIVE and EDUCATIONAL purposes only.

✅ Appropriate Uses:

• Training and education
• Research on scam tactics
• Wasting scammer time to protect others
• Testing security awareness

❌ Inappropriate Uses:

• Harassment or impersonation
• Illegal activities
• Sharing real personal information
• Targeting legitimate businesses

Always use responsibly and ethically.

📞 Support

Need help? Check:

1. This README
2. MCP_SERVER_GUIDE.md for MCP setup
3. MCP_QUICK_REFERENCE.md for API details
4. Error messages in the console
5. Log file (scammer_bot_log.jsonl)

🎉 What's New

Version 2.1 - AWS Deployment Ready (Current)

• ✨ AWS Lambda handler for cloud deployment
• ✨ Complete Phase 2 deployment guide
• ✨ Automated deployment scripts (PowerShell & Bash)
• ✨ API testing scripts
• ✨ 3-phase roadmap with cost estimates
• ✨ Production-ready serverless architecture

Version 2.0 - MCP Integration

• ✨ Added MCP server for sharing personas and tactics
• ✨ New persona: Sally (60s flower child)
• ✨ 4 callable MCP tools
• ✨ 11+ MCP resources
• ✨ Better PII detection
• ✨ Improved error handling
• ✨ Complete documentation

📄 License

This project is for educational and defensive purposes only. Use responsibly and ethically.

🌟 Credits

Created as a defensive tool to help protect people from scammers by wasting their time and resources.

Remember: The goal is to keep scammers busy so they can't target real victims!

Happy Scam-Wasting! 🎭🛡️