## https://sploitus.com/exploit?id=9B4F7D86-70DB-5AD6-8BA0-CEE3CB683890
# AIDRS โ AI-Powered Intrusion Detection & Response System
> A Windows-based hybrid intrusion detection and response prototype combining live packet capture, XGBoost machine-learning inference, rule-based attack detection, SOC-style incident investigation, source correlation, forensic logging, reporting, and controlled Windows Firewall containment.
[](https://www.python.org/)
[](.github/workflows/quality.yml)
[](#project-status)
[](#windows-installation)
[](LICENSE_STATUS.md)
> **Media status:** the repository structure and capture checklist are ready, but this package does not pretend that generated placeholders are real application screenshots. Replace the placeholder only after the clean-clone Windows workflow is validated.
## Why AIDRS exists
Rules are effective for known signatures, while machine learning can help identify behavioural and volumetric patterns. Detection alone is not enough: an analyst also needs evidence, correlation, workflow status, reporting, and a controlled response path. AIDRS brings these elements together in one single-host Windows laboratory prototype without claiming production or enterprise readiness.
## Core workflow
```mermaid
flowchart LR
A[Live network traffic] --> B[Scapy + Npcap]
B --> C[Windowed feature extraction]
C --> D[XGBoost volumetric inference]
B --> E[Rule and stateful detectors]
D --> F[Alert, label and confidence]
E --> F
F --> G[Investigation + MITRE context]
G --> H[Source correlation]
G --> I[SQLite evidence]
G --> J[Controlled Windows Firewall response]
I --> K[Dashboard, CSV and PDF reporting]
```
See [Architecture](docs/ARCHITECTURE.md), [AI model](docs/AI_MODEL.md), and [Detection coverage](docs/DETECTION_COVERAGE.md).
## Key features
### Monitoring
- Continuous live packet capture through Scapy and Npcap
- Active Windows interface and protected-host IPv4 discovery
- Windowed traffic-rate, byte-rate, packet-size, SYN-ratio, and forward-rate extraction
- Capture heartbeat, health visibility, and live traffic history
### AI detection
- Retained XGBoost volumetric model for live inference
- Separate full-feature XGBoost model for uploaded CIC-IDS2017-style CSV analysis
- Saved scaler, label encoder, feature-order, and model artifacts
- Probability-based labels and confidence, with explicit safety gates and configurable response threshold
### Rule and stateful detection
- SQL injection and XSS payload signatures
- SYN/port-spread scan behaviour
- HTTP request-rate and keep-alive abuse indicators
- Stateful bot-beacon and repeated-login counters
- Safe laboratory markers for selected attack families
### Investigation and correlation
- Alert severity, confidence, detection source, evidence, and action
- SOC-style status workflow: Active, Acknowledged, Investigating, Contained, Resolved, or False Positive
- Analyst notes and feedback history
- Explainable source-IP correlation across recent events
- MITRE ATT&CK context supplied by the security-intelligence mapping layer
### Response
- Manual or threshold-controlled containment
- Validation that rejects invalid, loopback, multicast, local, configured-protected, gateway, and broadcast targets
- Idempotent Windows Firewall block and unblock commands
- SQLite record of active and removed AIDRS firewall rules
### Reporting and administration
- Threat history, filtering, charts, CSV export, and ReportLab PDF reports
- Batch CSV model analysis
- Local Admin and Analyst roles
- Secure first-run administrator creation; no working password is included in the repository
- Configuration, database maintenance, and capture settings
## Technology stack
| Area | Technology |
|---|---|
| Language | Python 3.12 target |
| Dashboard | Streamlit, Plotly |
| Packet capture | Scapy, Npcap |
| Machine learning | XGBoost, scikit-learn, NumPy, pandas, joblib |
| Evidence store | SQLite |
| Reporting | pandas CSV export, ReportLab PDF generation |
| Response | Windows `netsh advfirewall` |
| Quality | pytest, coverage.py, Ruff, Bandit, pip-audit, GitHub Actions |
## AI training and live inference
The live model uses these features:
1. `Flow Packets/s`
2. `Flow Bytes/s`
3. `Average Packet Size`
4. `SYN_Ratio`
5. `Fwd Packets/s`
The documented pipeline is:
```text
CIC-IDS2017
โ merge and clean
โ consolidate labels
โ stratified train/test split
โ fit MinMaxScaler only on training data
โ train XGBoost classifier
โ evaluate on held-out data
โ save model/scaler/encoder/feature order
โ extract compatible live features
โ scaler.transform()
โ model.predict_proba()
โ decode class and confidence
```
The hybrid boundary is important: volumetric behaviour is primarily handled by XGBoost; SQL injection and XSS are primarily rule-based; bot-beacon detection is stateful/rule-based; SSH/FTP port activity is heuristic and does **not** prove a failed authentication; and port scanning can be supported by rules and ML depending on the evidence. See [AI_MODEL.md](docs/AI_MODEL.md).
## Evaluation results and limitations
The project documentation reports:
- **Overall held-out dataset classification accuracy:** 98.49%
- **Benign false-positive rate:** approximately 1.28%
These are dataset classification results, not a claim that the system prevents 98.49% of attacks. The uploaded package did not include the held-out prediction file or complete per-class report needed to independently regenerate the confusion matrix in this environment. The retained model artifacts, hashes, feature importance, and a reproducible evidence-generation script are included; per-class evidence must be regenerated from the authorised CIC-IDS2017 dataset before publication.
Rare and heterogeneous classes should be treated cautiously. Controlled-lab results do not establish production effectiveness, and encrypted HTTPS payloads are not decrypted.
## Screenshots and demo media
Expected verified filenames are documented in [assets/screenshots/README.md](assets/screenshots/README.md):
- Main dashboard and live traffic
- Threat alert and investigation details
- MITRE context and source correlation
- Firewall blocklist and threat logs
- PDF report and CSV analysis
- Configuration and architecture
The exact 20โ30 second GIF, 2โ4 minute video, and 1280ร640 social-preview capture plan is in [DEMO_GUIDE.md](docs/DEMO_GUIDE.md).
## Windows installation
### Prerequisites
- Windows 10 or Windows 11
- Python 3.12 (64-bit)
- Npcap with WinPcap API compatibility enabled
- Administrator PowerShell for packet capture and firewall actions
- Git
### Clean-clone setup
```powershell
git clone
cd AIDRS-Hybrid-Intrusion-Detection
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python scripts\initialise_database.py
python scripts\create_admin.py
```
No default user is created. The admin script prompts for a username, password, and confirmation and stores only a salted PBKDF2-HMAC-SHA256 password hash.
### Start the dashboard
```powershell
.\scripts\start_dashboard.bat
```
Equivalent command:
```powershell
python -m streamlit run Home.py
```
### Start elevated live capture
Open a second terminal and run:
```powershell
.\scripts\start_capture_admin.bat
```
Only the capture process should be elevated. The dashboard can remain a normal user process.
### Optional controlled-lab marker server
Local-only default:
```powershell
.\scripts\start_lab_server.bat
```
For an isolated authorised LAN, use the separate network script, read its warning, and explicitly confirm exposure:
```powershell
.\scripts\start_lab_server_network.bat
```
## Controlled laboratory demonstration
Use AIDRS only on systems and networks you own or are explicitly authorised to test. The full startup order, cautious commands, expected evidence, containment check, cleanup, and troubleshooting are in [DEMO_GUIDE.md](docs/DEMO_GUIDE.md).
Example low-rate scan against your own Windows lab host:
```bash
sudo nmap -sS -Pn -n -p 1-500 --max-rate 100
```
Example marker request to the explicitly exposed authorised-lab server:
```bash
curl "http://:8080/?id=1%20OR%201=1"
```
## Testing
```powershell
python -m pip install -r requirements-dev.txt
python -m ruff check .
python -m compileall -q .
python -m pytest --cov --cov-report=term-missing
python -m bandit -q -r . -x tests -ll --skip B404,B603,B607
python -m pip_audit -r requirements.txt --progress-spinner off
```
The firewall tests mock every subprocess call. Tests and CI never execute `netsh`, block an address, require Npcap, or require Administrator privileges.
## Safety notice
- Use only on owned or explicitly authorised systems and networks.
- Do not test against public, campus, employer, or third-party systems without written permission.
- Review protected IP settings before enabling automatic containment.
- Keep the dashboard and capture process separated by privilege where practical.
- Never include databases, packet captures, passwords, private reports, or real traffic logs in a public repository.
See [SECURITY.md](SECURITY.md).
## Project status
`v1.0.0-portfolio` is an academic, Windows-focused prototype release. It is intended to demonstrate end-to-end engineering, hybrid detection, investigation, evidence handling, and controlled response in an authorised laboratory.
## Known limitations
- Single-host, Windows-focused architecture
- Npcap and local Administrator privileges required for live capture
- Local Windows Firewall response only
- No TLS decryption; encrypted payload signatures are unavailable
- Model effectiveness depends on CIC-IDS2017 age, quality, class balance, and live-feature compatibility
- Heuristic SSH/FTP activity does not prove credential failure or compromise
- SQLite concurrency and retention are suitable for a prototype, not a large SOC deployment
- No cloud, distributed sensors, central SIEM, automated retraining, or production hardening in this release
See [LIMITATIONS.md](docs/LIMITATIONS.md).
## Future work after the ship line
- Expand automated tests and Windows clean-clone validation
- Separate privileged firewall response into a smaller helper
- Gradual internal module refactoring after behavioural tests exist
- Optional centralised sensors, PostgreSQL, SIEM/syslog integration, and drift monitoring
- Optional read-only demo using synthetic events
React, cloud deployment, Docker, multi-device architecture, generative AI, and automatic retraining are intentionally not part of the first portfolio release.
## Academic acknowledgement and dataset citation
AIDRS was developed as a Final Year Project by **Muhammad Faisal Abdullah**. The ML pipeline is based on the CIC-IDS2017 dataset. Users who reproduce training must obtain the dataset from its authorised source and cite the original dataset/publication as required. The dataset itself is not distributed in this repository.
## Licence status
No open-source licence has been selected. See [LICENSE_STATUS.md](LICENSE_STATUS.md). Do not assume MIT, Apache-2.0, or permission for commercial reuse.