Nighthawk-UEBA

# Nighthawk-UEBA

**Nighthawk-UEBA** is a completely free, open-source, unsupervised machine learning engine designed to detect abnormal user, network, and endpoint behaviors. By leveraging Isolation Forest algorithms, it builds a baseline of normal activity and flags statistical outliers indicative of insider threats, compromised accounts, or lateral movement.

---

## ✨ Features

* **Unsupervised Learning:** No labeled attack data required. Automatically learns baseline behaviors.
* **Multi-Vector Telemetry:** Analyzes user logins, network byte transfers, and endpoint process executions simultaneously.
* **Production-Ready:** Modular architecture with logging, typed interfaces, and robust error handling.
* **Synthetic Data Generation:** Includes a built-in generator to test pipelines immediately.
* **Isolation Forest Implementation:** Uses advanced anomaly detection to distinguish between normal operational noise and potential security threats.

---

## ⚙️ Prerequisites

* **Python:** 3.13 or 3.14
* **OS:** Windows 10
* **Editor:** VS Code

---

## 🚀 Installation & Setup

1. **Clone the repository:**
```bash
git clone https://github.com/JuttSahib1999/Nighthawk-UEBA.git
cd Nighthawk-UEBA

```


2. **Create a virtual environment (Python 3.13):**
```bash
py -3.13 -m venv venv
# (Or use 'py -3.13 -m venv venv' depending on your preference)

```


3. **Activate the environment:**
```bash
venv\Scripts\activate

```


4. **Install dependencies:**
```bash
pip install -r requirements.txt

```



---

## 💻 Usage Guide

The tool operates via a simple command-line interface.

1. **Generate Synthetic Data:**
Create a dataset of 10,000 events to establish the baseline and simulate threats.
```bash
python main.py --generate 10000

```


2. **Train the Engine:**
Train the Isolation Forest model on the generated data. This step "learns" what normal activity looks like.
```bash
python main.py --train

```


3. **Detect Anomalies:**
Analyze the logs and identify abnormal entries. The results will be saved to `data/ueba_results.csv`.
```bash
python main.py --detect

```



---

## Visualizing Results

The engine outputs telemetry data for analysis and provides a prediction score indicating whether an event is 'Normal' or an 'Anomaly'.

### Input Logs (Sample)
The raw input data includes event metadata, bytes transferred, and process risk scores.
![Input Logs](screenshots/ueba_logs.png)

### Detection Results (Output)
The `prediction` and `anomaly_score` columns reveal the detected threats.
![Detection Results](screenshots/ueba_results.png)

---

## 👨‍💻 Author

Created by **Abdul Muqeet Tabraiz**

* **LinkedIn:** [Abdul Muqeet Tabraiz](https://www.linkedin.com/in/abdul-muqeet-tabraiz/)
* **GitHub:** [JuttSahib1999](https://github.com/JuttSahib1999)

---

## 📋 Version & License

* **Version:** v1.0.0 (Stable Release)
* **License:** MIT License. See the `LICENSE` file for details.