# Kernel-CVE Severity Classifier

XGBoost classifier for predicting Linux kernel CVE severity levels based on patch analysis and feature extraction.

## Overview

This classifier predicts CVE severity into three categories:
- **IMPORTANT (0)**: High severity vulnerabilities requiring immediate attention
- **MODERATE (1)**: Medium severity vulnerabilities  
- **LOW (2)**: Low severity vulnerabilities

## Complete Pipeline

This end-to-end pipeline automates CVE severity classification from raw patch data to final predictions.

### 1. Data Collection ([`cve_data_scraper.py`](cve_data_scraper.py))
- Loads CVE IDs from [`data/kernel_cves.json`](data/kernel_cves.json) (contains labeled severity data)
- Clones/updates Linux kernel and security vulnerability repositories
- Extracts CVE details, commit URLs, and patch information
- Saves structured data with patches and metadata for each CVE

### 2. Feature Extraction ([`cve_feature_extraction.py`](cve_feature_extraction.py))
- Processes scraped CVE data to extract 48 binary features:
 - **File Path Analysis**: Component types (networking, hardware, disk, etc.)
 - **Patch Content Analysis**: Security indicators (kasan, uaf, nullptr, danger, etc.)
 - **Code Pattern Analysis**: Code changes (lock, memory, timer, init patterns)
 - **Metadata Features**: CVE timing, author info, fix detection patterns
- Outputs: [`cve-dataset.csv`](data/cve-dataset.csv)
- **Result**: A structured dataset where each CVE becomes a row with 48 binary features + severity label, ready for ML training. 

### 3. Dataset Splitting ([`split_datasets_for_train_test.py`](split_datasets_for_train_test.py))
- Splits `cve_dataset.csv` into training and testing datasets based on JSON splits
- Uses `train_kernel_cves.json` and `test_kernel_cves.json` to determine which CVEs go where
- Outputs: [`cve_training_dataset.csv`](data/cve_training_dataset.csv) and [`cve_testing_dataset.csv`](data/cve_testing_dataset.csv)

### 4. Data Balancing ([`cve_smote_balancer.py`](cve_smote_balancer.py))
- Addresses class imbalance in training data using SMOTE oversampling
- Transforms [`cve_training_dataset.csv`](data/cve_training_dataset.csv) → [`balanced-training-dataset-through-smote.csv`](data/balanced-training-dataset-through-smote.csv)
- Ensures proper representation of all severity levels, especially IMPORTANT
- **NOTE**: The raw CVE data is typically imbalanced across severity levels (more LOW/MODERATE than IMPORTANT CVEs). SMOTE balancing ensures the model properly classifies all severity levels.

### 5. Model Training ([`xgboost_train.py`](xgboost_train.py))
- Trains XGBoost classifier on balanced dataset
- Saves model to [`models/cve_severity_model.pkl`](models/cve_severity_model.pkl)
- Generates [`feature_importance.csv`](models/feature_importance.csv) rankings

### 6. Testing & Evaluation ([`test_cve_model.py`](test_cve_model.py))
- Evaluates model performance on [`cve_testing_dataset.csv`](data/cve_testing_dataset.csv)
- Generates visualization metrics in [`test-results/`](test-results/)
- Outputs accuracy, confusion matrix, and classification report

### 7. Prediction ([`cve_predictor.py`](cve_predictor.py))
- Predicts severity for new CVEs using the trained model
- Supports both CVE ID and direct commit hash input

## Usage

```
# Step 1: Scrape CVE data (fetches patches for CVEs in kernel_cves.json)
python cve_data_scraper.py

# Step 2: Extract features from scraped data
python cve_feature_extraction.py

# Step 3: Split dataset into training and testing
python split_datasets_for_train_test.py

# Step 4: Balance training dataset
python cve_smote_balancer.py

# Step 5: Train the model
python xgboost_train.py

# Step 6: Test model performance
python test_cve_model.py

# Step 7: Predict severity for a specific CVE
python cve_predictor.py CVE-2022-27666
# Or with specific commit hash
python cve_predictor.py CVE-2022-27666 --commit ebe48d368e97d007bfeb76fcb065d6cfc4c96645
```
## Model Configuration

- **Algorithm**: XGBoost Classifier
- **Estimators**: 200 trees
- **Max depth**: 6
- **Learning rate**: 0.1
- **Class weights**: Balanced
- **Features**: 48 binary features from patch analysis

## Data Files

- **Input**: [`kernel_cves.json`](data/kernel_cves.json) - CVE IDs with severity labels
- **Training**: [`balanced-training-dataset-through-smote.csv`](data/balanced-training-dataset-through-smote.csv) - SMOTE-balanced dataset
- **Testing**: [`cve_testing_dataset.csv`](data/cve_testing_dataset.csv) - Held-out test set
- **Model**: [`models/cve_severity_model.pkl`](models/cve_severity_model.pkl) - Trained classifier
