📌 VulnNarrator — AI-Powered Vulnerability Analysis & Reporting System

VulnNarrator is an end-to-end AI security pipeline that ingests raw vulnerability data (CVEs, scanners, bug bounty findings), classifies it, and generates clean, professional cybersecurity reports using a custom fine-tuned SFT model.

It combines traditional backend engineering with custom NLP models trained specifically on the structure of technical vulnerability disclosures.

This project is designed for researchers, bug bounty hunters, SOC teams, and automated security pipelines.

🚀 Features 🔍 1. Vulnerability Classification Engine

A fine-tuned GPT-2 classifier that:

Reads vulnerability descriptions

Predicts categories, severity, exploitability, CWE-type

Normalizes inconsistent scanner output

🧠 2. Report Generator (SFT Model)

A supervised fine-tuned model that generates:

Full Markdown security reports

CVSS summaries

Technical analysis

Impact explanations

Recommended remediations

It turns short or unstructured vulnerability descriptions into clean, professional writeups.

🗃 3. NVD / CVE Data Ingestion Worker

The backend includes a worker that:

Downloads NVD JSON feeds

Normalizes CVE entries

Pushes them into the database

Supports both recent and modified feeds

🧩 4. REST API (FastAPI)

FastAPI endpoints for:

/v1/findings — list + query vulnerabilities

/v1/report/generate — generate a professional Markdown report

/health — system health status

⚡ 5. Fully container-ready architecture

Built to scale:

Background workers

Model inference layer

API routing

Database with SQLAlchemy

📦 6. Git LFS Support

All large model weights (.safetensors) handled using Git LFS.

🧱 Project Architecture backend/ │ ├── app/ │ ├── main.py # FastAPI application setup │ ├── routers/ │ │ ├── findings.py # Vulnerability listing endpoints │ │ └── report.py # AI report generation endpoint │ │ │ ├── db/ │ │ ├── database.py # SQLAlchemy session + engine │ │ └── models.py # DB models for vulnerabilities │ │ │ ├── ml/ │ │ ├── sft_model/ # Fine-tuned GPT-2 model (Git LFS) │ │ │ ├── tokenizer/ # Tokenizer files │ │ │ └── model/ # Safetensors + config │ │ └── report_generator.py# Inference pipeline │ │ │ ├── services/ │ │ └── nvd_ingest.py # NVD feed ingestion logic │ │ │ └── workers/ │ └── run_nvd_worker.py # Background feed ingestion worker │ └── requirements.txt / environment.yml

🧠 Model Training Overview

1. Dataset Preparation (SFT Dataset)

A JSONL dataset of:

{ "instruction": "...", "response": "..." }

Where:

instruction = minimal vulnerability description

response = clean Markdown security report

2. Tokenizer

Rebuilt GPT-2 tokenizer with added tokens:

Instruction:

Response:

End

3. Training Details

Model: GPT-2

Epochs: 3

Batch size: 2–4 (GPU dependent)

Framework: HuggingFace Trainer

Loss: converges to ~0.7

Output: a strong domain-specific LLM for vulnerabilities

🔌 API Usage Examples ✔ Generate a Vulnerability Report

POST /v1/report/generate

Body:

{ "description": "Buffer overflow in XYZ component allows attacker to execute arbitrary code." }

Response: Returns clean Markdown report:

Security Vulnerability Report

Summary

...

🏃 Running the Backend

1. Create environment (Python 3.10 recommended) python -m venv .venv .venv\Scripts\activate

2. Install dependencies pip install -r requirements.txt

3. Run the API uvicorn app.main:app --reload

4. Run the NVD worker (optional) python app/workers/run_nvd_worker.py

📦 Git LFS Setup

To track large model files:

git lfs install git lfs track ".safetensors" git lfs track "backend/app/ml/sft_model/model/" git lfs track "backend/app/ml/sft_model/tokenizer/*" git add .gitattributes git add . git commit -m "Add LFS model files" git push

🧪 Tech Stack Backend

FastAPI

SQLAlchemy

Uvicorn

Pydantic

Machine Learning

HuggingFace Transformers

GPT-2

Tokenizers

Accelerate

Safetensors

Storage

SQLite (default)

Git LFS for models

🏆 Why This Project Stands Out

VulnNarrator isn’t a toy project. It shows deep understanding of:

ML fine-tuning

tokenizer engineering

backend + API design

working with security data feeds

architectural design

REST systems

LFS model deployments

This is the kind of project that gets: ✔ hiring manager attention ✔ portfolio standout value ✔ real-world usefulness

📣 Future Enhancements

Frontend UI dashboard

PDF export

More CVE sources

Multi-model selection

On-device inference using GGUF

Embedding-based vulnerability search