ThreatLens 🛡️

AI-Powered Web Attack Detection & Monitoring Dashboard

---

ThreatLens is a machine learning-based security monitoring system that detects and classifies web attacks in real-time. It uses a trained ML model to identify SQL Injection, XSS, Command Injection, and File Inclusion attacks with high accuracy.

✨ Features

• 🤖 ML-Powered Detection - Trained classifier using TF-IDF + LinearSVC
• 🎯 Multi-Attack Classification - Detects SQLi, XSS, Command Injection, File Inclusion
• 📊 Real-time Dashboard - Modern dark-themed UI with live monitoring
• 📈 Analytics & Insights - Attack trends, patterns, and statistics
• 🔔 Sound Alerts - Audio notifications for detected attacks
• 📥 Export Logs - Download attack logs as CSV
• 🐳 Docker Ready - One-command deployment with Docker Compose
• 🔌 Easy Integration - Simple REST API for any web application

---

📸 Screenshots

Dashboard Overview

Main dashboard with attack statistics, recent activity, and threat distribution

Attack Logs

Detailed attack logs with filtering, search, and export functionality

Analytics

Visual analytics with charts showing attack patterns and trends

Live Monitor

Real-time request monitoring with live updates and sound alerts

---

🚀 Setup

Prerequisites

• Docker & Docker Compose
• Git

Quick Start

1. Clone the repository

   git clone https://github.com/yassertioursi/ml-attack-detector.git
   cd threat-lens

2. Start the containers

   docker-compose up -d --build

3. Run database migrations

   docker exec ml_laravel php artisan migrate

4. Generate application key (first time only)

   docker exec ml_laravel php artisan key:generate

5. Access the dashboard

   • Dashboard: http://localhost:8000/dashboard
   • ML API: http://localhost:5000

Services

Service	Port	Description
Dashboard	8000	Laravel + React web interface
ML API	5000	FastAPI prediction endpoint
PostgreSQL	5432	Database for attack logs

Stopping the Application

docker-compose down

To remove all data (including database):

docker-compose down -v

---

📖 Usage

Dashboard Navigation

1. Dashboard - Overview of attack statistics and recent activity
2. Attack Logs - Browse, filter, and export all logged requests
3. Analytics - Visual charts and attack pattern analysis
4. Live Monitor - Real-time request feed with sound alerts

Testing Attack Detection

Send test payloads to see the detection in action:

# SQL Injection
curl -X POST http://localhost:8000/api/logs \
  -H "Content-Type: application/json" \
  -d '{"payload": "SELECT * FROM users WHERE id=1 OR 1=1--"}'

# XSS Attack
curl -X POST http://localhost:8000/api/logs \
  -H "Content-Type: application/json" \
  -d '{"payload": "<script>alert(document.cookie)</script>"}'

# Command Injection
curl -X POST http://localhost:8000/api/logs \
  -H "Content-Type: application/json" \
  -d '{"payload": "; cat /etc/passwd"}'

# File Inclusion
curl -X POST http://localhost:8000/api/logs \
  -H "Content-Type: application/json" \
  -d '{"payload": "../../etc/passwd"}'

# Benign Request
curl -X POST http://localhost:8000/api/logs \
  -H "Content-Type: application/json" \
  -d '{"payload": "user@example.com"}'

API Response Format

{
  "id": 1,
  "type": "sqli",
  "confidence": 0.95,
  "is_attack": true
}

Attack Types

Type	Description
benign	Safe, non-malicious request
sqli	SQL Injection attempt
xss	Cross-Site Scripting
cmdi	Command Injection
file_inclusion	Local/Remote File Inclusion

---

🔌 Integration Guide

Integrate ThreatLens with any web application to monitor and detect attacks in real-time.

API Endpoints

Log & Analyze Request (Recommended)

POST http://localhost:8000/api/logs
Content-Type: application/json

{
  "payload": "user input to analyze",
  "source_ip": "192.168.1.1"  // optional
}

Direct ML Prediction

POST http://localhost:5000/predict
Content-Type: application/json

{
  "payload": "user input to analyze"
}

---

Java Spring Boot Integration

@Service
public class ThreatLensService {
    
    private final RestTemplate restTemplate;
    private final String threatLensUrl = "http://localhost:8000/api/logs";
    
    public ThreatLensService(RestTemplateBuilder builder) {
        this.restTemplate = builder
            .setConnectTimeout(Duration.ofSeconds(2))
            .setReadTimeout(Duration.ofSeconds(2))
            .build();
    }
    
    @Async
    public CompletableFuture<Void> analyzeRequest(String payload, String sourceIp) {
        try {
            HttpHeaders headers = new HttpHeaders();
            headers.setContentType(MediaType.APPLICATION_JSON);
            
            Map<String, String> body = new HashMap<>();
            body.put("payload", payload);
            body.put("source_ip", sourceIp);
            
            HttpEntity<Map<String, String>> request = new HttpEntity<>(body, headers);
            restTemplate.postForObject(threatLensUrl, request, String.class);
        } catch (Exception e) {
            log.warn("ThreatLens analysis failed: {}", e.getMessage());
        }
        return CompletableFuture.completedFuture(null);
    }
}

// Filter to intercept requests
@Component
public class ThreatLensFilter implements Filter {
    
    @Autowired
    private ThreatLensService threatLensService;
    
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        
        // Collect data to analyze
        String queryString = httpRequest.getQueryString();
        String sourceIp = httpRequest.getRemoteAddr();
        
        // Send async (non-blocking)
        if (queryString != null) {
            threatLensService.analyzeRequest(queryString, sourceIp);
        }
        
        chain.doFilter(request, response);
    }
}

---

Node.js / Express Integration

const axios = require('axios');

const THREAT_LENS_URL = 'http://localhost:8000/api/logs';

// Middleware for Express
const threatLensMiddleware = (req, res, next) => {
    const payload = req.originalUrl + JSON.stringify(req.body || {});
    const sourceIp = req.ip || req.connection.remoteAddress;
    
    // Non-blocking async call
    axios.post(THREAT_LENS_URL, {
        payload: payload,
        source_ip: sourceIp
    }, { timeout: 2000 })
    .catch(err => console.log('ThreatLens error:', err.message));
    
    next();
};

// Usage
app.use(threatLensMiddleware);

---

Python Django Integration

import requests
from django.utils.deprecation import MiddlewareMixin
from concurrent.futures import ThreadPoolExecutor

executor = ThreadPoolExecutor(max_workers=2)

THREAT_LENS_URL = 'http://localhost:8000/api/logs'

def send_to_threatlens(payload, source_ip):
    try:
        requests.post(THREAT_LENS_URL, json={
            'payload': payload,
            'source_ip': source_ip
        }, timeout=2)
    except Exception as e:
        print(f'ThreatLens error: {e}')

class ThreatLensMiddleware(MiddlewareMixin):
    def process_request(self, request):
        payload = request.get_full_path()
        source_ip = request.META.get('REMOTE_ADDR', '')
        
        # Non-blocking
        executor.submit(send_to_threatlens, payload, source_ip)
        
        return None

Add to settings.py:

MIDDLEWARE = [
    'yourapp.middleware.ThreatLensMiddleware',
    # ... other middleware
]

---

Python Flask Integration

import requests
from flask import Flask, request, g
from concurrent.futures import ThreadPoolExecutor

app = Flask(__name__)
executor = ThreadPoolExecutor(max_workers=2)

THREAT_LENS_URL = 'http://localhost:8000/api/logs'

def send_to_threatlens(payload, source_ip):
    try:
        requests.post(THREAT_LENS_URL, json={
            'payload': payload,
            'source_ip': source_ip
        }, timeout=2)
    except:
        pass

@app.before_request
def analyze_request():
    payload = request.full_path + (request.data.decode() if request.data else '')
    executor.submit(send_to_threatlens, payload, request.remote_addr)

---

PHP / Laravel Integration

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class ThreatLensMiddleware
{
    public function handle(Request $request, Closure $next)
    {
        // Non-blocking async call
        dispatch(function () use ($request) {
            try {
                Http::timeout(2)->post('http://localhost:8000/api/logs', [
                    'payload' => $request->fullUrl() . json_encode($request->all()),
                    'source_ip' => $request->ip(),
                ]);
            } catch (\Exception $e) {
                \Log::warning('ThreatLens error: ' . $e->getMessage());
            }
        })->afterResponse();

        return $next($request);
    }
}

Register in app/Http/Kernel.php:

protected $middleware = [
    \App\Http\Middleware\ThreatLensMiddleware::class,
    // ...
];

---

Docker Network Integration

If your application runs in Docker, add it to the same network:

# your-app/docker-compose.yml
services:
  your-app:
    build: .
    networks:
      - threat_lens_default
    environment:
      - THREAT_LENS_URL=http://ml_laravel:80/api/logs

networks:
  threat_lens_default:
    external: true

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Your Web Application                      │
│                   (Spring Boot, Express, Django, etc.)           │
└─────────────────────────────┬───────────────────────────────────┘
                              │ POST /api/logs
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         ThreatLens                               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐  │
│  │   Laravel   │───▶│   ML API    │    │     PostgreSQL      │  │
│  │  Dashboard  │    │  (FastAPI)  │    │   (Attack Logs)     │  │
│  │  Port 8000  │    │  Port 5000  │    │     Port 5432       │  │
│  └─────────────┘    └─────────────┘    └─────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

---

🧠 ML Model

The attack classifier is trained using:

• Algorithm: LinearSVC with TF-IDF vectorization
• Features: Character-level n-grams (1-3)
• Classes: benign, sqli, xss, cmdi, file_inclusion
• Confidence: Softmax-normalized decision function scores

Retraining the Model

cd ml_api
python train_attack_classifier.py

---

📁 Project Structure

threat_lens/
├── docker-compose.yml          # Docker orchestration
├── ml_api/                     # ML prediction service
│   ├── app.py                  # FastAPI application
│   ├── train_attack_classifier.py
│   ├── attack_classifier.pkl   # Trained model
│   ├── tfidf_vectorizer.pkl    # TF-IDF vectorizer
│   └── Dockerfile
├── ml_dashboard/               # Web dashboard
│   ├── app/
│   │   ├── Http/Controllers/   # API & page controllers
│   │   └── Services/           # Attack detection service
│   ├── resources/js/           # React components
│   │   ├── pages/dashboard/    # Dashboard pages
│   │   └── components/         # Reusable components
│   ├── routes/
│   │   ├── web.php             # Web routes
│   │   └── api.php             # API routes
│   └── Dockerfile
└── screenshots/                # Documentation images

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• scikit-learn - Machine learning library
• FastAPI - Modern Python web framework
• Laravel - PHP web framework
• Inertia.js - Modern monolith architecture
• Recharts - React charting library
• Tailwind CSS - Utility-first CSS framework

---

Made with ❤️ by Yasser Tioursi for web security