README.md

metadata

title: NetShield – ML Model for Network Attack Detection
emoji: 🛡️
colorFrom: gray
colorTo: red
sdk: gradio
sdk_version: 5.4.0
app_file: app.py
pinned: false
license: mit

NetworkAttackDetector — Real‑time Network Threat Detection 🛡️

Lightweight Gradio app to predict and explain potential network scan types from request metadata. Built with a scikit‑learn pipeline, ready to run locally. 🚀

---

Badges

---

Table of Contents

• Demo
• Features
• Installation / Setup
• Usage
• Configuration / Options
• Contributing
• License
• Acknowledgements / Credits

---

Demo

The repository includes real demo assets under ./demo/.

• Image preview:

  

• Short walkthrough (MP4):

---

Features

• Interactive UI using gradio via ui.py → build_ui().
• Pretrained artifacts loaded from ./models/ via utils.py → load_artifacts().
• Fast inference using a serialized scikit‑learn pipeline (joblib).
• Human‑readable prediction by decoding labels with a fitted encoder.

---

Installation / Setup

Use a virtual environment for isolation.

# Create a virtual environment
python -m venv .venv

# Activate it
# On Linux/Mac:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

---

Usage

Run the Gradio app from the project root:

python app.py

Then open the local URL printed by Gradio (e.g., http://127.0.0.1:7860/).

Input fields

• Port (number)
• Request Type (e.g., GET, POST)
• Protocol (e.g., HTTP, HTTPS)
• Payload Size (number)
• User Agent (string)
• Status (e.g., 200, 404)

Output

• A predicted scan type (human‑readable label) returned by predict_intrusion().

---

Configuration / Options

• Model artifacts: The app expects the following files to exist:

  • models/network_logs_pipeline.joblib
  • models/target_encoder.joblib

• Changing artifact paths: Update utils.py → load_artifacts() if your models live elsewhere.

• Environment: Ensure your Python version satisfies the version in the badge above.

---

Contributing

Contributions are welcome! Suggestions, issues, and PRs help improve the project.

1. Fork the repo
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit changes: git commit -m "feat: add your feature"
4. Push to branch: git push origin feat/your-feature
5. Open a Pull Request

Please keep PRs focused and include context, screenshots when relevant, and tests if logic changes.

---

License

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

---

Acknowledgements / Credits

• Model training and experimentation are illustrated in network-threat-detection-with-f1-99.ipynb using pandas, numpy, scikit‑learn, xgboost, and shap.
• UI is built with gradio and model artifacts are loaded with joblib.