README.md

---
title: NetShield – ML Model for Network Attack Detection
emoji: 🛡️
colorFrom: gray
colorTo: red
sdk: gradio
sdk_version: "5.4.0"   # latest stable gradio
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

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

---

## Table of Contents

- [Demo](#demo)
- [Features](#features)
- [Installation / Setup](#installation--setup)
- [Usage](#usage)
- [Configuration / Options](#configuration--options)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgements / Credits](#acknowledgements--credits)

---

## Demo

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

- Image preview:

  ![Demo UI](./demo/demo.png)

- Short walkthrough (MP4):

  <video src="./demo/demo.mp4" controls width="640"></video>

---

## 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.

```bash
# 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:

```bash
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](./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`.