SafeLink Network Defense System

Advanced Machine Learning-Based ARP Spoofing Detection System

🔒 Network Security | 🤖 Machine Learning | 🎯 96.70% Accuracy | ⚡ Real-time Detection

📋 Overview

SafeLink is an intelligent network defense system that detects ARP spoofing attacks using a multi-layered machine learning approach. It combines Deterministic Finite Automaton (DFA) pre-filtering with Random Forest classification to achieve 96.70% detection accuracy with only 2.11% false positive rate.

Key Features

• ✅ Real-time ARP Packet Monitoring - Captures and analyzes Layer 2 traffic
• ✅ Machine Learning Detection - Random Forest classifier with 96.70% accuracy
• ✅ 3-Layer Detection Architecture - DFA + ANN + Random Forest fusion
• ✅ Web-Based Dashboard - React frontend for real-time monitoring
• ✅ Continuous Learning - Automated model retraining capability
• ✅ Threat Intelligence - Integration with AbuseIPDB
• ✅ RESTful API - FastAPI backend with WebSocket support
• ✅ Alert Management - Comprehensive logging and archiving

🚀 Quick Start

For Development

Windows:

# Run as Administrator
.\start_development.ps1

Linux/Mac:

sudo ./start_development.sh

This will:

1. Create virtual environment
2. Install dependencies
3. Initialize database
4. Start backend (http://localhost:8000)
5. Start frontend (http://localhost:5173)

For Production

See DEPLOYMENT_GUIDE.md for comprehensive production deployment instructions.

Quick production start (Linux):

sudo ./start_production.sh

Windows:

# Run as Administrator
.\start_production.ps1

📁 Project Structure

SafeLink/
├── 📂 Backend/
│   └── SafeLink_Backend/
│       ├── api.py                    # FastAPI application
│       ├── main.py                   # CLI entry point
│       ├── train_rf.py              # Random Forest trainer
│       ├── evaluate_models.py       # Model evaluator
│       ├── requirements.txt         # Python dependencies
│       ├── config/                  # Configuration modules
│       ├── core/                    # Core detection logic
│       ├── data/                    # Datasets & database
│       ├── models/                  # Trained ML models
│       ├── logs/                    # Application logs
│       ├── tests/                   # Test suite
│       └── utils/                   # Utility scripts
│
├── 📂 Frontend/
│   ├── src/
│   │   ├── App.jsx                  # Main React component
│   │   ├── components/              # Reusable components
│   │   ├── views/                   # Page views
│   │   └── lib/                     # API client
│   ├── package.json                 # npm dependencies
│   └── vite.config.js               # Vite configuration
│
├── 📂 docs/                         # Documentation files
├── 📂 paper_details/                # Research paper details
│
├── 📄 DEPLOYMENT_GUIDE.md           # Production deployment guide
├── 📄 README.md                     # This file
├── 🚀 start_development.sh          # Dev startup (Linux)
├── 🚀 start_development.ps1         # Dev startup (Windows)
├── 🚀 start_production.sh           # Production startup (Linux)
└── 🚀 start_production.ps1          # Production startup (Windows)

🔧 System Requirements

Minimum (Small Networks)

• OS: Ubuntu 20.04+ / Windows 10/11
• CPU: 4 cores @ 2.5 GHz
• RAM: 8 GB
• Storage: 20 GB
• Network: Gigabit Ethernet

Recommended (Enterprise)

• OS: Ubuntu 22.04 LTS Server
• CPU: 8 cores @ 3.0 GHz
• RAM: 16 GB
• Storage: 100 GB SSD
• Network: 10 Gbps

📦 Installation

Prerequisites

Ubuntu/Linux:

sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev -y
sudo apt install nodejs npm libpcap-dev -y

Windows:

1. Install Python 3.11.9
2. Install Node.js 20.x LTS
3. Install Npcap (with WinPcap compatibility)

Setup Steps

1. Clone the repository:

git clone <repository-url>
cd coreproject

2. Configure environment:

cd Backend/SafeLink_Backend
cp .env.example .env
# Edit .env file with your configuration

3. Install backend dependencies:

python3.11 -m venv venv
source venv/bin/activate  # Linux
# OR .\venv\Scripts\Activate.ps1  # Windows
pip install -r requirements.txt

4. Initialize database:

python Scripts/setup_db.py

5. Install frontend dependencies:

cd ../../Frontend
npm install

6. Start the application:

# Development mode
cd ..
sudo ./start_development.sh  # Linux
# OR .\start_development.ps1  # Windows (as Admin)

🎯 Usage

Starting the System

Development Mode:

• Backend auto-reloads on code changes
• Debug logging enabled
• Single worker process
• Access at: http://localhost:8000 (API) and http://localhost:5173 (UI)

Production Mode:

• Multiple workers (4)
• Info-level logging
• Optimized for performance
• Access at: https://your-domain.com

Accessing the Dashboard

1. Open browser: http://localhost:5173 (development) or https://your-domain.com (production)
2. Login with credentials (create account on first run)
3. Navigate through:
   • Dashboard - Real-time system status and recent alerts
   • Alerts - Complete alert history with filtering
   • Attackers - Threat intelligence and attacker profiles
   • Continuous Learning - Model training and performance
   • Mitigation - Manual response actions

API Documentation

Interactive API documentation available at:

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

📊 Performance Metrics

Random Forest Model (Production)

• Accuracy: 96.70%
• Precision: 95.98%
• Recall: 97.89%
• F1-Score: 96.93%
• ROC-AUC: 99.38%
• False Positive Rate: 2.11%
• False Negative Rate: 4.66%

System Performance

• Inference Time: ~2ms per packet
• Throughput: 1,000 packets/second
• Detection Latency: 0.2-0.5 seconds
• Memory Usage: 4-6 GB (typical)
• CPU Usage: 40-75% (under load)

🧪 Testing

Run the test suite:

cd Backend/SafeLink_Backend
source venv/bin/activate
pytest tests/

Test coverage:

pytest tests/ --cov=. --cov-report=html

🔒 Security Considerations

• HTTPS Required: Use SSL/TLS in production (see deployment guide)
• Strong Secrets: Generate secure SECRET_KEY (32+ characters)
• Rate Limiting: Enable API rate limiting to prevent brute force
• Firewall Rules: Block direct access to backend port (8000)
• Regular Updates: Keep dependencies updated monthly
• Backup Strategy: Daily database backups recommended

📚 Documentation

• Deployment Guide - Production deployment
• Vercel Deployment - Deploy to Vercel
• Git Deployment Checklist - Pre-deployment checklist
• Architecture Details - System architecture
• Tech Stack - Complete technology breakdown
• Model Results - Detailed model evaluation
• Formulas - Mathematical formulas
• Limitations - Known limitations

🖼️ Screenshots

Dashboard

Real-time network monitoring and threat detection

Alert Management

Comprehensive alert history with detailed analysis

Threat Intelligence

Attacker profiling with AbuseIPDB integration

Screenshots coming soon - Deploy and see it in action!

🚀 Live Demo

Want to see SafeLink in action?

1. Quick Local Demo:

   git clone https://github.com/Nagarohit29/Safelink.git
   cd Safelink
   # Windows
   .\start_development.ps1
   # Linux/Mac
   sudo ./start_development.sh

   Then open: http://localhost:5173

2. Deploy Your Own:

   • 
   • See VERCEL_DEPLOYMENT.md for setup instructions

⚡ Quick Links

• 📊 GitHub Actions - CI/CD Status
• 📝 Issues - Report bugs or request features
• 🔀 Pull Requests - Contribute to the project
• 📖 Wiki - Additional documentation
• 🌟 Star this repo - Show your support!

🤝 Contributing

This is a research project. For contributions:

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

📝 License

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

👥 Authors

• Research & Development Team
• Network Security Laboratory

🙏 Acknowledgments

• scikit-learn - Random Forest implementation
• FastAPI - Modern Python web framework
• React - Frontend library
• Scapy - Packet manipulation
• Vite - Frontend build tool

📧 Support & Contact

Having issues or questions?

• 🐛 Report a Bug
• 💡 Request a Feature
• 📖 Documentation
• 💬 Discussions

For security vulnerabilities: Please email: security@safelink-project.com (Do not create public issues)

🗺️ Roadmap

Version 1.1 (Planned)

• Fix ANN model performance
• Implement functional mitigation actions
• Add HTTPS support
• SIEM integration (Splunk, ELK)
• IPv6 support (NDP spoofing detection)

Version 2.0 (Future)

• Cloud deployment support (AWS, Azure, GCP)
• Distributed architecture
• Mobile application
• Advanced reporting and analytics
• Machine learning model marketplace

📈 Project Status

Metric	Status
Version	1.0.0
Status	✅ Production Ready
Build
Deployment
Last Updated	October 31, 2025
Stability	Stable
Maintenance	🟢 Active

⭐ Star History

If you find this project useful, please consider giving it a star! ⭐

---

Built with ❤️ for network security

🏠 Homepage • 📖 Documentation • 🐛 Report Bug • ✨ Request Feature