🛡️ ScamGuard AI

ScamGuard AI is a Flask-based scam detection web application designed to help users identify suspicious SMS messages, WhatsApp messages, links, and other text-based fraud attempts.

The application combines rule-based detection with a machine-learning text classifier and provides the results through a simple web interface.

✨ Features

• 🔍 Scam Message Detection

  • Risk score from 0–100
  • Safe / Suspicious / Likely Scam classification
  • Severity level
  • Detection reasons
  • ML confidence
  • Detected URLs and phone numbers
  • Basic language detection

• 🤖 Hybrid Detection System

  • Rule-based scam detection
  • Machine-learning text classification
  • TF-IDF character n-gram features
  • Logistic Regression model
  • Combines ML predictions with rule-based indicators

• 🌐 Multilingual Detection

  • English
  • Hindi/Marathi
  • Bengali
  • Tamil
  • Telugu
  • Gujarati

• 🚨 Scam Alerts

  • Stores suspicious scan alerts
  • Allows users to view recent alerts

• 🕘 Recent Scan History

  • Keeps track of recent scam checks
  • Displays the latest scans

• 👨‍👩‍👧 Family Management

  • Add trusted family members
  • Store family contact information

• 📚 Teach Me

  • Educational content about common scams
  • Helps users understand scam techniques

• ❤️ Health Check

  • API endpoint for checking backend status

---

🧱 Project Structure

SCAM_KTJ-main/
│
├── app.py                         # Flask application and API
├── scam_core.py                   # Scam detection logic
├── train.py                       # Machine-learning training script
├── setup.py                       # Setup helper
├── scamy_model.pkl                # Pre-trained ML model
├── requirements.txt               # Python dependencies
├── LICENSE                        # Project license
│
├── public_sms.csv                 # SMS dataset
├── public_whatsapp.csv            # WhatsApp dataset
├── public_unified_multimodal.csv  # Combined dataset
├── scam_multilingual.csv          # Multilingual dataset
│
└── static/
    ├── index.html                 # Login page
    ├── home.html                  # Main dashboard
    ├── check-link.html            # Scam checking page
    ├── recent-alerts.html         # Alert history
    ├── my-family.html             # Family management
    └── teach-me.html              # Scam awareness page

---

⚙️ How It Works

ScamGuard uses two main detection approaches.

1. Rule-Based Detection

The system checks messages for common scam indicators such as:

• OTP requests
• Banking or payment requests
• UPI-related messages
• Account suspension threats
• KYC verification requests
• Urgent or threatening language
• Suspicious links
• URL shorteners
• Lottery and prize messages
• Free offers
• Suspicious domains
• Phone number patterns
• Excessive capitalization
• Multiple exclamation marks
• Multilingual scam phrases

Each detected indicator contributes to the overall risk score.

2. Machine Learning

The project includes a pre-trained machine-learning model stored in:

scamy_model.pkl

The training pipeline uses:

• Character-level TF-IDF
• Logistic Regression
• Random Forest for larger datasets
• Train/test evaluation
• 5-fold cross-validation

The final result combines the ML prediction with the rule-based risk score.

If the ML model is unavailable, the application can fall back to rule-based detection.

---

🚀 Installation

Requirements

• Python 3.8 or higher
• pip
• Modern web browser

1. Clone the Repository

git clone <your-repository-url>
cd SCAM_KTJ-main

Or simply extract the ZIP file and open the project folder.

2. Create a Virtual Environment

Windows

python -m venv .venv
.venv\Scripts\activate

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Run the Application

python app.py

The application should start at:

http://localhost:5000

Open the URL in your browser.

---

🔐 Demo Login

The current version uses demo authentication.

Any phone number can be entered and the OTP only needs to contain 6 digits.

Example:

Phone: 9876543210
OTP: 123456

This authentication system is intended only for demonstration purposes and should not be used in production.

---

🔌 API Endpoints

Login

POST /api/login

Example request:

{
  "phone": "9876543210",
  "otp": "123456"
}

---

Scan a Message

POST /api/scan

Example request:

{
  "user_id": "demo_user",
  "text": "URGENT: Your bank account will be suspended. Verify now."
}

Example response:

{
  "label": "SUSPICIOUS ⚠️",
  "risk_score": 65,
  "severity": "medium",
  "reasons": [
    "Account threat",
    "False urgency"
  ],
  "ml_confidence": 0.82,
  "ml_prediction": "SCAM"
}

---

Recent Scans

GET /api/recent-scans?user_id=demo_user

Returns the user's recent scam scans.

---

Alerts

GET /api/alerts?user_id=demo_user

Returns recent scam alerts.

---

Clear Alerts

POST /api/alerts/clear

Example:

{
  "user_id": "demo_user"
}

---

Family Members

GET /api/family?user_id=demo_user

Returns saved family members.

Add Family Member

POST /api/family/add

Example:

{
  "user_id": "demo_user",
  "name": "Rahul",
  "phone": "+919876543210"
}

---

Health Check

GET /api/health

Example response:

{
  "status": "healthy",
  "message": "ScamGuard API is running"
}

---

🧠 Training the ML Model

The project includes a training script:

train.py

To train the model:

python train.py

The training process:

1. Loads the available datasets.
2. Detects the text and label columns.
3. Converts labels into SCAM and SAFE.
4. Splits the dataset into training and testing data.
5. Creates TF-IDF features.
6. Trains the machine-learning models.
7. Evaluates model performance.
8. Performs cross-validation.
9. Saves the trained models.

The main model is saved as:

scamy_model.pkl

---

🗃️ Data Storage

The current application uses in-memory Python data structures to store:

• Users
• Scan history
• Alerts
• Family members

Therefore, the data will be lost when the Flask server restarts.

For a production application, a persistent database such as:

• SQLite
• PostgreSQL
• MySQL
• MongoDB

should be used.

---

🔒 Security

Before deploying the application publicly, the following improvements should be made:

• Use secure environment variables for secrets.
• Replace the hard-coded Flask secret key.
• Implement real OTP authentication.
• Add proper user authentication and authorization.
• Validate API input.
• Add rate limiting.
• Configure CORS for trusted domains only.
• Disable Flask debug mode in production.
• Use a secure database.
• Avoid logging sensitive information.
• Use HTTPS.
• Use a production WSGI server such as Gunicorn.

---

🧪 Testing

The scam detection engine can be tested directly using:

python scam_core.py

The file contains example messages covering different types of scams.

You can also test the API by running the Flask server and sending requests to:

POST /api/scan

---

⚠️ Limitations

ScamGuard AI is an assistance tool and cannot guarantee that every scam will be detected.

Possible limitations include:

• False positives
• False negatives
• Outdated scam patterns
• Dependence on training-data quality
• Limited language detection
• No real-time URL reputation checking
• Demo authentication
• In-memory data storage

Users should always verify suspicious messages through official channels.

Never share:

• OTPs
• Passwords
• PINs
• Banking credentials
• UPI PINs
• Credit/debit card security information

with unknown people or suspicious websites.

---

🔮 Future Improvements

Possible future enhancements include:

• Persistent database support
• Real OTP authentication
• URL reputation checking
• Phishing website detection
• Better multilingual NLP models
• WhatsApp/SMS integration
• Real-time notifications
• Family scam alerts
• Personalized risk profiles
• Automated model retraining
• Docker support
• Automated testing
• CI/CD integration
• Production monitoring

---

📄 License

See the LICENSE file for more information.

---

👥 Project

SCAM_KTJ — ScamGuard AI

An AI-assisted scam detection and awareness platform designed to help users identify suspicious messages, links, and common digital-fraud patterns.

Disclaimer: ScamGuard AI is intended for educational and awareness purposes. It should not be considered a replacement for official banking, cybersecurity, or law-enforcement services.