Skip to content

BACKEND_GUIDE.md

Latest commit

 

History

History
352 lines (284 loc) · 7.66 KB

BACKEND_GUIDE.md

File metadata and controls

352 lines (284 loc) · 7.66 KB
Raw

AegisAI Backend Integration Guide

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Install Tesseract OCR (for image analysis)

Windows:

# Download and install from: https://github.com/UB-Mannheim/tesseract/wiki
# Add to PATH: C:\Program Files\Tesseract-OCR

macOS:

brew install tesseract

Linux:

sudo apt-get install tesseract-ocr

3. Train ML Model

python train_model.py

4. Start Backend Server

python backend_complete.py

5. Test Backend

python test_backend.py

📊 Database Schema

Users Table

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    password_hash VARCHAR(128) NOT NULL,
    profile_image VARCHAR(100) DEFAULT 'default_profile.jpg',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

ScanHistory Table

CREATE TABLE scan_history (
    id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL,
    input_type VARCHAR(10),  -- 'URL' or 'Image'
    input_value TEXT,
    prediction VARCHAR(20),  -- 'Legitimate' or 'Phishing'
    confidence_score FLOAT,
    risk_score INTEGER,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users (id)
);

🔗 API Endpoints

Authentication

  • POST /api/register - User registration
  • POST /api/login - User login
  • POST /api/logout - User logout

Analysis

  • POST /api/analyze-url - URL phishing detection
  • POST /api/analyze-image - Image OCR analysis

Data

  • GET /api/history - User scan history
  • GET /api/dashboard-stats - Dashboard statistics
  • PUT /api/update-profile - Profile management

System

  • GET /api/health - Health check

🔄 Backend Workflow

1. User Registration
   ├── Validate input data
   ├── Hash password with bcrypt
   ├── Save to database
   └── Return user data

2. User Login
   ├── Find user by username/email
   ├── Verify password hash
   ├── Create session
   └── Return user data

3. URL Analysis
   ├── Validate URL format
   ├── Extract 7 features
   ├── Scale features
   ├── Predict with Random Forest
   ├── Calculate risk score
   ├── Save to database
   └── Return results

4. Image Analysis
   ├── Upload and save file
   ├── Extract text with OCR
   ├── Analyze text for keywords
   ├── Calculate risk score
   ├── Save to database
   └── Return results

5. History Tracking
   ├── Query user scans
   ├── Apply filters
   ├── Paginate results
   └── Return statistics

🧠 Feature Extraction (7 Features)

features = [
    url_length,           # Total URL length
    num_dots,            # Number of '.' characters
    has_at_symbol,       # Binary: @ present (1/0)
    has_https,           # Binary: HTTPS (1/0)
    num_subdomains,      # Number of subdomains
    count_special_chars, # Special characters count
    suspicious_count     # Phishing keywords count
]

🖼️ Image OCR Analysis

Process

  1. Text Extraction: Use pytesseract to extract text
  2. Keyword Analysis: Scan for 40+ phishing keywords
  3. Risk Calculation: Score based on keyword density
  4. Classification: High Risk/Suspicious/Low Risk

Keywords Detected

phishing_keywords = [
    'login', 'verify', 'update', 'secure', 'bank',
    'account', 'password', 'payment', 'transaction',
    'urgent', 'immediate', 'suspended', 'blocked'
]

🔒 Security Features

Password Security

from werkzeug.security import generate_password_hash, check_password_hash

# Hash password
password_hash = generate_password_hash(password)

# Verify password
is_valid = check_password_hash(password_hash, provided_password)

Session Management

from flask_login import LoginManager, login_user, logout_user

# Login user
login_user(user)

# Logout user
logout_user()

Input Validation

# URL validation
def validate_url(url):
    if not url:
        return False
    if not url.startswith(('http://', 'https://')):
        url = 'https://' + url
    return url

# File validation
allowed_extensions = {'png', 'jpg', 'jpeg', 'gif', 'bmp'}

📈 ML Model Integration

Model Loading

with open('aegis_model.pkl', 'rb') as f:
    model_data = pickle.load(f)

rf_model = model_data['model']
scaler = model_data['scaler']
feature_names = model_data['feature_names']

Prediction Process

# Extract features
features = extractor.extract_features(url)

# Scale features
features_scaled = scaler.transform(features.reshape(1, -1))

# Make prediction
prediction_proba = rf_model.predict_proba(features_scaled)[0]
prediction = 'Phishing' if prediction_proba[1] > 0.5 else 'Legitimate'
confidence = max(prediction_proba)

# Calculate risk score
risk_score = int(min(confidence * 100, 100)) if prediction == 'Phishing' else int((1 - confidence) * 50)

🧪 Testing

Run Tests

python test_backend.py

Test Coverage

  • ✅ User registration and login
  • ✅ URL analysis (legitimate and phishing)
  • ✅ Image analysis (OCR)
  • ✅ History tracking
  • ✅ Dashboard statistics
  • ✅ Profile management
  • ✅ Error handling

Manual Testing with curl

# Register user
curl -X POST http://localhost:5000/api/register \
  -H "Content-Type: application/json" \
  -d '{"username":"test","email":"test@example.com","password":"testpass123"}'

# Login
curl -X POST http://localhost:5000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"testpass123"}'

# Analyze URL
curl -X POST http://localhost:5000/api/analyze-url \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.google.com"}'

🚀 Deployment

Production Setup

# config.py
class ProductionConfig:
    SECRET_KEY = 'your-production-secret-key'
    SQLALCHEMY_DATABASE_URI = 'postgresql://user:pass@localhost/aegisai'
    SESSION_COOKIE_SECURE = True
    WTF_CSRF_ENABLED = True

Environment Variables

export SECRET_KEY='your-secret-key'
export DATABASE_URL='sqlite:///aegisai.db'
export FLASK_ENV='production'

Docker Deployment

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["python", "backend_complete.py"]

🔧 Troubleshooting

Common Issues

  1. Model not found

    python train_model.py

  2. OCR dependencies missing

    pip install pytesseract pillow
# Install Tesseract OCR system package

  3. Database connection error

    # Delete database and restart
rm aegisai.db
python backend_complete.py

  4. Port already in use

    # Kill process on port 5000
lsof -ti:5000 | xargs kill

Debug Mode

# Enable debug mode
app.run(debug=True, host='0.0.0.0', port=5000)

📊 Performance Optimization

Model Loading

  • Load model once at startup (not in each request)
  • Use pickle for fast serialization

Database Optimization

  • Add indexes on frequently queried columns
  • Use connection pooling for production

Caching

  • Cache model predictions
  • Cache user sessions
  • Use Redis for distributed caching

🔮 Future Enhancements

  • Rate limiting on API endpoints
  • Email notifications for high-risk detections
  • Advanced image analysis with CNN
  • Real-time URL scanning
  • API key authentication
  • Multi-language support
  • Advanced threat intelligence

AegisAI Backend - Complete, production-ready phishing detection system! 🛡️