{"id":30357266,"url":"https://github.com/annkimani-ics/random-forest-based-idps","last_synced_at":"2026-02-17T08:03:04.320Z","repository":{"id":310497361,"uuid":"1040087245","full_name":"annKimani-ICS/Random-Forest-Based-IDPS","owner":"annKimani-ICS","description":"Random Forest-Based Intrusion Detection \u0026 Prevention System (IDPS) A machine learning-powered IDPS that detects and mitigates Denial-of-Service (DoS) attacks in corporate networks using the CIC-DDoS2019 dataset. Features a Random Forest model, modular design, and an interactive GUI for real-time monitoring and alerts.","archived":false,"fork":false,"pushed_at":"2025-11-15T14:27:08.000Z","size":16007,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-15T14:35:12.866Z","etag":null,"topics":["cic-ddos-2019","css","cybersecurity","javascript","jupyter-notebook","machine-learning","powershell","python","random-forest-classifier"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/annKimani-ICS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-18T12:43:20.000Z","updated_at":"2025-11-14T19:50:07.000Z","dependencies_parsed_at":"2025-08-18T14:33:23.268Z","dependency_job_id":"f3619098-b7c0-49a1-87ff-6359479be650","html_url":"https://github.com/annKimani-ICS/Random-Forest-Based-IDPS","commit_stats":null,"previous_names":["is-project-4th-year/grp-a-isp-annkimani-ics"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/annKimani-ICS/Random-Forest-Based-IDPS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annKimani-ICS%2FRandom-Forest-Based-IDPS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annKimani-ICS%2FRandom-Forest-Based-IDPS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annKimani-ICS%2FRandom-Forest-Based-IDPS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annKimani-ICS%2FRandom-Forest-Based-IDPS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/annKimani-ICS","download_url":"https://codeload.github.com/annKimani-ICS/Random-Forest-Based-IDPS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annKimani-ICS%2FRandom-Forest-Based-IDPS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29537254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T05:00:25.817Z","status":"ssl_error","status_checked_at":"2026-02-17T04:57:16.126Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cic-ddos-2019","css","cybersecurity","javascript","jupyter-notebook","machine-learning","powershell","python","random-forest-classifier"],"created_at":"2025-08-19T07:38:45.016Z","updated_at":"2026-02-17T08:03:04.307Z","avatar_url":"https://github.com/annKimani-ICS.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Random Forest-Based Intrusion Detection \u0026 Prevention System (IDPS)\n\n## Overview\nThis project implements a **machine learning-based Intrusion Detection and Prevention System (IDPS)** for detecting and mitigating **Denial-of-Service (DoS) attacks** in corporate networks.  \nIt uses the **Random Forest algorithm** trained on the **CIC-DDoS2019 dataset**, optimized for accuracy and practical deployment in Kenyan enterprise environments.  \nA **Graphical User Interface (GUI)** provides real-time traffic monitoring, alert management, and report generation.\n\n## Objectives\n- Detect and classify malicious DoS traffic with high accuracy.\n- Isolate and block suspicious traffic in real-time.\n- Provide a usable **GUI dashboard** for administrators.\n- Support explainability with feature importance and SHAP analysis.\n- Deliver a modular, scalable solution aligned with enterprise security needs.\n\n## System Features\n\n### Core Functionality\n- **Data Preprocessing:** Cleaning, scaling, and feature engineering pipeline\n- **Model Training:** Random Forest classifier with evaluation metrics (Accuracy, Precision, Recall, F1, AUC)\n- **Testing \u0026 Evaluation:** CIC-DDoS2019 dataset split into training/test sets; evaluated for robustness\n- **Real-time Detection:** Live traffic monitoring and DoS attack detection\n\n### User Interface\n- **Desktop GUI:** PyQt5-based dashboard for system management\n- **Multi-Factor Authentication:** TOTP-based 2FA with Google Authenticator\n- **User Management:** Role-based access control (Admin/Analyst)\n- **Alert Management:** Real-time alert monitoring and response\n\n### Security \u0026 Operations\n- **Automated Setup:** One-command installation and configuration\n- **Virtual Environment:** Isolated Python environment for stability\n- **Database Integration:** PostgreSQL with Alembic migrations\n- **Audit Logging:** Comprehensive event logging for security\n- **API Documentation:** Auto-generated Swagger/OpenAPI docs\n\n## Repository Structure\n```\nRandom-Forest-Based-IDPS/\n│\n├── Automation Scripts\n│   ├── setup.sh              # Complete project setup\n│   ├── run_backend.sh         # Start backend with venv\n│   ├── run_gui.sh            # Start GUI with venv\n│   └── run_full_system.sh    # Start both backend \u0026 GUI\n│\n├── GUI Application\n│   ├── gui/\n│   │   ├── main.py           # GUI entry point\n│   │   ├── login_window.py   # Login \u0026 MFA dialogs\n│   │   ├── dashboard_window.py # Main dashboard\n│   │   └── api_client.py     # Backend communication\n│\n├── Backend API\n│   ├── backend/\n│   │   ├── app/\n│   │   │   ├── main.py       # FastAPI application\n│   │   │   ├── auth.py       # Authentication logic\n│   │   │   ├── totp.py       # MFA implementation\n│   │   │   ├── models.py     # Database models\n│   │   │   └── routers/      # API endpoints\n│\n├── Documentation\n│   ├── README.md             # Main project docs\n│   ├── README_MFA.md         # MFA overview\n│   ├── QUICK_START_MFA.md    # Quick MFA setup\n│   ├── MFA_SETUP_GUIDE.md    # Complete MFA guide\n│   └── MFA_VISUAL_GUIDE.md   # Visual MFA walkthrough\n│\n├── Analysis \u0026 Models\n│   ├── notebooks/            # Jupyter notebooks\n│   ├── config/              # Model configurations\n│   ├── models/              # Trained ML models\n│   └── reports/             # Evaluation reports\n│\n└── Configuration\n    ├── requirements.txt      # Python dependencies\n    ├── .gitignore          # Ignored files\n    └── venv/               # Virtual environment (created by setup)\n```\n\n\n---\n\n## Tech Stack\n- **Python** – Core development\n- **scikit-learn** – Random Forest training \u0026 evaluation\n- **pandas, numpy** – Data preprocessing\n- **matplotlib, seaborn** – Visualization\n- **PyQt5** – Graphical User Interface\n- **SHAP** – Explainability\n- **VirtualBox + Kali Linux** – Traffic simulation\n\n---\n\n## Getting Started\n\n### Quick Setup (Recommended)\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/annKimani-ICS/Random-Forest-Based-IDPS.git\n   cd Random-Forest-Based-IDPS\n   ```\n\n2. **Run automated setup:**\n   ```bash\n   chmod +x setup.sh\n   ./setup.sh\n   ```\n\n3. **Start the system:**\n   ```bash\n   # Start backend only (defaults to port 3000; override with PORT=8000)\n   ./run_backend.sh\n   # or specify a custom port\n   PORT=8000 ./run_backend.sh\n   \n   # Or start GUI only (in new terminal)\n   ./run_gui.sh\n   \n   # Or start both together\n   ./run_full_system.sh\n   ```\n\n### Manual Setup (Alternative)\n\nIf you prefer manual setup or encounter issues with the automated scripts:\n\n#### Prerequisites\n- Python 3.8+ (3.10+ recommended)\n- Git\n- Virtual environment support\n\n#### Step-by-Step Installation\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/annKimani-ICS/Random-Forest-Based-IDPS.git\n   cd Random-Forest-Based-IDPS\n   ```\n\n2. **Create virtual environment:**\n   ```bash\n   python3 -m venv venv\n   source venv/bin/activate  # Linux/Mac\n   # or\n   venv\\Scripts\\activate     # Windows\n   ```\n\n3. **Install backend dependencies:**\n   ```bash\n   cd backend\n   pip install -r requirements.txt\n   ```\n\n4. **Install GUI dependencies:**\n   ```bash\n   cd ../gui\n   pip install -r requirements.txt\n   ```\n\n5. **Initialize database (if needed):**\n   ```bash\n   cd ../backend\n   alembic upgrade head  # Run migrations\n   ```\n\n6. **Run the system:**\n   ```bash\n   # Terminal 1 - Backend (recommended: local venv inside backend)\n   cd backend\n   python3 -m venv .venv \u0026\u0026 source .venv/bin/activate\n   pip install -r requirements.txt\n   uvicorn app.main:app --reload --host 0.0.0.0 --port 3000\n   \n   # Terminal 2 - GUI\n   cd gui\n   source ../venv/bin/activate\n   python main.py\n   ```\n\n### Multi-Factor Authentication Setup\n\nThis system includes **TOTP-based Multi-Factor Authentication** using Google Authenticator:\n\n1. **After logging in**, navigate to the **Security** tab\n2. **Click \"Enable Two-Factor Authentication\"**\n3. **Scan QR code** with Google Authenticator app\n4. **Enter verification code** to activate\n5. **Save recovery codes** for backup access\n\n**Detailed MFA guides:**\n- `QUICK_START_MFA.md` - Quick 5-minute setup\n- `MFA_SETUP_GUIDE.md` - Complete admin guide\n- `README_MFA.md` - MFA documentation index\n\n#**Results (Fourth Iteration)**\n**Performance Metrics:**\nAccuracy: 90.48%\nF1-Score: 90.51%\nPrecision: 90.62%\nRecall: 90.48%\nHoldout Validation F1-Score: 89.76%\nPerformance Consistency: 0.0076 (Excellent)\n\n**Key Features:**\nhour (0.218) - Time-based attack patterns\nday_of_week (0.182) - Weekly traffic behavior\nFwd Packet Length Max (0.057) - Network traffic analysis\nPacket Length Mean (0.057) - Statistical network metrics\nSubflow Fwd Bytes (0.050) - Flow analysis\nMax Packet Length (0.050) - Traffic volume indicators\nFwd Packet Length Mean (0.048) - Forward packet statistics\nAvg Fwd Segment Size (0.043) - Segment-level analysis\nTotal Length of Fwd Packets (0.039) - Packet aggregation\nAverage Packet Size (0.032) - Size-based detection\n\n**Technical Achievements:**\nTraining Time: \u003c 15 minutes (99%+ speed improvement)\nData Optimization: 581K → 50K samples (91% reduction)\nFeature Selection: 87 → 30 features (65% reduction)\nModel Architecture: Voting Ensemble (Random Forest + Random Forest)\nClass Balancing: SMOTE applied for balanced training\n\n**Application/Capability:**\nHigh-performance detection of DDoS attack flows with real-time processing capabilities, achieving enterprise-grade accuracy while maintaining sub-15-minute training cycles for rapid model deployment and updates in production network environments.\n\n**Improvement Over Previous Iterations:**\n+25.63% F1-Score improvement over Iteration 3\n+20.31% Accuracy improvement over Iteration 3\n99%+ faster training compared to initial iterations\n\n#**Roadmap**\n Sprint 1 – Data Cleaning \u0026 Preprocessing\n Sprint 2 – Model Training \u0026 Evaluation\n Sprint 3 – GUI Development (PyQt5 Dashboard)\n Sprint 4 – Integration with VM Simulation (Ubuntu + Kali)\n Sprint 5 – Final Evaluation \u0026 Defense\n\n#**Author**:\nKimani Ann Wangari\nBSc Informatics and Computer Science, Strathmore University, Nairobi, Kenya\nSupervisor: Mr. James Gikera\n\n#**License**:\nThis project is for academic and research purposes only. Unauthorized use in production environments is not advised without further security hardening.\n\n[![Review Assignment Due Date](https://classroom.github.com/assets/deadline-readme-button-22041afd0340ce965d47ae6ef1cefeee28c7c493a6346c4f15d667ab976d596c.svg)](https://classroom.github.com/a/F63P1L7A)\n[![Open in Visual Studio Code](https://classroom.github.com/assets/open-in-vscode-2e0aaae1b6195c2367325f4f02e2d04e9abb55f0b24a779b69b11b9e10269abc.svg)](https://classroom.github.com/online_ide?assignment_repo_id=20100707\u0026assignment_repo_type=AssignmentRepo)\n\nGit cheatsheet: https://philomatics.com/git-cheatsheet-release\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannkimani-ics%2Frandom-forest-based-idps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fannkimani-ics%2Frandom-forest-based-idps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannkimani-ics%2Frandom-forest-based-idps/lists"}