🛡️ Purple-Ops

Enterprise-Grade AI-Powered Security Operations Center (SOC) Platform

Real-time vulnerability scanning · CVE intelligence · NIST + ISO compliance · PDF reporting · RBAC auth

$ docker-compose up --build
✓ Backend   → http://localhost:8000
✓ Frontend  → http://localhost:5173
✓ Swagger   → http://localhost:8000/docs
✓ ZAP       → http://localhost:8090

📋 Table of Contents

Overview
Features
Tech Stack
Architecture
Quick Start
Project Structure
API Endpoints
RBAC Roles
Compliance
Screenshots
Author

🔍 Overview

Purple-Ops is a full-stack, production-ready Security Operations Center platform that integrates automated vulnerability scanning, real-time CVE threat intelligence, and regulatory compliance automation into a single deployable system.

Built as an MCA Final Year Major Project at Chandigarh University, it demonstrates that enterprise-grade SOC capabilities — typically costing $100K+/year in commercial tools — can be delivered through open-source technologies.

The Problem It Solves

Traditional Approach	Purple-Ops
Manual, fragmented tools	Single unified platform
No real-time CVE correlation	Automatic NIST NVD API lookup
Manual compliance mapping	Auto NIST 800-53 + ISO 27001
Sequential scanning (slow)	Parallel scanning (~4x faster)
No PDF reporting	One-click SOC reports
No RBAC	3-tier role enforcement

✨ Features

🔍 Scanning Engine

Nmap network port scanner — TCP SYN, service version detection, OS fingerprinting
OWASP ZAP web application scanner — Spider + Active scan, OWASP Top 10 detection
Parallel Scanning — ThreadPoolExecutor (5 workers), ~4x throughput improvement
Auto-routing: IP targets → Nmap, URLs → ZAP

🧠 Threat Intelligence

Real-time NIST NVD API v2.0 integration
Automatic CVE ID fetching per discovered service
CVSS 3.x severity scoring (Critical / High / Medium / Low)
AI-based risk prioritization with asset criticality weighting

🔐 Security & Auth

JWT authentication (HS256 signed tokens)
bcrypt password hashing (cost factor 12)
3-tier RBAC — Admin / Analyst / Viewer
Route-level enforcement on all 14 API endpoints
CORS, input validation, SQL injection prevention via ORM

📋 Compliance Automation

NIST SP 800-53 Rev 5 — 9 control families, 39 controls mapped
ISO/IEC 27001:2022 — Annex A technological controls, 28 controls mapped
Per-vulnerability control cross-referencing
Control frequency analysis for systemic gap identification

📄 Reporting

ReportLab PDF SOC reports — executive summary, vuln tables, compliance section
Prioritized remediation recommendations
Downloadable from dashboard in one click

🎯 Dashboard (14 Pages)

Page	Description
Dashboard	SOC command center — stat cards, live alerts, threat meter
Analytics	5 Recharts visualizations — donut, bar, area, horizontal bar, line
Alert Center	Real-time alert feed with severity filtering + detail panel
Assets	Asset inventory with CRUD + quick-scan button
Threats	Vulnerability intelligence with inline status editing
Web Scanner	OWASP ZAP-powered web assessment interface
Net Scanner	Nmap network scanning with terminal output
Threat Intel	IOC lookup — IP, domain, hash reputation analysis
Tickets	Auto-generated incident tickets for Critical/High vulns
Case Board	Card-based case management with status transitions
History	Scan history trend charts + detailed log table
Compliance	NIST + ISO mapping charts + audit-ready evidence table
Log Explorer	Searchable activity log with severity color-coding
Terminal	Real-time system activity stream

🛠️ Tech Stack

Layer	Technologies
Backend	FastAPI, SQLAlchemy, PostgreSQL/SQLite, Celery, Redis, APScheduler
Frontend	React 18, Vite 5, Recharts, Lucide React
Security Tools	Nmap 7.94+, OWASP ZAP (Docker), NIST NVD API v2.0
Auth	JWT (python-jose), bcrypt, RBAC middleware
Reporting	ReportLab, FastAPI-Mail
DevOps	Docker Compose, 5-service architecture
Standards	NIST SP 800-53 Rev 5, ISO/IEC 27001:2022, CVSS 3.x

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│              👤 User / Browser                       │
│         Admin  |  Analyst  |  Viewer                 │
└──────────────────────┬──────────────────────────────┘
                       │ HTTPS / JWT Bearer
┌──────────────────────▼──────────────────────────────┐
│       ⬡  React 18 + Vite  (localhost:5173)          │
│   14 Pages  |  5 Charts  |  Dark CyberPlatform UI   │
└──────────────────────┬──────────────────────────────┘
                       │ REST API / JSON
┌──────────────────────▼──────────────────────────────┐
│     ⚙️  FastAPI Backend  (localhost:8000)            │
│  JWT Auth  |  RBAC  |  SQLAlchemy ORM  |  14 APIs   │
└──────┬──────────┬──────────┬──────────┬─────────────┘
       │          │          │          │
  ┌────▼───┐ ┌───▼───┐ ┌────▼───┐ ┌───▼──────┐
  │Celery  │ │Scan   │ │Report  │ │Compliance│
  │Workers │ │Engine │ │Engine  │ │Mapper    │
  └────┬───┘ └───┬───┘ └────────┘ └──────────┘
       │         │
  ┌────▼──┐  ┌──▼──────────────────────────────┐
  │Redis  │  │ Nmap        OWASP ZAP    NVD API │
  │:6379  │  │ (network)   (web :8090)  (CVEs)  │
  └───────┘  └─────────────────────────────────┘
       │
  ┌────▼──────────┐
  │  PostgreSQL   │
  │  (prod DB)    │
  └───────────────┘

  🐳 All services via Docker Compose — 1 command deploy

🚀 Quick Start

Prerequisites

Docker + Docker Compose v2
Git

1. Clone the repository

git clone https://github.com/yourusername/VulnGuardAI.git
cd VulnGuardAI

2. Configure environment

cp backend/.env.example backend/.env

Edit backend/.env:

SECRET_KEY=your-super-secret-jwt-key-min-64-chars
DATABASE_URL=sqlite:///./vulnguard.db
REDIS_URL=redis://redis:6379/0
ZAP_API=http://zap:8090
NVD_API_KEY=your-nvd-api-key-optional
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_FROM=your-email@gmail.com

3. Start all services

docker-compose up --build

This starts all 5 services:

Service	URL	Description
Frontend	http://localhost:5173	React dashboard
Backend API	http://localhost:8000	FastAPI server
Swagger UI	http://localhost:8000/docs	API documentation
Redis	localhost:6379	Celery broker (internal)
OWASP ZAP	localhost:8090	Web scanner (internal)

4. Create your first admin user

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "Admin@123", "role": "admin"}'

5. Login and start scanning

Open http://localhost:5173, login with your credentials, and add your first asset!

Manual Setup (without Docker)

# Terminal 1 — Redis
docker run -d -p 6379:6379 redis:alpine

# Terminal 2 — OWASP ZAP
docker run -d -p 8090:8090 ghcr.io/zaproxy/zaproxy:stable \
  zap.sh -daemon -host 0.0.0.0 -port 8090 -config api.disablekey=true

# Terminal 3 — Backend
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Terminal 4 — Celery worker
cd backend
celery -A task_queue.celery_app worker --loglevel=info

# Terminal 5 — Frontend
cd frontend
npm install
npm run dev

📁 Project Structure

VulnGuardAI/
├── backend/
│   ├── main.py                    # App entry point, CORS, routers
│   ├── database.py                # SQLAlchemy engine + session
│   ├── .env                       # Environment config (secrets)
│   ├── requirements.txt
│   ├── Dockerfile
│   ├── models/
│   │   ├── asset.py
│   │   ├── vulnerability.py
│   │   ├── user.py
│   │   ├── ticket.py
│   │   ├── audit.py
│   │   └── scan_history.py
│   ├── routes/
│   │   ├── auth.py                # Login, register, /me
│   │   ├── assets.py              # CRUD assets
│   │   ├── scan.py                # Single + parallel scan
│   │   ├── vulnerabilities.py     # Vuln list + status update
│   │   ├── tickets.py             # Incident tickets
│   │   ├── dashboard.py           # Summary stats
│   │   ├── history.py             # Scan history
│   │   └── report.py              # PDF + compliance reports
│   ├── auth/
│   │   ├── jwt_handler.py         # Token create/verify
│   │   ├── security.py            # bcrypt helpers
│   │   └── auth.py                # RBAC dependency injection
│   ├── scanner/
│   │   ├── nmap_scanner.py        # Nmap integration
│   │   └── zap_scanner.py         # OWASP ZAP integration
│   ├── intelligence/
│   │   ├── cve_fetcher.py         # NIST NVD API client
│   │   └── compliance_mapper.py   # NIST 800-53 + ISO 27001
│   ├── ai_engine/
│   │   ├── cvss_calculator.py     # CVSS scoring logic
│   │   └── risk_model.py          # Risk prioritization
│   ├── reports/
│   │   └── pdf_report.py          # ReportLab PDF generator
│   ├── alerts/
│   │   └── email_alert.py         # FastAPI-Mail alerts
│   ├── task_queue/
│   │   ├── celery_app.py          # Celery configuration
│   │   └── scan_tasks.py          # Background scan tasks
│   └── core/
│       ├── config.py              # Settings from .env
│       ├── scheduler.py           # APScheduler jobs
│       └── alert_engine.py        # Alert trigger logic
├── frontend/
│   ├── src/
│   │   └── App.jsx                # All 14 pages (single SPA)
│   ├── public/
│   ├── .env                       # VITE_API_BASE=http://localhost:8000
│   ├── package.json
│   ├── vite.config.js
│   └── Dockerfile
├── docker-compose.yml             # 5-service orchestration
└── README.md

📡 API Endpoints

All endpoints except /auth/login and /auth/register require Authorization: Bearer <token>.

Method	Endpoint	Role Required	Description
`POST`	`/auth/register`	Public	Register new user
`POST`	`/auth/login`	Public	Login + get JWT
`GET`	`/auth/me`	All	Get current user info
`GET`	`/assets/`	All	List all assets
`POST`	`/assets/`	Admin / Analyst	Add new asset
`GET`	`/vulnerabilities/`	All	List vulnerabilities
`PUT`	`/vulnerabilities/{id}/status`	Admin / Analyst	Update status
`POST`	`/scan/{asset_id}`	Admin / Analyst	Scan single asset
`POST`	`/scan/parallel`	Admin / Analyst	Parallel scan all
`GET`	`/tickets/`	All	List tickets
`PUT`	`/tickets/{id}/status`	Admin / Analyst	Update ticket
`GET`	`/dashboard/summary`	All	Dashboard stats
`GET`	`/history/`	All	Scan history
`GET`	`/reports/vulnerabilities/pdf`	Admin / Analyst	Download PDF
`GET`	`/reports/compliance`	All	Compliance mapping

Full interactive docs: http://localhost:8000/docs

👥 RBAC Roles

Permission	Admin	Analyst	Viewer
View dashboard / analytics	✅	✅	✅
View assets / vulnerabilities	✅	✅	✅
View tickets / history	✅	✅	✅
Add / edit assets	✅	✅	❌
Trigger scans	✅	✅	❌
Update vulnerability status	✅	✅	❌
Generate PDF reports	✅	✅	❌
Manage users	✅	❌	❌
View audit logs	✅	❌	❌

📊 Performance

Metric	Result
API response time (GET endpoints)	< 70ms avg
PDF generation time	< 4s
Parallel scan speedup (5 workers)	~4x vs sequential
JWT auth coverage	100% of protected endpoints
Unit test cases	97 passed, 0 failed
Backend test coverage	89.8%
NIST SP 800-53 control coverage	83% (39/47 relevant controls)
ISO 27001 control coverage	82.4% (28/34 tech controls)

✅ Compliance Frameworks

NIST SP 800-53 Revision 5

Auto-mapped control families: AC, IA, SC, SI, RA, CM, AU, IR, SA

ISO/IEC 27001:2022 Annex A

Auto-mapped themes: Organizational Controls (A.5), Technological Controls (A.8)

OWASP Top 10 (2021)

100% coverage via OWASP ZAP active scanning engine

🧪 Running Tests

cd backend
pip install pytest pytest-mock
pytest tests/ -v --tb=short

Expected output:

97 passed in 12.4s

📸 Screenshots

Dashboard, Analytics, Compliance, Alert Center — screenshots available in /docs/Screenshots/

⚠️ Ethical Use Notice

Purple-Ops is designed exclusively for authorized security assessment of systems you own or have explicit written permission to test.

Unauthorized scanning of systems you do not own may violate the Computer Fraud and Abuse Act (CFAA), Computer Misuse Act, or equivalent legislation in your jurisdiction.

Always obtain written authorization before scanning any target.

🎓 Academic Information

Field	Details
Project Type	MCA Final Year Major Project
Student	Ayush Kumar Thakur
UID	24MCA20322 (MCA 5'B)
Institution	University Institute of Computing, Chandigarh University
Academic Year	2024–26
Domain	Cybersecurity

📄 License

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

Purple-Ops — Built with ❤️ for the cybersecurity community

"From scan to compliance report in minutes, not days."

Name		Name	Last commit message	Last commit date
backend		backend
docs		docs
frontend		frontend
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation