cve-dashboard/README.md

# STEAM Security Dashboard v1.0.0

A self-hosted vulnerability management dashboard for the NTS-AEO-STEAM and NTS-AEO-ACCESS-ENG business units. Centralises CVE tracking, Ivanti host finding triage, AEO compliance posture, FP/Archer/CARD exception workflows, and internal documentation in a single interface.

## Quick Start

### Prerequisites

- Node.js 18+
- Docker (for PostgreSQL 16 container)
- Python 3 with `python3-pandas` and `python3-openpyxl` (for compliance xlsx parsing)

### Install

```bash
git clone <repo-url>
cd cve-dashboard

# Backend dependencies
npm install

# Frontend dependencies
cd frontend && npm install && cd ..

# Python dependencies (Ubuntu/Debian)
apt install -y python3-pandas python3-openpyxl
```

### Configure

```bash
cp backend/.env.example backend/.env
# Edit backend/.env — at minimum set SESSION_SECRET and DATABASE_URL:
#   openssl rand -base64 32
```

See `backend/.env.example` for all available options including `DATABASE_URL`, Ivanti API, Jira, and Atlas integration keys.

### Start PostgreSQL

The deploy script handles the full Postgres setup — container, schema, dependencies, and data migration from SQLite:

```bash
chmod +x scripts/deploy-postgres.sh
./scripts/deploy-postgres.sh
```

For fresh installs without an existing SQLite database, the script creates the schema and skips migration.

### Build and Run

```bash
# Build frontend
cd frontend && npm run build && cd ..

# Start servers
./start-servers.sh
```

Dashboard: http://localhost:3000 · API: http://localhost:3001

The helper scripts use `systemctl` under the hood — the systemd units in `systemd/` must be installed first. See the full manual for setup instructions.

## Features

| Feature | Description |
|---------|-------------|
| **CVE Management** | Track CVEs across multiple vendors with document storage and NVD auto-fill |
| **Reporting** | Ivanti host finding triage with donut charts, inline editing, advanced filtering, CSV/XLSX export |
| **Ivanti Queue** | Personal staging list for batch FP, Archer, CARD, and Granite workflows |
| **FP Workflow** | Submit false positive workflows directly to Ivanti API with attachments |
| **Compliance** | Weekly AEO xlsx upload with diff preview, drift detection, per-team metric health cards |
| **Archive Tracking** | Automatic detection of disappeared/returned findings with BU reassignment classification |
| **Findings Trend** | Historical open vs closed chart with archive activity sparkline and shift reason tooltips |
| **Jira Integration** | Create, sync, and track Jira Data Center tickets linked to CVE/vendor pairs |
| **Archer Tickets** | Track risk acceptance exceptions (EXC numbers) linked to findings |
| **CARD API** | Granite/CARD asset lookup integration for network device workflows |
| **Knowledge Base** | Internal document library with inline PDF/Markdown viewing |
| **Access Control** | Four user groups (Admin, Standard_User, Leadership, Read_Only) with full audit trail |

## Project Structure

```
cve-dashboard/
├── backend/
│   ├── server.js              # Express API server
│   ├── db.js                  # PostgreSQL connection pool (pg)
│   ├── db-schema.sql          # Complete DDL for fresh Postgres setup
│   ├── setup-postgres.js      # Schema initializer (runs db-schema.sql)
│   ├── routes/                # API route handlers
│   ├── helpers/               # API clients (Ivanti, Jira, Atlas, CARD)
│   ├── middleware/            # Auth middleware
│   ├── migrations/            # Schema migrations (legacy SQLite deployments)
│   └── scripts/               # Compliance parser, data import utilities
├── frontend/
│   ├── src/
│   │   ├── App.js             # Main app with routing
│   │   ├── components/        # React components
│   │   └── contexts/          # Auth context
│   └── public/
├── docs/
│   ├── api/                   # API specs (Ivanti, Atlas, Jira)
│   ├── design/                # Design system, workflow diagrams
│   ├── guides/                # User guides, full reference manual
│   ├── security/              # Security audits and remediation plans
│   ├── testing/               # Test plans and scripts
│   └── troubleshooting/       # Investigation scripts and reports
├── docker-compose.yml         # PostgreSQL 16 container definition
├── scripts/
│   └── deploy-postgres.sh     # One-time deployment: container, schema, migration
├── systemd/                   # systemd service files
├── start-servers.sh
└── stop-servers.sh
```

## Tech Stack

| Layer | Technology |
|-------|------------|
| Backend | Node.js 18+, Express 5 |
| Database | PostgreSQL 16 (Docker, port 5433) |
| Frontend | React 19, Recharts, Lucide React |
| Auth | bcryptjs, cookie-based sessions, express-rate-limit |
| Compliance | Python 3, pandas, openpyxl |

## Documentation

- **[Full Reference Manual](docs/guides/full-reference-manual.md)** — comprehensive feature documentation, API reference, database schema, security model, and configuration details
- **[Postgres Migration Plan](docs/guides/postgres-migration-plan.md)** — architecture decisions, schema design, and cutover procedure for the SQLite to PostgreSQL migration
- **[Migration Guide](backend/migrations/README.md)** — schema migration scripts for upgrading existing deployments
- **[Design System](docs/design/design-system.md)** — UI component patterns and color system
- **[Ivanti API Reference](docs/api/ivanti-api-reference.md)** — Ivanti/RiskSense API integration details
- **[Jira API Use Cases](docs/api/jira-api-use-cases.md)** — Jira Data Center API compliance summary

## License

Internal use only — Charter Communications / NTS-AEO.

---

*Designed and built by Jordan Ramos (jordan.ramos@spectrum.com)*