# OT/ICS Network Security & Asset Management System Enterprise-grade security monitoring and asset management system for Operational Technology (OT) and Industrial Control Systems (ICS) networks. --- ## 🚀 Quick Start (Windows) **Fastest way to run the application:** 1. Right-click **`RUN_AS_ADMIN.bat`** → Select "Run as administrator" 2. Application launches automatically with all checks! **See: [QUICK_START.md](QUICK_START.md) for complete quick start guide** --- ## 🔧 Having Issues? **→ See [TROUBLESHOOTING_INDEX.md](TROUBLESHOOTING_INDEX.md) - Quick navigation to all troubleshooting guides!** **Common issues:** - **Zero packets captured?** → [PACKET_CAPTURE_NOT_WORKING_FIX.md](PACKET_CAPTURE_NOT_WORKING_FIX.md) - **Blank screen after starting?** → [BLANK_SCREEN_DIAGNOSTIC.md](BLANK_SCREEN_DIAGNOSTIC.md) - **No threat detections?** → [WRONG_MONITORING_SYSTEM_FIX.md](WRONG_MONITORING_SYSTEM_FIX.md) - **Missing dependencies?** → [NEW_PC_SETUP_GUIDE.md](NEW_PC_SETUP_GUIDE.md) - **Red underlines in IDE?** → [IDE_IMPORT_WARNINGS_FIX.md](IDE_IMPORT_WARNINGS_FIX.md) **Diagnostic tools:** ```powershell python test_packet_capture.py # Full diagnostic python test_capture_simple.py # Quick capture test ``` --- ## Features - **Network Discovery**: Automatically discover devices on your network - **ML-Based IDS/IPS**: Real-time intrusion detection using hybrid machine learning models - **Anomaly Detection**: Detect unusual network behavior and security threats - **Vulnerability Assessment**: Identify security weaknesses in discovered devices - **Asset Management**: Track and manage network assets - **Real-Time Monitoring**: Continuous network monitoring with alerts - **Protocol Analysis**: Deep packet inspection and protocol analysis - **Network Visualization**: Interactive network topology visualization - **Security Reports**: Generate comprehensive security assessment reports ## Quick Start ### 🪟 Windows Users See **[WINDOWS_INSTALL.md](WINDOWS_INSTALL.md)** for Windows-specific installation instructions. ### Installation **Linux/Mac:** ```bash pip install -r requirements.txt cd src python3 main.py ``` **Windows:** ```powershell python -m pip install -r requirements.txt cd src python main.py ``` **Important**: ML features require additional dependencies. See [ML_INSTALLATION.md](ML_INSTALLATION.md) for details. ### ML System Setup If you see "ML Security System is not available" error: ```bash # Install ML dependencies pip install numpy pandas scikit-learn tensorflow xgboost # Verify installation python3 -c "import sklearn; import tensorflow; print('� ML dependencies installed')" ``` See [ML_INSTALLATION.md](ML_INSTALLATION.md) for detailed installation guide. ## Workflow 1. **Scan Network**: Discover all devices on your network 2. **Establish Baseline**: Learn normal network behavior 3. **Enable Monitoring**: Start real-time threat detection 4. **Review Alerts**: Investigate detected anomalies 5. **Generate Reports**: Create security assessment reports ## Documentation ### 📖 Quick Reference - **[QUICK_START.md](QUICK_START.md)** - Fast reference for common tasks ⭐ - **[TROUBLESHOOTING_INDEX.md](TROUBLESHOOTING_INDEX.md)** - Navigate to right solution for your issue ⭐ ### 🔧 Setup Guides - **[NEW_PC_SETUP_GUIDE.md](NEW_PC_SETUP_GUIDE.md)** - Complete setup on new PC - **[WINDOWS_INSTALL.md](WINDOWS_INSTALL.md)** - Windows installation guide - **[ML_INSTALLATION.md](ML_INSTALLATION.md)** - ML dependencies installation guide ### 🩺 Troubleshooting Guides - **[PACKET_CAPTURE_NOT_WORKING_FIX.md](PACKET_CAPTURE_NOT_WORKING_FIX.md)** - Zero packets captured - **[BLANK_SCREEN_DIAGNOSTIC.md](BLANK_SCREEN_DIAGNOSTIC.md)** - Blank screen after starting - **[WRONG_MONITORING_SYSTEM_FIX.md](WRONG_MONITORING_SYSTEM_FIX.md)** - No detections/Legacy system - **[IDE_IMPORT_WARNINGS_FIX.md](IDE_IMPORT_WARNINGS_FIX.md)** - Red underlines in IDE - **[ACTIVE_DEVICE_FILTERING_FIX.md](ACTIVE_DEVICE_FILTERING_FIX.md)** - All 255 IPs showing ### 🔬 System Documentation - **[ML_PERFORMANCE_REPORT.md](ML_PERFORMANCE_REPORT.md)** - ML model performance and metrics - **[MAIN_WINDOW_ANALYSIS.md](MAIN_WINDOW_ANALYSIS.md)** - UI workflow and features guide - **[data/datasets/QUICKSTART.md](data/datasets/QUICKSTART.md)** - Dataset setup for ML training ## System Requirements ### Minimum - Python 3.8+ - 4GB RAM - 2GB disk space ### Recommended - Python 3.10+ - 8GB RAM - 5GB disk space - Network admin privileges (for packet capture) ## Troubleshooting **→ See [TROUBLESHOOTING_INDEX.md](TROUBLESHOOTING_INDEX.md) for complete troubleshooting guide** ### Quick Fixes **"No module named 'PyQt6'"** - Install dependencies: `pip install -r requirements.txt` - Or see: [NEW_PC_SETUP_GUIDE.md](NEW_PC_SETUP_GUIDE.md) **Zero packets captured / Blank screen** - Run as Administrator (Windows) or with sudo (Linux/Mac) - Run diagnostic: `python test_packet_capture.py` - See: [PACKET_CAPTURE_NOT_WORKING_FIX.md](PACKET_CAPTURE_NOT_WORKING_FIX.md) **No threat detections** - Verify using real-time system (not legacy) - Test from DIFFERENT PC (not self-ping) - See: [WRONG_MONITORING_SYSTEM_FIX.md](WRONG_MONITORING_SYSTEM_FIX.md) ## Architecture ``` OTLAB_DEV/ � src/ � � gui/ # PyQt6 user interface � � ml/ # Machine learning models � � � models/ # Hybrid ML models (LSTM + Isolation Forest) � � � monitoring/ # Real-time monitoring � � security/ # Security analysis modules � � network/ # Network scanning and discovery � � database/ # Asset inventory database � data/ � � datasets/ # Training datasets (CICIDS2017, UNSW-NB15) � models/ # Trained ML models ``` ## ML Models The system uses hybrid machine learning models: - **LSTM Autoencoder**: Deep learning for sequence anomaly detection - **Isolation Forest**: Unsupervised anomaly detection - **Random Forest**: Attack classification - **XGBoost**: Advanced threat classification Trained on real-world datasets: - **UNSW-NB15**: 257K network traffic records with 9 attack types - **CICIDS2017**: 2.8M records with modern attack scenarios Performance: - Accuracy: 53.31% - Recall: 71.01% (detects 71% of attacks) - Precision: 64.20% - Real-time inference: <100ms per device ## License This is an enterprise security tool. Use in accordance with applicable laws and regulations. ## Security Notice This tool is designed for authorized security testing and monitoring of networks you own or have permission to test. Unauthorized network scanning or monitoring may be illegal in your jurisdiction.