cve-dashboard/README.md

# CVE Dashboard

A comprehensive vulnerability management system designed for tracking CVE (Common Vulnerabilities and Exposures) remediation status and maintaining vendor documentation compliance.

![Charter Communications](https://img.shields.io/badge/Charter-Communications-0476D9)
![Version](https://img.shields.io/badge/version-1.1.0-blue)
![License](https://img.shields.io/badge/license-Internal-red)

---

## 📋 Table of Contents

- [Overview](#overview)
- [Key Features](#key-features)
- [Architecture](#architecture)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage Guide](#usage-guide)
- [API Documentation](#api-documentation)
- [Database Schema](#database-schema)
- [File Organization](#file-organization)
- [Troubleshooting](#troubleshooting)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [Author](#author)

---

## 🎯 Overview

The CVE Dashboard solves a critical problem in vulnerability management: **quickly determining whether a CVE has been addressed and if required vendor documentation exists** before requesting false positive designations from security teams.

### Problem Statement

Security teams report vulnerabilities that may not apply to your environment. Before requesting a false positive designation, you need to:
1. ✅ Verify if the CVE has already been addressed
2. ✅ Confirm you have required vendor documentation (advisories, correspondence, proof of remediation)
3. ✅ Maintain organized records for audits and compliance

### Solution

This dashboard provides:
- **Instant CVE status verification** via Quick Check
- **Document compliance tracking** to ensure you have required vendor documentation
- **Automated file organization** maintaining the structure: `CVE-ID/Vendor/Documents`
- **Searchable database** with filters for vendor, severity, and status
- **RESTful API** for integration with other systems

---

## ✨ Key Features

### 🔐 User Authentication & Roles
- **Secure login**: Session-based authentication with encrypted passwords
- **Role-based access control**: Three user roles with different permissions
  - **Admin**: Full access including user management and document deletion
  - **Editor**: Can add/edit CVEs and upload documents
  - **Viewer**: Read-only access to CVEs and documents
- **User management**: Admins can create, edit, and deactivate users
- **Session persistence**: Stay logged in across browser sessions (24-hour expiry)

### 🔍 Quick CVE Status Check
- **Instant verification**: Enter any CVE ID and immediately see if it's been addressed
- **Multi-vendor display**: Shows all vendors associated with a CVE
- **Document compliance**: Shows which documents are present per vendor (Advisory ✓, Email ○, Screenshot ○)
- **Visual indicators**: Color-coded results (green = addressed, yellow = not found, red = missing required docs)

### 📂 Document Management
- **Upload documents**: PDF, images, Word docs, text files (up to 10MB)
- **Automatic organization**: Files stored as `uploads/CVE-2024-1234/Microsoft/advisory.pdf`
- **Per-vendor storage**: Each vendor's documents are organized separately
- **Document types**: Advisory, Email, Screenshot, Patch, Other
- **View & Delete**: Direct links to view documents, admin-only deletion

### 🏢 Multi-Vendor Support
- **Same CVE, multiple vendors**: Track a single CVE across different vendors (e.g., CVE-2024-1234 for both Microsoft and Cisco)
- **Vendor-specific tracking**: Each vendor entry has its own status, documents, and compliance
- **Flexible organization**: Documents organized by CVE ID and vendor

### 🔎 Search & Filter
- **Search by CVE ID or description**: Find vulnerabilities quickly
- **Filter by vendor**: Microsoft, Cisco, Oracle, VMware, Adobe, etc.
- **Filter by severity**: Critical, High, Medium, Low
- **Real-time results**: Updates as you type

### 📊 Compliance Tracking
- **Document status badges**: "✓ Docs Complete" or "⚠ Incomplete"
- **Required documents**: Advisory (mandatory), Email (optional), Screenshot (optional)
- **Vendor-specific requirements**: Customizable per vendor
- **Per-vendor compliance**: Track documentation status for each vendor separately

### 🎨 Charter/Spectrum Branding
- **Corporate colors**: Charter Blue (#0476D9) throughout
- **Professional design**: Clean, modern interface
- **Responsive layout**: Works on desktop and tablets

---

## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────────┐
│                    CVE Dashboard                         │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────┐         ┌──────────────────────┐     │
│  │   Frontend   │         │      Backend API      │     │
│  │              │  HTTP   │                       │     │
│  │  React +     │◄───────►│  Express.js          │     │
│  │  Tailwind    │  :3001  │  + Auth Middleware   │     │
│  │              │         │                       │     │
│  │  Port: 3000  │         │  ┌─────────────────┐  │     │
│  └──────────────┘         │  │  SQLite DB      │  │     │
│                           │  │  - cves         │  │     │
│                           │  │  - documents    │  │     │
│                           │  │  - required_docs│  │     │
│                           │  │  - users        │  │     │
│                           │  │  - sessions     │  │     │
│                           │  └─────────────────┘  │     │
│                           └──────────────────────┘     │
│                                      │                  │
│                                      ▼                  │
│                           ┌──────────────────────┐     │
│                           │   File Storage       │     │
│                           │                       │     │
│                           │  uploads/             │     │
│                           │  └─ CVE-2024-1234/   │     │
│                           │     ├─ Microsoft/     │     │
│                           │     │  └─ advisory.pdf│     │
│                           │     └─ Cisco/         │     │
│                           │        └─ advisory.pdf│     │
│                           └──────────────────────┘     │
└─────────────────────────────────────────────────────────┘
```

### Technology Stack

**Frontend:**
- React 18
- Tailwind CSS (via CDN)
- Lucide React (icons)
- Fetch API
- Context API (AuthContext)

**Backend:**
- Node.js v18+
- Express.js 4
- SQLite3
- Multer (file uploads)
- CORS
- bcryptjs (password hashing)
- cookie-parser (session management)
- dotenv (environment configuration)

**Database:**
- SQLite (development/production)
- Easily upgradeable to PostgreSQL

---

## 📦 Prerequisites

- **Node.js**: v18.0.0 or higher
- **npm**: v8.0.0 or higher
- **Git**: For version control
- **Linux/Unix environment**: Tested on Ubuntu 20.04+

Check your versions:
```bash
node --version
npm --version
git --version
```

---

## 🚀 Installation

### 1. Clone the Repository
```bash
git clone https://vulcan.apophisnetworking.net/jramos/cve-dashboard.git
cd cve-dashboard
```

### 2. Install Backend Dependencies
```bash
cd backend
npm install
```

Expected packages:
- express
- sqlite3
- multer
- cors
- bcryptjs
- cookie-parser
- dotenv

### 3. Install Frontend Dependencies
```bash
cd ../frontend
npm install
```

Expected packages:
- react
- react-dom
- react-scripts
- lucide-react

### 4. Initialize the Database
```bash
cd ../backend
node setup.js
```

This will:
- ✅ Create `cve_database.db`
- ✅ Create tables: `cves`, `documents`, `required_documents`, `users`, `sessions`
- ✅ Set up multi-vendor support with UNIQUE(cve_id, vendor) constraint
- ✅ Create indexes for fast queries
- ✅ Create `cve_document_status` view
- ✅ Create `uploads/` directory
- ✅ Insert default required documents for major vendors
- ✅ Create default admin user (admin/admin123)

Expected output:
```
🚀 CVE Database Setup (Multi-Vendor Support)

════════════════════════════════════════

✓ Uploads directory already exists
✓ Database initialized successfully
✓ Created default admin user (admin/admin123)

📝 Adding sample CVE data for testing...
   ✓ Added sample: CVE-2024-SAMPLE-1 / Microsoft
   ✓ Added sample: CVE-2024-SAMPLE-1 / Cisco
ℹ️  Sample data added - demonstrates multi-vendor support

╔════════════════════════════════════════════════════════╗
║          CVE DATABASE SETUP COMPLETE!                  ║
╚════════════════════════════════════════════════════════╝
```

### 5. Configure Environment Variables

Run the environment setup script to configure server IP addresses:
```bash
cd backend
chmod +x setup-env.sh
./setup-env.sh
```

The script will:
- Auto-detect your server's IP address
- Create `backend/.env` with CORS and API settings
- Create `frontend/.env` with API base URL

**Manual Configuration (Alternative):**

Create `backend/.env`:
```bash
# Backend Configuration
PORT=3001
API_HOST=YOUR_SERVER_IP
CORS_ORIGINS=http://YOUR_SERVER_IP:3000
SESSION_SECRET=your-secure-secret-key
```

Create `frontend/.env`:
```bash
# Frontend Configuration
REACT_APP_API_BASE=http://YOUR_SERVER_IP:3001/api
REACT_APP_API_HOST=http://YOUR_SERVER_IP:3001
```

### 6. Add Tailwind CSS to Frontend

Edit `frontend/public/index.html` and add this line in the `<head>` section:
```html
<script src="https://cdn.tailwindcss.com"></script>
```

### 7. Create Startup Scripts (Optional but Recommended)

**Create start-servers.sh:**
```bash
cd /home/cve-dashboard
cat > start-servers.sh << 'EOF'
#!/bin/bash
echo "Starting CVE Dashboard servers..."

# Start backend
cd backend
nohup node server.js > backend.log 2>&1 &
BACKEND_PID=$!
echo "Backend started (PID: $BACKEND_PID)"

# Start frontend
cd ../frontend
nohup npm start > frontend.log 2>&1 &
FRONTEND_PID=$!
echo "Frontend started (PID: $FRONTEND_PID)"

# Save PIDs
echo $BACKEND_PID > ../backend.pid
echo $FRONTEND_PID > ../frontend.pid

echo "✓ Both servers running in background"
echo "  Backend:  http://localhost:3001"
echo "  Frontend: http://localhost:3000"
EOF

chmod +x start-servers.sh
```

**Create stop-servers.sh:**
```bash
cat > stop-servers.sh << 'EOF'
#!/bin/bash
echo "Stopping CVE Dashboard servers..."

if [ -f backend.pid ]; then
    kill $(cat backend.pid) 2>/dev/null
    rm backend.pid
    echo "✓ Backend stopped"
fi

if [ -f frontend.pid ]; then
    kill $(cat frontend.pid) 2>/dev/null
    rm frontend.pid
    echo "✓ Frontend stopped"
fi

pkill -f "node server.js"
pkill -f "react-scripts start"
echo "All servers stopped"
EOF

chmod +x stop-servers.sh
```

---

## ⚙️ Configuration

### Backend Configuration

**Environment Variables** (`backend/.env`):
```bash
PORT=3001                              # API server port
API_HOST=192.168.2.117                 # Server IP address
CORS_ORIGINS=http://192.168.2.117:3000 # Allowed frontend origins (comma-separated)
SESSION_SECRET=your-secure-secret      # Session encryption key
```

**File Upload Limits** (`backend/server.js`):
```javascript
const upload = multer({
    storage: storage,
    limits: { fileSize: 10 * 1024 * 1024 } // 10MB limit
});
```

### Frontend Configuration

**Environment Variables** (`frontend/.env`):
```bash
REACT_APP_API_BASE=http://192.168.2.117:3001/api  # API endpoint with /api path
REACT_APP_API_HOST=http://192.168.2.117:3001      # Base URL for file downloads
```

**Severity Levels** (`frontend/src/App.js`):
```javascript
const severityLevels = ['All Severities', 'Critical', 'High', 'Medium', 'Low'];
```

### Database Configuration

**Add Required Documents for New Vendor:**
```bash
sqlite3 backend/cve_database.db
```
```sql
INSERT INTO required_documents (vendor, document_type, is_mandatory, description) 
VALUES ('Adobe', 'advisory', 1, 'Adobe Security Bulletin');
```

**Update CVE Status Values:**

Modify in `backend/server.js` or directly in database:
- `Open` - CVE identified, not yet addressed
- `Addressed` - CVE has been remediated
- `False Positive Requested` - Submitted to security team
- `False Positive Approved` - Confirmed false positive
- `Closed` - No action required

---

## 📖 Usage Guide

### Starting the Application

**Option 1: Manual Start**
```bash
# Terminal 1 - Backend
cd /home/cve-dashboard/backend
node server.js

# Terminal 2 - Frontend
cd /home/cve-dashboard/frontend
npm start
```

**Option 2: Using Startup Scripts**
```bash
cd /home/cve-dashboard
./start-servers.sh
```

**Access the application:**
- Frontend: `http://YOUR_SERVER_IP:3000`
- Backend API: `http://YOUR_SERVER_IP:3001`

### Logging In

1. Navigate to `http://YOUR_SERVER_IP:3000`
2. You'll see the login page
3. Enter credentials:
   - **Default admin**: username `admin`, password `admin123`
4. Click **"Sign In"**
5. You'll be redirected to the dashboard

**First-Time Setup:**
- After initial setup, change the default admin password
- Create additional users based on their roles:
  - **Viewers**: Read-only access (security auditors, stakeholders)
  - **Editors**: Can add/edit CVEs and upload documents (analysts)
  - **Admins**: Full access including user management (team leads)

### User Management (Admin Only)

1. Click on your username in the top right
2. Select **"User Management"**
3. From here you can:
   - View all users and their roles
   - Create new users
   - Edit user roles and status
   - Deactivate users (soft delete)

### Adding a New CVE

**Required Role:** Editor or Admin

1. Click the **"+ Add New CVE"** button (top right)
2. Fill in the form:
   - **CVE ID**: e.g., `CVE-2024-1234`
   - **Vendor**: e.g., `Microsoft`
   - **Severity**: Critical, High, Medium, or Low
   - **Description**: Brief description of the vulnerability
   - **Published Date**: Date the CVE was published
3. Click **"Add CVE"**
4. CVE appears in the dashboard immediately

**Multi-Vendor Note:** You can add the same CVE ID multiple times with different vendors. For example, CVE-2024-1234 can exist for both Microsoft and Cisco with separate tracking.

### Uploading Documents

**Required Role:** Editor or Admin

1. Find the CVE in the list
2. Click **"View Documents"** to expand
3. Click **"Upload New Document"**
4. Select your file (PDF, PNG, JPG, TXT, DOC, DOCX)
5. When prompted, specify:
   - **Vendor**: Select the vendor this document applies to
   - **Document type**: advisory, email, screenshot, patch, other
   - **Notes** (optional): Description or context
6. File uploads and organizes automatically

**File Organization Example (Multi-Vendor):**
```
uploads/
└── CVE-2024-1234/
    ├── Microsoft/
    │   ├── 1706140800000-MS-Security-Advisory.pdf
    │   └── 1706140850000-Vendor-Email.pdf
    └── Cisco/
        └── 1706140900000-Cisco-Advisory.pdf
```

### Using Quick Check

**Scenario: Security team reports CVE-2024-5678**

1. Enter `CVE-2024-5678` in the **Quick Check** box
2. Click **"Check Status"**

**Result A - Already Addressed (Multi-Vendor):**
```
✓ CVE Addressed

Vendor: Microsoft
Severity: Critical | Status: Addressed
Documents: 3 attached
✓ Advisory ✓ Email ✓ Screenshot

Vendor: Cisco
Severity: High | Status: Open
Documents: 1 attached
✓ Advisory ○ Email ○ Screenshot

Ready for false positive request (Microsoft)
```

**Result B - Not Found:**
```
⚠ Not Found
This CVE has not been addressed yet.
No entry exists in the database.

Action Required: Create entry and gather vendor documentation
```

**Result C - Incomplete:**
```
✓ CVE Addressed
Vendor: Oracle
Documents: 1 attached
✗ Advisory ○ Email ○ Screenshot

Missing required advisory - obtain before requesting false positive
```

### Searching and Filtering

**Search by CVE ID or Description:**
- Type in the search box
- Results filter in real-time

**Filter by Vendor:**
- Select from dropdown: All Vendors, Microsoft, Cisco, Oracle, VMware, Adobe

**Filter by Severity:**
- Select from dropdown: All Severities, Critical, High, Medium, Low

**Combine Filters:**
- Search for "remote code" + Vendor: Microsoft + Severity: Critical

### Viewing Documents

1. Click **"View Documents"** on any CVE
2. See list of attached documents with:
   - Document name
   - Type (advisory, email, screenshot)
   - File size
   - Notes
3. Click **"View"** to open document in new tab
4. Select checkboxes to export multiple documents

### Deleting Documents (Admin Only)

1. Expand documents for a CVE
2. Click red **"Delete"** button next to document (only visible to admins)
3. Confirm deletion in popup
4. Document removed from database and filesystem

### Exporting Documents

1. Expand documents for one or more CVEs
2. Check boxes next to documents you want to export
3. Click **"Export X Documents for Report"** at top
4. Currently shows alert (ready for integration with report system)

---

## 🔌 API Documentation

Base URL: `http://YOUR_SERVER_IP:3001/api`

**Authentication Required:** All endpoints except `/api/auth/login` require authentication via session cookie.

### Authentication Endpoints

#### Login
```http
POST /api/auth/login
Content-Type: application/json
```

**Body:**
```json
{
  "username": "admin",
  "password": "admin123"
}
```

**Response:**
```json
{
  "message": "Login successful",
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@localhost",
    "role": "admin"
  }
}
```

Sets a session cookie (`session_id`) for subsequent requests.

#### Logout
```http
POST /api/auth/logout
```

**Response:**
```json
{
  "message": "Logged out successfully"
}
```

#### Get Current User
```http
GET /api/auth/me
```

**Response:**
```json
{
  "id": 1,
  "username": "admin",
  "email": "admin@localhost",
  "role": "admin"
}
```

### User Management Endpoints (Admin Only)

#### Get All Users
```http
GET /api/users
```

#### Create User
```http
POST /api/users
Content-Type: application/json
```

**Body:**
```json
{
  "username": "newuser",
  "email": "user@example.com",
  "password": "password123",
  "role": "editor"
}
```

#### Update User
```http
PUT /api/users/:id
Content-Type: application/json
```

#### Delete User
```http
DELETE /api/users/:id
```

### CVE Endpoints

#### Get All CVEs
```http
GET /api/cves
```
**Required Role:** Any authenticated user

**Query Parameters:**
- `search` (optional): Search term for CVE ID or description
- `vendor` (optional): Filter by vendor name
- `severity` (optional): Filter by severity level

**Example:**
```bash
curl -b cookies.txt "http://192.168.2.117:3001/api/cves?vendor=Microsoft&severity=Critical"
```

**Response:**
```json
[
  {
    "id": 1,
    "cve_id": "CVE-2024-1234",
    "vendor": "Microsoft",
    "severity": "Critical",
    "description": "Remote code execution vulnerability",
    "published_date": "2024-01-15",
    "status": "Addressed",
    "created_at": "2024-01-26 10:30:00",
    "updated_at": "2024-01-26 10:30:00",
    "document_count": 3,
    "doc_status": "Complete"
  }
]
```

#### Check CVE Status
```http
GET /api/cves/check/:cveId
```
**Required Role:** Any authenticated user

**Example:**
```bash
curl -b cookies.txt "http://192.168.2.117:3001/api/cves/check/CVE-2024-1234"
```

**Response (Found - Multi-Vendor):**
```json
{
  "exists": true,
  "vendors": [
    {
      "vendor": "Microsoft",
      "severity": "Critical",
      "status": "Addressed",
      "total_documents": 3,
      "compliance": {
        "advisory": true,
        "email": true,
        "screenshot": true
      }
    },
    {
      "vendor": "Cisco",
      "severity": "High",
      "status": "Open",
      "total_documents": 1,
      "compliance": {
        "advisory": true,
        "email": false,
        "screenshot": false
      }
    }
  ],
  "addressed": true,
  "has_required_docs": true
}
```

**Response (Not Found):**
```json
{
  "exists": false,
  "message": "CVE not found - not yet addressed"
}
```

#### Get Vendors for CVE
```http
GET /api/cves/:cveId/vendors
```
**Required Role:** Any authenticated user

**Example:**
```bash
curl -b cookies.txt "http://192.168.2.117:3001/api/cves/CVE-2024-1234/vendors"
```

**Response:**
```json
[
  {
    "vendor": "Microsoft",
    "severity": "Critical",
    "status": "Addressed",
    "description": "Remote code execution vulnerability",
    "published_date": "2024-01-15"
  },
  {
    "vendor": "Cisco",
    "severity": "High",
    "status": "Open",
    "description": "Remote code execution vulnerability",
    "published_date": "2024-01-15"
  }
]
```

#### Create CVE
```http
POST /api/cves
Content-Type: application/json
```
**Required Role:** Editor or Admin

**Body:**
```json
{
  "cve_id": "CVE-2024-1234",
  "vendor": "Microsoft",
  "severity": "Critical",
  "description": "Remote code execution vulnerability in Windows Server",
  "published_date": "2024-01-15"
}
```

**Note:** The same CVE ID can be added multiple times with different vendors. The combination of (cve_id, vendor) must be unique.

**Example:**
```bash
curl -b cookies.txt -X POST http://192.168.2.117:3001/api/cves \
  -H "Content-Type: application/json" \
  -d '{
    "cve_id": "CVE-2024-1234",
    "vendor": "Microsoft",
    "severity": "Critical",
    "description": "Remote code execution vulnerability",
    "published_date": "2024-01-15"
  }'
```

**Response:**
```json
{
  "id": 1,
  "cve_id": "CVE-2024-1234",
  "message": "CVE created successfully for vendor: Microsoft"
}
```

**Error (Duplicate):**
```json
{
  "error": "This CVE already exists for this vendor. Choose a different vendor or update the existing entry."
}
```

#### Update CVE Status
```http
PATCH /api/cves/:cveId/status
Content-Type: application/json
```
**Required Role:** Editor or Admin

**Body:**
```json
{
  "status": "False Positive Requested"
}
```

**Example:**
```bash
curl -b cookies.txt -X PATCH http://192.168.2.117:3001/api/cves/CVE-2024-1234/status \
  -H "Content-Type: application/json" \
  -d '{"status": "False Positive Requested"}'
```

### Document Endpoints

#### Get Documents for CVE
```http
GET /api/cves/:cveId/documents
```
**Required Role:** Any authenticated user

**Query Parameters:**
- `vendor` (optional): Filter documents by vendor

**Example:**
```bash
curl -b cookies.txt "http://192.168.2.117:3001/api/cves/CVE-2024-1234/documents?vendor=Microsoft"
```

**Response:**
```json
[
  {
    "id": 1,
    "cve_id": "CVE-2024-1234",
    "vendor": "Microsoft",
    "name": "MS-Security-Advisory.pdf",
    "type": "advisory",
    "file_path": "uploads/CVE-2024-1234/Microsoft/1706140800000-MS-Security-Advisory.pdf",
    "file_size": "245.50 KB",
    "mime_type": "application/pdf",
    "uploaded_at": "2024-01-26 10:35:00",
    "notes": "Official Microsoft Security Advisory"
  }
]
```

#### Upload Document
```http
POST /api/cves/:cveId/documents
Content-Type: multipart/form-data
```
**Required Role:** Editor or Admin

**Form Fields:**
- `file`: The file to upload
- `vendor`: Vendor name (required - determines storage folder)
- `type`: Document type (advisory, email, screenshot, patch, other)
- `notes` (optional): Description

**Example:**
```bash
curl -b cookies.txt -X POST http://192.168.2.117:3001/api/cves/CVE-2024-1234/documents \
  -F "file=@/path/to/advisory.pdf" \
  -F "vendor=Microsoft" \
  -F "type=advisory" \
  -F "notes=Official security advisory"
```

**Response:**
```json
{
  "id": 1,
  "message": "Document uploaded successfully",
  "file": {
    "name": "advisory.pdf",
    "path": "uploads/CVE-2024-1234/Microsoft/1706140800000-advisory.pdf",
    "size": "245.50 KB"
  }
}
```

#### Delete Document
```http
DELETE /api/documents/:id
```
**Required Role:** Admin only

**Example:**
```bash
curl -b cookies.txt -X DELETE http://192.168.2.117:3001/api/documents/1
```

**Response:**
```json
{
  "message": "Document deleted successfully"
}
```

### Utility Endpoints

#### Get All Vendors
```http
GET /api/vendors
```
**Required Role:** Any authenticated user

**Example:**
```bash
curl -b cookies.txt "http://192.168.2.117:3001/api/vendors"
```

**Response:**
```json
["Microsoft", "Cisco", "Oracle", "VMware", "Adobe"]
```

#### Get Statistics
```http
GET /api/stats
```
**Required Role:** Any authenticated user

**Example:**
```bash
curl -b cookies.txt "http://192.168.2.117:3001/api/stats"
```

**Response:**
```json
{
  "total_cves": 25,
  "critical_count": 8,
  "addressed_count": 20,
  "total_documents": 75,
  "compliant_count": 18
}
```

---

## 🗄️ Database Schema

### Tables

#### `cves`
Stores CVE metadata and remediation status.

| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PRIMARY KEY | Auto-incrementing ID |
| cve_id | VARCHAR(20) | CVE identifier (e.g., CVE-2024-1234) |
| vendor | VARCHAR(100) | Vendor name |
| severity | VARCHAR(20) | Critical, High, Medium, Low |
| description | TEXT | Vulnerability description |
| published_date | DATE | Date CVE was published |
| status | VARCHAR(50) | Open, Addressed, False Positive Requested, Closed |
| created_at | TIMESTAMP | Record creation timestamp |
| updated_at | TIMESTAMP | Last update timestamp |

**Unique Constraint:** `UNIQUE(cve_id, vendor)` - Allows same CVE with different vendors

**Indexes:**
- `idx_cve_id` on `cve_id`
- `idx_vendor` on `vendor`
- `idx_severity` on `severity`
- `idx_status` on `status`

#### `documents`
Stores document metadata and file locations.

| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PRIMARY KEY | Auto-incrementing ID |
| cve_id | VARCHAR(20) | CVE identifier |
| vendor | VARCHAR(100) | Vendor name (for per-vendor organization) |
| name | VARCHAR(255) | Original filename |
| type | VARCHAR(50) | advisory, email, screenshot, patch, other |
| file_path | VARCHAR(500) | Path to file on filesystem |
| file_size | VARCHAR(20) | File size (e.g., "245.50 KB") |
| mime_type | VARCHAR(100) | MIME type (e.g., "application/pdf") |
| uploaded_at | TIMESTAMP | Upload timestamp |
| notes | TEXT | Optional notes or description |

**Foreign Key:** `cve_id` → `cves(cve_id)` ON DELETE CASCADE

**Indexes:**
- `idx_doc_cve_id` on `cve_id`
- `idx_doc_vendor` on `vendor`
- `idx_doc_type` on `type`

#### `users`
Stores user accounts for authentication.

| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PRIMARY KEY | Auto-incrementing ID |
| username | VARCHAR(50) UNIQUE | Login username |
| email | VARCHAR(255) UNIQUE | User email address |
| password_hash | VARCHAR(255) | bcrypt hashed password |
| role | VARCHAR(20) | admin, editor, or viewer |
| is_active | BOOLEAN | Account active status (1=active, 0=disabled) |
| created_at | TIMESTAMP | Account creation timestamp |
| last_login | TIMESTAMP | Last successful login |

**Roles:**
- `admin` - Full access: manage users, delete documents, all CVE operations
- `editor` - Can add/edit CVEs, upload documents
- `viewer` - Read-only access to CVEs and documents

**Indexes:**
- `idx_users_username` on `username`

#### `sessions`
Stores active user sessions.

| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PRIMARY KEY | Auto-incrementing ID |
| session_id | VARCHAR(255) UNIQUE | Session token (stored in cookie) |
| user_id | INTEGER | Foreign key to users.id |
| expires_at | TIMESTAMP | Session expiration time |
| created_at | TIMESTAMP | Session creation timestamp |

**Foreign Key:** `user_id` → `users(id)` ON DELETE CASCADE

**Indexes:**
- `idx_sessions_session_id` on `session_id`
- `idx_sessions_user_id` on `user_id`
- `idx_sessions_expires` on `expires_at`

#### `required_documents`
Defines which document types are mandatory per vendor.

| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PRIMARY KEY | Auto-incrementing ID |
| vendor | VARCHAR(100) | Vendor name |
| document_type | VARCHAR(50) | advisory, email, screenshot, etc. |
| is_mandatory | BOOLEAN | 1 = required, 0 = optional |
| description | TEXT | Description of requirement |

**Default Values:**
```sql
('Microsoft', 'advisory', 1, 'Official Microsoft Security Advisory')
('Cisco', 'advisory', 1, 'Cisco Security Advisory')
('Oracle', 'advisory', 1, 'Oracle Security Alert')
('VMware', 'advisory', 1, 'VMware Security Advisory')
('Adobe', 'advisory', 1, 'Adobe Security Bulletin')
```

### Views

#### `cve_document_status`
Provides real-time compliance status for each CVE.

**Columns:**
- `cve_id`
- `vendor`
- `severity`
- `status`
- `total_documents` - Count of all documents
- `advisory_count` - Count of advisory documents
- `email_count` - Count of email documents
- `screenshot_count` - Count of screenshot documents
- `compliance_status` - "Complete" or "Missing Required Docs"

**Example Query:**
```sql
SELECT * FROM cve_document_status 
WHERE compliance_status = 'Missing Required Docs';
```

### Database Queries

**Find all Critical CVEs without required docs:**
```sql
SELECT c.cve_id, c.vendor, c.description, cd.compliance_status
FROM cves c
JOIN cve_document_status cd ON c.cve_id = cd.cve_id
WHERE c.severity = 'Critical' 
  AND cd.compliance_status = 'Missing Required Docs';
```

**Get document count by type:**
```sql
SELECT type, COUNT(*) as count
FROM documents
GROUP BY type
ORDER BY count DESC;
```

**Find CVEs without any documents:**
```sql
SELECT c.cve_id, c.vendor, c.severity
FROM cves c
LEFT JOIN documents d ON c.cve_id = d.cve_id
WHERE d.id IS NULL;
```

---

## 📁 File Organization

### Directory Structure
```
cve-dashboard/
├── backend/
│   ├── server.js                 # Express API server
│   ├── setup.js                  # Database initialization script
│   ├── setup-env.sh              # Environment configuration script
│   ├── .env                      # Environment variables (create with setup-env.sh)
│   ├── cve_database.db           # SQLite database file
│   ├── package.json              # Backend dependencies
│   ├── middleware/
│   │   └── auth.js               # Authentication middleware
│   ├── routes/
│   │   ├── auth.js               # Login/logout endpoints
│   │   └── users.js              # User management endpoints
│   └── backend.log               # Backend log file (if using startup script)
│
├── frontend/
│   ├── public/
│   │   └── index.html            # Main HTML (includes Tailwind CDN)
│   ├── src/
│   │   ├── App.js                # Main React component
│   │   ├── index.js              # React entry point
│   │   ├── index.css             # Global styles
│   │   ├── components/
│   │   │   ├── LoginForm.js      # Login page component
│   │   │   ├── UserMenu.js       # User dropdown menu
│   │   │   └── UserManagement.js # Admin user management
│   │   └── contexts/
│   │       └── AuthContext.js    # Authentication state management
│   ├── .env                      # Environment variables (create with setup-env.sh)
│   ├── package.json              # Frontend dependencies
│   └── frontend.log              # Frontend log file (if using startup script)
│
├── uploads/                       # File storage (auto-created)
│   ├── temp/                      # Temporary upload directory
│   ├── CVE-2024-1234/
│   │   ├── Microsoft/             # Vendor-specific folder
│   │   │   ├── 1706140800000-advisory.pdf
│   │   │   └── 1706140850000-email.pdf
│   │   └── Cisco/                 # Same CVE, different vendor
│   │       └── 1706140900000-advisory.pdf
│   └── CVE-2024-5678/
│       └── Oracle/
│           └── 1706140900000-advisory.pdf
│
├── .gitignore                    # Git ignore rules
├── README.md                     # This file
├── test_cases_auth.md            # Authentication test cases
├── start-servers.sh              # Startup script
├── stop-servers.sh               # Shutdown script
├── backend.pid                   # Backend process ID (when running)
└── frontend.pid                  # Frontend process ID (when running)
```

### File Naming Convention

Uploaded files are automatically prefixed with a timestamp:
```
[unix_timestamp]-[original_filename]

Example:
1706140800000-MS-Security-Advisory.pdf
```

This prevents filename collisions and maintains chronological order.

### Folder Creation

Folders are created automatically when:
1. Database is initialized (`uploads/` and `uploads/temp/`)
2. First document is uploaded for a CVE (`uploads/CVE-ID/Vendor/`)

---

## 🔧 Troubleshooting

### Backend Won't Start

**Error: `Cannot find module 'express'`**
```bash
cd /home/cve-dashboard/backend
npm install
```

**Error: `Port 3001 is already in use`**
```bash
# Find process using port 3001
netstat -tuln | grep 3001
# or
lsof -i :3001

# Kill the process
kill -9 <PID>

# Or change port in server.js
nano server.js
# Change: const PORT = 3002;
```

**Error: `Database locked`**
SQLite allows only one write operation at a time.
```bash
# Check if multiple instances are running
ps aux | grep "node server.js"

# Kill duplicate processes
pkill -f "node server.js"

# Restart
node server.js
```

### Frontend Won't Start

**Error: `Cannot find module 'lucide-react'`**
```bash
cd /home/cve-dashboard/frontend
npm install lucide-react
```

**Error: `Port 3000 is already in use`**
```bash
# Kill process on port 3000
lsof -i :3000
kill -9 <PID>

# Or set different port
export PORT=3001
npm start
```

**Styling Not Appearing**
Make sure Tailwind CDN is in `public/index.html`:
```html
<script src="https://cdn.tailwindcss.com"></script>
```

### Upload Issues

**Error: `Failed to fetch` during upload**

1. **Check CORS configuration:**
```bash
nano backend/server.js
```
Ensure CORS allows your frontend origin:
```javascript
app.use(cors({
  origin: ['http://localhost:3000', 'http://192.168.2.117:3000'],
  credentials: true
}));
```

2. **Check upload directory permissions:**
```bash
chmod -R 755 uploads/
mkdir -p uploads/temp
```

3. **Check backend logs:**
```bash
tail -f backend/backend.log
```

**Error: `CVE ID and Vendor are required`**

This means form data isn't reaching the backend. Check:
1. Frontend is sending `cveId` and `vendor` in FormData
2. Backend multer is parsing multipart form correctly

**File Size Limit Exceeded**
Default limit is 10MB. To increase:
```javascript
// In backend/server.js
const upload = multer({ 
    storage: storage,
    limits: { fileSize: 50 * 1024 * 1024 } // 50MB
});
```

### Database Issues

**View database contents:**
```bash
cd /home/cve-dashboard/backend
sqlite3 cve_database.db

# View all CVEs
sqlite> SELECT * FROM cves;

# View all documents
sqlite> SELECT * FROM documents;

# Check compliance status
sqlite> SELECT * FROM cve_document_status;

# Exit
sqlite> .quit
```

**Reset database:**
```bash
cd /home/cve-dashboard/backend
rm cve_database.db
node setup.js
```

**Backup database:**
```bash
cp backend/cve_database.db backend/cve_database_backup_$(date +%Y%m%d).db
```

### API Connection Issues

**Error: `Failed to fetch` on all requests**

1. **Verify backend is running:**
```bash
ps aux | grep "node server.js"
curl http://192.168.2.117:3001/api/cves
```

2. **Check API_BASE URL in App.js:**
```javascript
const API_BASE = 'http://192.168.2.117:3001/api';
```

3. **Check firewall:**
```bash
# Allow port 3001
sudo ufw allow 3001
```

4. **Test backend directly:**
```bash
curl http://192.168.2.117:3001/api/cves
```

### Permission Issues

**Error: `EACCES: permission denied`**
```bash
# Fix ownership
sudo chown -R $USER:$USER /home/cve-dashboard

# Fix permissions
chmod -R 755 /home/cve-dashboard
chmod -R 777 /home/cve-dashboard/uploads
```

---

## 🗺️ Roadmap

### Version 1.1 (Current Release) ✅
- [x] **User Authentication**: Login system with user roles (admin, editor, viewer)
- [x] **Multi-Vendor Support**: Same CVE can be tracked across multiple vendors
- [x] **Environment Configuration**: .env files replace hardcoded IPs
- [ ] **Audit Logging**: Track who added/modified CVEs
- [ ] **Email Notifications**: Alert when new CVEs are added
- [ ] **Export to Excel**: Download CVE list as spreadsheet
- [ ] **Bulk Upload**: Import CVEs from CSV
- [ ] **Advanced Search**: Full-text search across all fields

### Version 1.2
- [ ] **Dashboard Analytics**: Charts showing CVE trends by vendor/severity
- [ ] **Automated CVSS Scoring**: Fetch CVSS scores from NVD API
- [ ] **Integration with Vulnerability Scanners**: Import from Nessus, Qualys, etc.
- [ ] **Document Templates**: Pre-filled templates for vendor requests
- [ ] **Mobile App**: React Native mobile version

### Version 2.0
- [ ] **PostgreSQL Migration**: Production-ready database
- [ ] **Docker Deployment**: Containerized deployment
- [ ] **SSO Integration**: Charter/Spectrum LDAP/SSO
- [ ] **API Keys**: Secure API access for integrations
- [ ] **Webhook Support**: Notify external systems on CVE updates
- [ ] **Multi-tenancy**: Support multiple business units

### Proposed Features
- Calendar view for CVE timelines
- Automated false positive workflows
- Integration with JIRA/ServiceNow
- Machine learning for auto-categorization
- PDF report generation
- Compliance reports (SOX, PCI-DSS, HIPAA)

**Have a feature request?** Open an issue in Gitea or contact the author.

---

## 🤝 Contributing

This is an internal Charter Communications project. Contributions are welcome from Charter team members.

### Development Workflow

1. **Clone the repository:**
```bash
git clone https://vulcan.apophisnetworking.net/jramos/cve-dashboard.git
cd cve-dashboard
```

2. **Create a feature branch:**
```bash
git checkout -b feature/your-feature-name
```

3. **Make your changes and commit:**
```bash
git add .
git commit -m "feat: Add your feature description"
```

4. **Push to Gitea:**
```bash
git push origin feature/your-feature-name
```

5. **Create a Pull Request** in Gitea

### Commit Message Convention

Follow [Conventional Commits](https://www.conventionalcommits.org/):

- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation changes
- `style:` Code style changes (formatting)
- `refactor:` Code refactoring
- `test:` Adding tests
- `chore:` Maintenance tasks

Examples:
```
feat: Add bulk CVE import from CSV
fix: Resolve upload timeout issue for large files
docs: Update API documentation with new endpoints
refactor: Improve database query performance
```

### Code Style

**Backend:**
- Use async/await for asynchronous operations
- Error handling with try/catch
- Descriptive variable names
- Comment complex logic

**Frontend:**
- React functional components with hooks
- Tailwind utility classes for styling
- No inline styles
- Extract reusable components

### Testing

Before submitting:
1. Test all CRUD operations
2. Test file upload/download/delete
3. Test Quick Check with various scenarios
4. Test search and filters
5. Verify on clean database

---

## 👤 Author

**jramos**  
Charter Communications  
Vulnerability Management Team

**Contact:**
- Gitea: [@jramos](https://vulcan.apophisnetworking.net/jramos)
- Email: jramos@charter.com (internal)

---

## 📄 License

**Internal Use Only** - Charter Communications

This software is proprietary and confidential. Unauthorized copying, distribution, or use of this software, via any medium, is strictly prohibited.

Copyright © 2024-2026 Charter Communications. All rights reserved.

---

## 📊 Project Statistics

- **Version**: 1.1.0
- **Released**: January 2026
- **Lines of Code**: ~2,500
- **Dependencies**: 15
- **Supported Browsers**: Chrome, Edge, Firefox, Safari

---

## 🙏 Acknowledgments

- Charter Communications Security Team for requirements and testing
- Anthropic Claude AI for development assistance
- Open-source community for dependencies (Express, React, SQLite)

---

## 📚 Additional Resources

### Related Documentation
- [SQLite Documentation](https://www.sqlite.org/docs.html)
- [Express.js Guide](https://expressjs.com/en/guide/routing.html)
- [React Documentation](https://react.dev/)
- [Tailwind CSS](https://tailwindcss.com/docs)
- [CVE Program](https://www.cve.org/)
- [NVD (National Vulnerability Database)](https://nvd.nist.gov/)

### Internal Resources
- Charter Security Portal: [link]
- Vulnerability Management SOP: [link]
- False Positive Request Process: [link]

---

## 📝 Changelog

### [1.1.0] - 2026-01-29

#### Added
- **User Authentication**: Complete login system with session-based auth
  - Three user roles: admin, editor, viewer
  - Default admin account (admin/admin123)
  - Session persistence with secure cookies
  - Password hashing with bcryptjs
- **User Management**: Admin interface for managing users
  - Create, edit, deactivate users
  - Role assignment
  - Password reset capability
- **Multi-Vendor Support**: Track same CVE across multiple vendors
  - UNIQUE constraint on (cve_id, vendor) instead of just cve_id
  - Per-vendor document storage
  - Quick Check shows all vendors for a CVE
  - New API endpoint: GET /api/cves/:cveId/vendors
- **Environment Configuration**: Replaced hardcoded IPs
  - setup-env.sh script for easy configuration
  - .env files for both frontend and backend
  - Auto-detection of server IP address

#### Changed
- All API endpoints now require authentication
- Document deletion restricted to admin role
- CVE creation/editing restricted to editor and admin roles
- stop-servers.sh improved with better process killing
- Browser tab title changed from "ReactApp" to "Dashboard"
- Document storage now organized by CVE ID AND vendor

#### Fixed
- Dynamic hostname detection now works via environment variables
- Multiple vendors can now have entries for the same CVE

### [1.0.0] - 2024-01-26

#### Added
- Initial release with core functionality
- CVE management (Create, Read, Update)
- Document upload/view/delete
- Quick CVE status check
- Search and filtering
- SQLite database
- RESTful API
- Charter/Spectrum branding
- Automatic file organization
- Document compliance tracking
- Required document configuration per vendor

#### Known Issues (Resolved in 1.1.0)
- ~~Dynamic hostname detection not working (hardcoded IP as workaround)~~ Fixed
- ~~No user authentication (single-user system)~~ Fixed
- Export functionality shows alert only (not implemented)

---

**Built with ❤️ for Charter Communications**