ai-soc-assistant

# 🛡️ AI SOC Assistant

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/JuttSahib1999/ai-soc-assistant/releases)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.7%2B-blue.svg)](https://www.python.org/)
[![Author](https://img.shields.io/badge/author-Abdul%20Muqeet%20Tabraiz-orange.svg)](https://www.linkedin.com/in/abdul-muqeet-tabraiz/)

An intelligent, AI-powered Security Operations Center (SOC) Assistant that automates security alert analysis, severity classification, MITRE ATT&CK mapping, and investigation recommendations.

## 🎯 Features

- **Multi-format Alert Processing**: Accepts alerts from JSON and CSV files
- **AI-Powered Severity Classification**: Intelligent severity classification with confidence scoring
- **Contextual Alert Explanation**: Human-readable explanations of why alerts matter
- **MITRE ATT&CK Mapping**: Automatic mapping to MITRE ATT&CK framework techniques
- **Smart Investigation Steps**: Generates prioritized investigation procedures
- **Multiple Output Formats**: Text reports and JSON exports
- **Batch Processing**: Analyze multiple alerts simultaneously
- **Completely Free**: No API keys, no subscriptions, fully offline

## 🚀 Quick Start

### Prerequisites

- Python 3.7 or higher
- Windows 10 (also works on Linux/Mac)

### Installation

#### Clone the repository
```bash
git clone [https://github.com/JuttSahib1999/ai-soc-assistant.git](https://github.com/JuttSahib1999/ai-soc-assistant.git)
cd ai-soc-assistant

```

#### Install dependencies

```bash
pip install -r requirements.txt

```

## Usage

#### Process JSON alerts

```bash
python src/main.py -f data/sample_alerts.json

```

#### Process CSV alerts

```bash
python src/main.py -f data/sample_alerts.csv

```

#### Generate JSON output

```bash
python src/main.py -f data/sample_alerts.json -o json

```

#### View help

```bash
python src/main.py --help

```

## 📊 Sample Output

```text
AI SOC ASSISTANT v1.0.0

Analyzing alerts from: data/sample_alerts.json


Loaded 3 alert(s) from file

Processing Alert 1/3...
Type: ransomware_detected
Severity: CRITICAL (Confidence: 95.00%)
Report saved: output/alert_analysis_20260708_103000.txt
MITRE Techniques Found: 4


Analysis Complete! 3 alert(s) processed.

```

### 📁 Project Structure

```text
ai-soc-assistant/
├── src/                # Source code
├── data/               # Sample alert files
├── tests/              # Unit tests
├── output/             # Generated reports
├── config/             # Configuration files
└── docs/               # Documentation

```

### 🔧 Configuration

Edit `config/config.yaml` to customize:

* Analysis thresholds
* Output formats
* Report directories

### 🧪 Testing

```bash
python -m pytest tests/

```

### 📚 Documentation

#### Alert Format

#### JSON Format:

```json
{
  "alerts": [
    {
      "timestamp": "2026-07-08T10:30:00Z",
      "source_ip": "192.168.1.100",
      "destination_ip": "10.0.0.50",
      "alert_type": "ransomware_detected",
      "severity": "critical",
      "description": "Alert description here"
    }
  ]
}

```

#### CSV Format:

```csv
timestamp,source_ip,destination_ip,alert_type,severity,description
2026-07-08T10:30:00Z,192.168.1.100,10.0.0.50,ransomware_detected,critical,Alert description

```

### 🤝 Contributing

Contributions are welcome! This is Version 1.0 and will not be updated, but forks are encouraged.

### 👤 Author

**Abdul Muqeet Tabraiz**

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

### 📄 License

This project is licensed under the MIT License - see the **LICENSE** file for details.

### 🙏 Acknowledgments

* MITRE ATT&CK Framework
* Python Open Source Community
* Security Operations Community

### ⚠️ Disclaimer

This tool is for educational and defensive security purposes only. Always ensure you have proper authorization before analyzing security alerts.

---

**Made with ❤️ by Abdul Muqeet Tabraiz**
README.md
