Global Vulnerability Intelligence & Risk Scoring System

Overview

This project implements an end-to-end cybersecurity data science pipeline on top of the NIST NVD v2.0 API. It ingests live CVE JSON data, stores raw documents in MongoDB, curates a modeling dataset in R, trains Random Forest models for CVSS score and severity prediction, exports analytical visuals, generates Power BI web-ready tables, and serves an interactive Shiny app for manual vulnerability scoring.

The design follows the course requirements from the project brief:

• public non-Kaggle dataset
• API-based ingestion with pagination and logging
• preprocessing and missing-value handling in R
• exploratory analysis with multiple visualizations
• predictive modeling with evaluation metrics
• GitHub-managed project structure
• Power BI-ready dashboard outputs

Implemented Scope

Data engineering

• NVD API client with retry logic, pagination, local batch logging, and raw JSON archiving
• Dockerized MongoDB target for storing raw CVE documents, curated records, and app prediction logs
• Curated flat dataset generation from nested NVD JSON with vendor/product/CWE extraction

Analytics and ML

• feature engineering from description text, CVSS vector metadata, weakness labels, and vendor context
• Random Forest classifier for base_severity
• Random Forest regressor for base_score
• explicit train/test split, class balancing, and saved evaluation metrics
• automated chart export for review/demo material

Frontend and BI

• Shiny app for entering vulnerability details and predicting score/severity
• prediction audit logging for operational tracking
• Power BI web export tables and optional Power BI Service push-dataset sync
• optional ngrok workflow for remote demo access

Real Run Snapshot

The repo was executed locally against live NVD API data during implementation.

• Curated dataset size: 11,881 CVE records
• Classification test accuracy: 0.9655
• Classification test macro F1: 0.8474
• Regression test RMSE: 0.1156
• Regression test R-squared: 0.9968
• Exported visuals: 8
• Exported Power BI tables: 5

Latest metrics are written to artifacts/reports/model_metrics.json when the pipeline is run locally.

Repository Layout

NVD-Vulnerability-Risk-Scorer/
├── R/                        # Reusable R modules
├── app/                      # Shiny application
├── config/                   # Central YAML configuration
├── data/                     # Raw + processed data layout
├── docs/                     # Architecture and setup notes
├── powerbi/                  # Dashboard export area
├── scripts/                  # Runnable pipeline entrypoints
├── tests/                    # Regression test harness
├── .github/workflows/        # GitHub Actions validation
├── docker-compose.yml        # MongoDB + Mongo Express
└── Makefile                  # One-command task runner

Quick Start

1. Install dependencies

make install
cp .env.example .env

2. Start MongoDB in Docker

make start-db

If Docker is running correctly, MongoDB will be exposed on localhost:27017 and Mongo Express on http://localhost:8081.

3. Run the full pipeline

make pipeline

This runs:

1. NVD API ingestion
2. JSON flattening / curated dataset build
3. Random Forest training
4. report generation
5. Power BI export refresh

4. Launch the app

make app

The Shiny app starts on http://0.0.0.0:8501.

Key Scripts

• scripts/01_ingest_nvd.R: fetches live NVD pages and writes raw JSON batches
• scripts/02_prepare_dataset.R: creates the curated modeling dataset
• scripts/03_train_models.R: trains the Random Forest models and writes metrics
• scripts/04_generate_reports.R: exports visualizations and analysis summary
• scripts/05_sync_powerbi.R: refreshes Power BI web tables and optional push sync
• scripts/06_run_app.R: launches the Shiny frontend
• scripts/07_demo_rstudio_mongo.R: proves the R-to-Docker MongoDB connection
• scripts/08_export_powerbi_r_visuals.R: renders the two Power BI R visuals as local PNGs
• scripts/09_backfill_mongo_from_raw.R: loads saved raw NVD batches into MongoDB without another API run
• tests/run_tests.R: validates ETL/modeling/app data contracts

Power BI Web Workflow

Because Power BI Desktop is not available on macOS, this project uses a web-compatible workflow:

1. R generates dashboard-ready CSV tables under powerbi/exports/
2. optional credentials allow scripts/05_sync_powerbi.R to push rows into Power BI Service
3. dashboards are then built in the Power BI web app from those refreshed tables

Setup details are documented in docs/powerbi_web_setup.md. The explicit R visual scripts are documented in docs/powerbi_r_visuals.md.

MongoDB / Docker Demo for Class

The teacher asked for a completed experiment showing RStudio connected to a DB running in Docker. The repo includes that exact demo path:

make start-db
make backfill-raw
make demo-db

This loads the saved raw JSON batches into MongoDB and then verifies the live R-to-Docker connection with a timestamped round-trip insert/read.

Documentation

• docs/architecture.md
• docs/data_dictionary.md
• docs/powerbi_web_setup.md
• docs/powerbi_r_visuals.md
• docs/ngrok_preview.md

Notes

• API keys and Power BI credentials are read from environment variables and are not committed.
• Generated data, charts, and exports are intentionally ignored by git.
• On this machine, the code pipeline ran successfully; Docker image pulls still depended on local Docker Desktop network access. If make start-db hangs, restart Docker Desktop and retry the pull.