- [Upgrading an Existing Deployment](#upgrading-an-existing-deployment)
- [Migrations](#migrations)
- [Troubleshooting](#troubleshooting)
---
## Overview
The STEAM Security Dashboard answers a common problem in vulnerability management: tracking which CVEs have been addressed, whether supporting vendor documentation exists, where each finding is in the remediation or exception workflow, and how the team's overall AEO compliance posture is trending week over week.
The application provides:
- A searchable, filterable CVE list with per-vendor tracking and document storage
- NVD API integration to auto-populate CVE metadata
- Python 3 with `python3-pandas` and `python3-openpyxl` apt packages (required for compliance xlsx parsing)
---
## Installation
### 1. Clone the repository
```bash
git clone <repo-url>
cd cve-dashboard
```
### 2. Install backend dependencies
```bash
npm install
```
### 3. Install frontend dependencies
```bash
cd frontend
npm install
```
### 4. Install Python dependencies
Install via apt — this is the correct approach on Ubuntu/Debian and mirrors the dev server setup:
```bash
apt install -y python3-pandas python3-openpyxl
```
> If apt packages are unavailable or you need a specific version, see `docs/python-venv-setup.md` for the venv fallback approach.
> A bulk notes import script (`import_notes_from_csv.py`) is also available in `backend/scripts/` for maintenance tasks like backfilling notes from a CSV. It uses only Python stdlib.
### 5. Configure environment variables
Create `backend/.env` — the server will refuse to start without `SESSION_SECRET`:
```bash
cd backend
cp .env.example .env
# Edit .env and set SESSION_SECRET to a random string:
# openssl rand -base64 32
```
See [Configuration](#configuration) for all available options.
The deploy script handles the full setup — starts the Postgres container, creates the schema, installs the `pg` dependency, migrates data from SQLite (if present), and builds the frontend:
This starts a PostgreSQL 16 container (`steam-postgres`) on port 5433 with a persistent Docker volume, then runs `backend/db-schema.sql` to create all tables, indexes, and views.
For manual setup or troubleshooting, the individual steps are:
```bash
docker compose up -d # Start Postgres container
node backend/setup-postgres.js # Run schema DDL
node backend/scripts/migrate-to-postgres.js # Migrate data from SQLite (if upgrading)
```
> **Existing deployments:** If upgrading from SQLite, the deploy script automatically runs the data migration. The original `backend/cve_database.db` file is preserved as a backup. See [Postgres Migration Plan](docs/guides/postgres-migration-plan.md) for full details.
**`DATABASE_URL` is required.** The backend connects to PostgreSQL via this connection string. Format: `postgresql://user:password@host:port/database`. The deploy script adds this automatically.
**`NODE_ENV` and the Secure cookie flag:** When `NODE_ENV=production`, session cookies are set with the `Secure` flag, which means the browser will only send them over HTTPS connections. If you are running the application over plain HTTP (no TLS/SSL), you **must** leave `NODE_ENV` unset or set it to `development` — otherwise login will succeed but every subsequent API request will return 401 because the browser silently drops the cookie. Only set `NODE_ENV=production` when the application is served behind HTTPS (e.g., via a reverse proxy with TLS termination).
### Frontend: `frontend/.env`
```env
REACT_APP_API_BASE=http://YOUR_IP:3001/api
REACT_APP_API_HOST=http://YOUR_IP:3001
```
Replace `YOUR_IP` with the machine's IP address or hostname. Use `localhost` for local-only access.
> **Important:** React caches environment variables at build/start time. After changing `frontend/.env`, fully restart the frontend process — a browser refresh alone is not sufficient.
Both scripts call `systemctl start` / `systemctl stop` on the `cve-backend` and `cve-frontend` services. The systemd units must be installed first — see [Running as systemd services](#running-as-systemd-services-auto-start-on-reboot) for setup.
### Running as systemd services (auto-start on reboot)
Two systemd unit files are installed to `/etc/systemd/system/` so the dashboard starts automatically when the server boots:
| Unit | What it runs |
|---|---|
| `cve-backend.service` | `node server.js` from `backend/` |
| `cve-frontend.service` | `npm start` from `frontend/` (waits for backend) |
Both services load their respective `.env` files, restart on failure (5-second delay), and append output to `backend/backend.log` and `frontend/frontend.log`.
**First-time setup** (if the units are not yet installed):
> The helper scripts (`start-servers.sh` / `stop-servers.sh`) are thin wrappers around `systemctl start` / `systemctl stop`. They require the systemd units to be installed and enabled as described above.
All routes require authentication. Four user groups are supported:
| Group | Permissions |
|---|---|
| `Admin` | Full CRUD on all resources, user management, audit log access, export all data, delete any resource regardless of ownership |
| `Standard_User` | View all data, create and edit resources, delete own resources (with state and compliance restrictions), basic export (CSV/XLSX) |
| `Leadership` | View all data, export reports/compliance/visualizations, no create/edit/delete |
| `Read_Only` | View all data only — no create, edit, delete, or export |
**Standard User delete restrictions:**
- Can only delete resources they created (`created_by` ownership check)
- Cannot delete findings marked as resolved or closed
- Cannot delete tickets linked to compliance reports
- CVE deletion triggers a cascade impact check — if any associated Archer or JIRA ticket is compliance-linked, deletion is blocked and requires Admin intervention
Sessions expire after 24 hours. Session tokens are stored in `httpOnly` cookies. Login is rate-limited to 20 attempts per 15-minute window.
The Reporting page is the core operational view for remediation tracking. It integrates with Ivanti/RiskSense to show all host findings for the configured business units, with CARD ownership integration and multi-BU scoping.
The **Group by Host** toggle in the toolbar collapses duplicate assets (same hostname + IP) with multiple finding IDs into expandable host rows. Hosts with only one finding remain as flat rows. Toggle between grouped and flat views. This reduces visual clutter when a single host has dozens of findings.
#### CARD Ownership Tooltip
Hover over any IP address in the findings table to see CARD asset ownership data in an interactive tooltip:
- Confirmed, unconfirmed, and candidate team assignments with confidence scores
- Click "Actions" to open the CARD Action Modal for direct confirm/decline/redirect operations
- Results cached per session — re-hover displays instantly without API calls
- Quick mode uses CTEC suffix only with 15s timeout to avoid multi-minute waits
- Timeouts (504) are not cached — re-hover will retry the lookup
- When Ivanti Host ID is available, uses the faster asset-search path
#### Multi-BU Scope
The multi-select BU picker at the top of the page replaces the previous binary scope toggle. Select one or more BUs to filter findings:
- NTS-AEO-ACCESS-ENG
- NTS-AEO-STEAM
- NTS-AEO-ACCESS-OPS
- NTS-AEO-INTELDEV
Per-user BU team assignments (`bu_teams` on the user record) determine the default scope.
**Inline editing:** Click a Host or DNS cell to override the Ivanti value. An amber dot (●) marks overridden cells; use the revert button (↻) to restore the original. Overrides survive re-syncs. Requires Admin or Standard_User group.
**CVE Tooltips:** Hover over any CVE badge in the table to see a tooltip with the CVE description and severity (if the CVE exists in the local database). Tooltips appear after a 300ms delay, are cached in memory for the session, and auto-position to stay within the viewport.
**Filtering:** Click ⊙ on any column header for multi-select filtering. The `— empty —` option filters to findings with no value in that column. Multiple filters are ANDed. The Action Coverage chart also acts as a filter.
**Column management:** Toggle visibility and drag to reorder via the **Columns** button. Order and visibility persist to `localStorage`.
**Row visibility:** Hide individual rows by clicking the `EyeOff` icon on any row, or select multiple rows via checkboxes and click **Hide Selected** in the bulk action toolbar. Hidden rows are excluded from the table, the Action Coverage chart, and exports. Use the **Hidden (N)** button in the toolbar to view and restore hidden rows individually or all at once. Hidden row state persists to `localStorage` across sessions. Row hiding is a personal view preference available to all user groups.
**Export:** Click **Export** to download the current filtered view as CSV or XLSX. Hidden rows and filtered rows are both excluded from exports. Requires Admin, Standard_User, or Leadership group.
A personal staging list for batch-processing FP, Archer, CARD, GRANITE, DECOM, and Remediate workflows without context-switching into Ivanti mid-review. Requires Admin or Standard_User group.
- **Create FP Workflow** — select pending FP items and click to open the FP Workflow modal, which submits a False Positive workflow batch directly to the Ivanti API with form fields, file attachments, and scope override. Attachments can be local file uploads or documents selected from the CVE document library — library documents are read from disk and sent to Ivanti identically to local uploads. Successful submission marks the queue items as complete and records the submission locally.
- **Create Jira Ticket** — select multiple items and use the consolidation modal to create a single Jira ticket covering all selected findings. Ticket links are displayed on completed items.
- **Loader Sheet** — select GRANITE items to generate a Granite Loader Sheet with CARD enrichment
- **Archer Template** — select Archer items to open the template selector for pre-filling Archer Risk Acceptance forms
- This is useful when a CARD inventory fix is done but the finding still needs an FP or Archer workflow, or when an item was assigned to the wrong workflow initially
Queue items are stored in the database, are **personal to your login**, and persist across sessions and page refreshes.
Submit False Positive workflows directly to the Ivanti API with attachments and full lifecycle tracking. Accessible from the Ivanti Queue when FP items are selected.
**Submission workflow:**
1. Select pending FP items in the queue
2. Fill in workflow name, reason, description, expiration date, and scope override
3. Attach supporting documents (local uploads or library documents, 10MB limit per file)
4. Submit — the workflow batch is created in Ivanti via API and recorded locally
**Lifecycle tracking:** Each submission tracks its status through the lifecycle:
-`submitted` — initial state after successful API submission
The Compliance page tracks NTS-AEO team posture against the AEO compliance framework using weekly xlsx reports exported from the NTS_AEO reporting system.
#### Upload Workflow
Admin and Standard_User groups can upload a new compliance report via the **Upload Report** button:
1. Drop or browse for the `NTS_AEO_YYYY_MM_DD.xlsx` file
2. The backend extracts the xlsx schema and runs a **drift check** against the parser configuration (`compliance_config.json`). If structural drift is detected, a drift review phase is shown before the diff preview:
- **Breaking** findings (red) — missing core columns or detail sheets — block the upload until the config is updated
- **Silent-miss** findings (amber) — unknown metrics or sheets that will be miscategorised — warn but allow proceeding
- **Cosmetic** findings (muted) — new columns or stale config entries — informational only
- Admins can click **Reconcile Config** to auto-patch the parser configuration and re-run the check
3. If no breaking drift exists, the **diff preview** is shown — new violations, resolved items, and recurring items since the last upload
4. Click **Confirm Upload** to commit. The upload is recorded and the device table updates immediately.
The report date is extracted automatically from the filename.
**Upload rollback:** Admins can roll back the most recent upload via `POST /api/compliance/rollback/:uploadId`. Rolling back deletes new items introduced by that upload, re-activates items it resolved, and decrements seen counts on recurring items.
#### Metric Health Cards
Each AEO metric (e.g., `2.3.4i`, `5.2.4`) is shown as a health card displaying:
- Compliance percentage vs target
- Status: Meets/Exceeds Target · Within 15% of Target · Below 15% of Target
Click a card to filter the device table to only devices failing that metric.
#### Device Table
Shows all devices currently failing one or more metrics (Active tab) or previously resolved (Resolved tab). Columns: Hostname, IP Address, Type, Failing Metrics, Times Seen. Click a row to open the detail panel.
#### Detail Panel
A slide-out panel for a selected device showing:
- **Failing Metrics** — each metric with surfaced extra fields (CVEs, SLA status, due date, OS, EoL, Splunk last seen, MFA software)
- For **2.3.x vulnerability metrics**: the `Ivanti_Vulnerability_ID` is displayed with a **View in Reporting →** button that navigates directly to the Reporting page
- **Resolved Metrics** — previously failing metrics now back in compliance
- **History** — how many times the device has appeared on the report and since when
- **Notes** — timestamped notes per metric with a multi-metric selector if multiple metrics are failing. Notes can be deleted by the author or an Admin — deleting a multi-metric note removes it from all linked metrics. Requires Admin or Standard_User group.
Notes persist across uploads and are keyed to the device hostname and metric ID.
#### Teams
Only **STEAM** and **ACCESS-ENG** teams are tracked. The team selector at the top of the page switches context between them.
- Results cached per session for instant re-display — timeouts (504) are not cached and will retry on re-hover
- When Ivanti Host ID is available, uses the CARD asset-search endpoint for faster resolution
**Direct actions (no queue item required):**
- Click "Actions" in the CARD tooltip to open the CARD Action Modal
- Modal displays full owner context: confirmed, unconfirmed, declined, and candidate teams
- Confirm, decline, or redirect ownership via the CARD API
- Bare IPs are auto-resolved to CARD asset IDs (via host_id fast path or suffix guessing: CTEC, NATL, CHTR, COML, RESI, WIFI, VOIP)
- IP address validation before mutation operations
**Queue-based actions:**
- Add findings to the queue with workflow type CARD
- Confirm, decline, or redirect from the queue panel
- Queue items are marked complete on successful CARD action
- update_token handling for safe concurrent operations
**Team assets endpoint:**
- Paginated team asset lookup by disposition (confirmed, unconfirmed, candidate)
- Used by the Granite enrichment batch endpoint for full data
---
### Granite Loader Sheet
Generate Granite Loader Sheets with CARD enrichment for network device workflows.
**Generation workflow:**
1. Add findings to the queue with workflow type GRANITE
2. Click **Loader Sheet** in the queue panel (or use the Loader Sheet button on the Reporting page)
3. The modal fetches CARD data for each IP/host_id to enrich with NCIM, Qualys, and Netops Granite fields
4. Review and edit per-row data with searchable picklists
5. Export as formatted XLSX
**CARD enrichment fields:**
-`equip_inst_id` — NCIM equipment instance ID
-`hostname` — resolved hostname from CARD
-`site_name` — NCIM site name
-`mgmt_ip_asn` — management IP ASN
-`responsible_team` — NCIM responsible team
-`equipment_class` — equipment classification
-`equip_template` — equipment template
-`equip_status` — equipment status
-`serial_number` — device serial number
**Features:**
- Searchable picklists for teams, statuses, operation types (defined in `graniteLoaderPicklists.js`)
- Column groups with configurable visibility (defined in `graniteLoaderConfig.js`)
- Per-row inline editing before export
- Batch enrichment: accepts up to 200 IPs or host_ids per request
- When no team is specified, searches both NTS-AEO-STEAM and NTS-AEO-ACCESS-ENG
---
### Atlas Action Plans
Atlas InfoSec action plan tracking with per-host vulnerability mapping. Provides visibility into which hosts have active remediation, risk acceptance, or compensating control plans.
**AtlasBadge component:**
- Appears on finding rows in the Reporting table when a host has one or more action plans
- Badge colour indicates plan type: remediation, risk acceptance, or compensating control
- Reads from local cache (`atlas_action_plans_cache` table) for instant rendering without API round-trips
**Slide-out panel:**
- Click the AtlasBadge to open the Atlas detail panel
- Shows all plans for the host with type, status, and metadata
- Qualys vulnerability mapping per host (resolved via `/hosts/vulnerabilities` endpoint)
**Cache management:**
- Local cache stores plan existence, count, and full plan JSON per host_id
- Manual refresh triggers a re-fetch from the Atlas API and updates the cache
-`atlas_known` flag indicates whether the host has been checked (avoids re-querying hosts with no plans)
**Plan operations (Admin/Standard_User):**
- Create action plans: remediation, risk_acceptance, or compensating_control
- Update existing plans (PATCH)
- Refresh cache per host
---
### Finding Archive Tracking
Automatic detection of findings that disappear between Ivanti syncs, with lifecycle state tracking and anomaly logging.
**How it works:**
- On each sync, findings present in the previous sync but absent from the current sync are classified as archived
- If a previously archived finding reappears, it transitions to RETURNED
- Findings that remain absent are eventually classified as CLOSED or CLOSED_GONE
**Lifecycle states:**
| State | Meaning |
|-------|---------|
| ARCHIVED | Finding disappeared from Ivanti (first detection) |
| RETURNED | Previously archived finding reappeared in a subsequent sync |
Bulk export tools for reports and data extracts. Available to Admin, Standard_User, and Leadership groups. Read_Only users cannot access the Exports page.
A dedicated page for managing Jira Data Center tickets linked to CVE/vendor pairs and Ivanti queue items. Accessible from the navigation drawer. Requires a configured Jira API connection (see [Configuration](#configuration)).
- **Create in Jira** — create a new Jira issue directly from the dashboard with project key, issue type, summary, and description; the resulting ticket is automatically linked to a CVE/vendor pair in the local database. CVE/Vendor fields are optional — tickets can be created with source context tracking only.
- **Multi-item creation** — from the Ivanti Queue consolidation modal, create a single Jira ticket covering multiple findings
- **Save to Dashboard** — save a Jira issue found via lookup to the local database
**Vendor-specific issue types:** The Issue Type dropdown in the creation modal is context-aware. When the Project Key field matches a recognized vendor project key (e.g., `AA_VECIMA`, `AA_CISCO`, `AA_ADTRAN`), the dropdown switches to vendor-specific issue types (Epic, Story, Task, Defect, Production Defect/Incident Fix, New Feature, Spike, Release Candidate, Documentation). For all other project keys — including the default from `JIRA_PROJECT_KEY` — the dropdown shows STEAM issue types (Story, Epic, Program, Project, Reservation, Automation Maintenance). Matching is case-insensitive and trims whitespace. Changing the project key such that the context switches (STEAM to vendor or vice versa) resets the selected issue type. The same behavior applies when creating a Jira ticket from the Ivanti Queue. The list of recognized vendor project keys is defined in `VENDOR_PROJECT_KEYS` in `frontend/src/components/pages/JiraPage.js`.
All Jira API calls are proxied through the backend. Credentials are never exposed to the browser. Rate limits are enforced client-side with inter-request delays (1s for GETs, 2s for writes). See `docs/api/jira-api-use-cases.md` for the full API compliance summary.
Template management system for Archer Risk Acceptance forms. Stores static content (Environment Overview, Segmentation, Mitigating Controls, and 5 additional sections) organised by Vendor, Platform, and Model hierarchy.
**Capabilities:**
- Full CRUD — create, view, update, and delete templates
- Clone existing templates into new vendor/platform/model combinations
- Search/filter by vendor, platform, or model (case-insensitive)
- Hierarchy browsing endpoints: list vendors, platforms per vendor, models per vendor+platform
- Per-section copy-to-clipboard buttons in the inline view panel
- Template selector integrated into the Ivanti Queue for Archer workflow items
- Accessible from nav drawer (Template Mgr) and from Archer queue items
**Template sections (8 content fields, each max 10,000 chars):**
- Environment Overview
- Segmentation
- Mitigating Controls
- Additional Info
- Charter Network Banner
- Data Classification
- Charter Network
- Additional Access List
**Hierarchy:** Vendor > Platform > Model (unique constraint on the combination). Templates are sorted alphabetically by vendor, platform, model.
---
### In-App Notifications
Native notification system providing per-user alerts for system events without external dependencies (replaces previous Webex bot integration).
**Notification types:**
-`issue_resolved` — GitLab feedback issue closed and deployed
**UI:**
- NotificationBell component in the header with unread count badge
- Click to view list of unread notifications (newest first, limited to 50)
- Mark individual notifications as read, or mark all as read
- Only the owning user can mark their own notifications
**Storage:** Notifications are stored in the `notifications` table with `user_id`, `username`, `type`, `title`, `message`, `issue_number`, and `read` flag.
---
### Feedback — GitLab Integration
In-app bug reports and feature requests submitted directly to the GitLab project as issues. Keeps the GitLab PAT server-side so credentials are never exposed to the browser.
**Submission workflow:**
1. Click the feedback button in the nav drawer
2. Select type: Bug Report or Feature Request
3. Fill in title and description
4. Optionally attach up to 3 screenshots (PNG, JPG, GIF, WebP — 5MB each)
5. Submit — creates a GitLab issue with labels (`bug` or `enhancement`) and formatted description
**Issue lifecycle:**
- GitLab webhook receiver (`POST /api/webhooks/gitlab`) listens for issue close events
- When a feedback issue is closed, the submitter username is parsed from the issue description
- An in-app notification is created for the submitter: "Your bug report has been resolved and deployed"
The Admin Panel is a full-page, tabbed interface accessible only to Admin-group users. It replaces the previous inline modal rendering and follows the dashboard's dark tactical intelligence theme. Three tabs provide consolidated access to administrative functions:
**User Management** — the default tab. Displays a themed user table with group badges (Admin in red, Standard_User in accent blue, Leadership in amber, Read_Only in muted grey). Admins can create, edit, and delete users, change group assignments, and toggle active status — all through inline forms styled to match the dashboard. Admins cannot demote themselves or deactivate their own account. Deactivating a user immediately invalidates all their active sessions. All group changes are audit-logged with previous and new group values.
**Audit Log** — a paginated, filterable log table showing every state-changing action with timestamp, username, action type, entity type, entity ID, details, and IP address. Action types are colour-coded: login in green, delete in red, create in accent blue, update in amber. Filter by username, action type, entity type, and date range. Results are paginated at 25 per page.
**System Info** — stat cards showing total user count, active user count, total audit log entries, and users who logged in within the last 7 days. A "Recent Activity" section lists the 10 most recent audit log entries.
The `UserMenu` quick-access links ("Manage Users", "Audit Log") continue to open the existing modal components for fast access without navigating to the admin page.
---
## Scripts
### `backend/scripts/parse_compliance_xlsx.py`
Called automatically by the compliance upload flow. Parses the NTS_AEO xlsx report and outputs structured JSON to stdout for consumption by the Node compliance route. Reads metric categories, core columns, and skip sheets from `compliance_config.json` (shared with the drift checker).
- Reads all detail sheets; skips sheets listed in `skip_sheets`
- Filters to rows where `Compliant == False`
- Extracts hostname, IP, device type, team, and metric ID per row
- Captures all non-core columns in `extra_json` (CVEs, SLA status, OS, EoL, Splunk, MFA, Ivanti_Vulnerability_ID, etc.)
- Parses `Summary` sheet for per-team metric health (compliance_pct, target, status)
- Extracts report date from the filename (`NTS_AEO_YYYY_MM_DD.xlsx`)
Called by the preview endpoint before parsing. Extracts the structural schema of an xlsx file as JSON — sheet names, first-row column headers per sheet, and unique metric values from the Summary sheet. The Node.js drift checker compares this schema against `compliance_config.json` to detect breaking, silent-miss, and cosmetic drift.
**Dependencies:** `openpyxl>=3.0.0`
### `backend/scripts/compliance_config.json`
Shared parser configuration file — the single source of truth for `metric_categories` (metric ID → category mapping), `core_cols` (columns that become main item fields), and `skip_sheets` (sheets excluded from parsing). Read by both `parse_compliance_xlsx.py` and the Node.js `driftChecker.js` module. Admins can auto-patch this file via the **Reconcile Config** button in the upload modal.
---
## API Reference
All endpoints are prefixed with `/api`. All endpoints except `/api/auth/login` and `/api/auth/logout` require a valid session cookie. Group requirements are listed per endpoint.
### Auth
| Method | Path | Group | Description |
|---|---|---|---|
| POST | `/api/auth/login` | Public | Log in, receive session cookie (rate-limited: 20/15min) |
| POST | `/api/auth/logout` | Public | Invalidate session |
| GET | `/api/auth/me` | Any | Get current user info (returns `group` field) |
| GET | `/api/cves` | Any | List CVEs; query params: `search`, `vendor`, `severity`, `status` |
| POST | `/api/cves` | Admin, Standard_User | Create a new CVE entry |
| PUT | `/api/cves/:id` | Admin, Standard_User | Update a CVE entry by row ID |
| PATCH | `/api/cves/:cveId/status` | Admin, Standard_User | Update status for all vendor rows matching a CVE ID |
| DELETE | `/api/cves/:id` | Admin, Standard_User | Delete a single CVE vendor entry (ownership + cascade check for Standard_User) |
| DELETE | `/api/cves/by-cve-id/:cveId` | Admin, Standard_User | Delete all vendor entries for a CVE ID (ownership + cascade check for Standard_User) |
| GET | `/api/cves/check/:cveId` | Any | Quick check: existence and status of a CVE |
| GET | `/api/cves/distinct-ids` | Any | All distinct CVE IDs (used by NVD sync) |
| GET | `/api/cves/:cveId/vendors` | Any | All vendor entries for a specific CVE ID |
| GET | `/api/cves/compliance` | Any | Document compliance status view |
| GET | `/api/cves/:cveId/tooltip` | Any | Get CVE description and severity for tooltip display (truncated to 300 chars) |
### Documents
| Method | Path | Group | Description |
|---|---|---|---|
| GET | `/api/cves/:cveId/documents` | Any | List documents for a CVE; optional `?vendor=` filter |
| POST | `/api/cves/:cveId/documents` | Admin, Standard_User | Upload a document for a CVE/vendor pair |
| DELETE | `/api/documents/:id` | Admin | Delete a document and its file from disk |
### NVD
| Method | Path | Group | Description |
|---|---|---|---|
| GET | `/api/nvd/lookup/:cveId` | Any | Look up a single CVE in the NVD 2.0 API |
| POST | `/api/cves/nvd-sync` | Admin, Standard_User | Bulk update CVE metadata from NVD |
### JIRA Tickets
| Method | Path | Group | Description |
|---|---|---|---|
| GET | `/api/jira-tickets` | Any | List tickets; optional filters: `cve_id`, `vendor`, `status` |
| POST | `/api/jira-tickets` | Admin, Standard_User | Create a JIRA ticket |
| PUT | `/api/jira-tickets/:id` | Admin, Standard_User | Update a JIRA ticket |
| DELETE | `/api/jira-tickets/:id` | Admin, Standard_User | Delete a JIRA ticket (ownership + compliance check for Standard_User) |
| GET | `/api/jira-tickets/connection-test` | Admin | Test Jira API connectivity and credentials |
| GET | `/api/jira-tickets/rate-limit` | Admin | Get current burst and daily rate limit usage |
| GET | `/api/jira-tickets/lookup/:issueKey` | Any | Look up a single Jira issue by key |
| POST | `/api/jira-tickets/search` | Any | JQL search for Jira issues |
| POST | `/api/jira-tickets/create-in-jira` | Admin, Standard_User | Create an issue in Jira and link it locally |
| POST | `/api/jira-tickets/sync-all` | Admin | Bulk-sync all tracked tickets via JQL |
| POST | `/api/jira-tickets/:id/sync` | Admin, Standard_User | Sync a single ticket's status from Jira |
### Ivanti — Host Findings
| Method | Path | Group | Description |
|---|---|---|---|
| GET | `/api/ivanti/findings` | Any | Get cached findings with notes and overrides merged in |
| POST | `/api/ivanti/findings/sync` | Admin, Standard_User | Trigger an immediate findings sync from Ivanti |
| GET | `/api/ivanti/findings/counts` | Any | Open vs closed finding totals |
| GET | `/api/ivanti/findings/fp-workflow-counts` | Any | FP workflow state breakdown |
| PUT | `/api/ivanti/findings/:findingId/override` | Admin, Standard_User | Override `hostName` or `dns`; empty value clears the override |
| PUT | `/api/ivanti/findings/:findingId/note` | Admin, Standard_User | Save or update a finding note (max 255 chars) |
### Ivanti — Workflows
| Method | Path | Group | Description |
|---|---|---|---|
| GET | `/api/ivanti/workflows` | Any | Get cached workflow data |
| POST | `/api/ivanti/workflows/sync` | Admin, Standard_User | Trigger an immediate workflow sync |
### Ivanti — FP Workflow Submission
| Method | Path | Group | Description |
|---|---|---|---|
| GET | `/api/ivanti/fp-workflow/documents/search` | Any | Search the CVE document library by name, CVE ID, or vendor; returns up to 50 matches |
| POST | `/api/ivanti/fp-workflow` | Admin, Standard_User | Submit an FP workflow batch to Ivanti API (multipart/form-data with local attachments and/or `libraryDocIds`) |
| GET | `/api/ivanti/fp-workflow/submissions` | Any | List FP submissions for the current user |
| PUT | `/api/ivanti/fp-workflow/submissions/:id` | Admin, Standard_User | Update an FP submission (edit form fields) |
| POST | `/api/ivanti/fp-workflow/submissions/:id/findings` | Admin, Standard_User | Add or remove findings on an existing submission |
| POST | `/api/ivanti/fp-workflow/submissions/:id/attachments` | Admin, Standard_User | Upload additional attachments (local files and/or `libraryDocIds`) to an existing submission |
| POST | `/api/ivanti/fp-workflow/submissions/:id/requeue` | Admin, Standard_User | Re-queue findings from a rejected submission into the todo queue under a new workflow type |
| GET | `/api/ivanti/archive` | Any | List archive records; optional filters: `state` (ACTIVE/ARCHIVED/RETURNED/CLOSED), `teams` (comma-separated BU names) |
| GET | `/api/ivanti/archive/anomalies` | Any | Sync anomaly log (significant count deltas and classification data) |
| GET | `/api/ivanti/archive/transitions/:archiveId` | Any | Transition history for a specific archive record |
| POST | `/api/compliance/preview` | Admin, Standard_User | Parse an xlsx upload, run drift check, and return drift report + diff + temp file path |
| POST | `/api/compliance/commit` | Admin, Standard_User | Commit a previewed upload to the database |
| POST | `/api/compliance/reconcile-config` | Admin | Auto-patch `compliance_config.json` to resolve breaking and silent-miss drift findings |
| POST | `/api/compliance/rollback/:uploadId` | Admin | Roll back the most recent upload (deletes new items, re-activates resolved items) |
| GET | `/api/compliance/uploads` | Any | List all compliance upload records |
| GET | `/api/compliance/summary` | Any | Metric health summary; `?team=STEAM` |
| GET | `/api/compliance/items` | Any | Device list; `?team=STEAM&status=active` |
| GET | `/api/compliance/items/:hostname` | Any | Full detail for a device (metrics + notes) |
| GET | `/api/compliance/notes/:hostname/:metricId` | Any | Notes for a specific hostname/metric |
| POST | `/api/compliance/notes` | Admin, Standard_User | Add a note for a hostname/metric; accepts `metric_ids` array for multi-metric notes |
| DELETE | `/api/compliance/notes/:id` | Admin, Standard_User | Delete a note by ID; `?group=true` deletes all notes sharing the same `group_id`. Author or Admin only. |
### Knowledge Base
| Method | Path | Group | Description |
|---|---|---|---|
| POST | `/api/knowledge-base/upload` | Admin, Standard_User | Upload a new knowledge base document |
| GET | `/api/knowledge-base` | Any | List all articles |
| GET | `/api/knowledge-base/:id` | Any | Get article metadata |
| GET | `/api/knowledge-base/:id/content` | Any | Get file content for inline display |
| GET | `/api/knowledge-base/:id/download` | Any | Download the file |
| DELETE | `/api/knowledge-base/:id` | Admin, Standard_User | Delete article and file (Standard_User: own articles only) |
### Archer Tickets
| Method | Path | Group | Description |
|---|---|---|---|
| GET | `/api/archer-tickets` | Any | List tickets; optional filters: `cve_id`, `vendor`, `status` |
| GET | `/api/archer-tickets/status-trend` | Any | Ticket counts by date and status for pipeline chart |
| POST | `/api/archer-tickets` | Admin, Standard_User | Create a new Archer ticket |
| PUT | `/api/archer-tickets/:id` | Admin, Standard_User | Update an Archer ticket |
| DELETE | `/api/archer-tickets/:id` | Admin, Standard_User | Delete an Archer ticket (ownership + compliance check for Standard_User) |
| POST | `/api/archer-templates/:id/clone` | Admin, Standard_User | Clone a template with new vendor/platform/model |
| GET | `/api/archer-templates/hierarchy/vendors` | Any | List distinct vendor names |
| GET | `/api/archer-templates/hierarchy/platforms` | Any | List platforms for a vendor; query: `vendor` |
| GET | `/api/archer-templates/hierarchy/models` | Any | List models for vendor+platform; query: `vendor`, `platform` |
### CARD Asset Ownership
| Method | Path | Group | Description |
|---|---|---|---|
| GET | `/api/card/status` | Any | Check if CARD API is configured |
| GET | `/api/card/teams` | Admin, Standard_User | List all CARD teams |
| GET | `/api/card/teams/:teamName/assets` | Admin, Standard_User | Paginated team assets by disposition |
| GET | `/api/card/owner/:assetId` | Admin, Standard_User | Get owner record for an asset |
| GET | `/api/card/owner-lookup/:ip` | Admin, Standard_User | Resolve IP to asset and return owner data; `?quick=1` for tooltip mode, `?hostId=N` for fast path |
| POST | `/api/card/owner/:assetId/confirm` | Admin, Standard_User | Direct confirm ownership (no queue item) |
| POST | `/api/card/owner/:assetId/decline` | Admin, Standard_User | Direct decline ownership (no queue item) |
| POST | `/api/card/owner/:assetId/redirect` | Admin, Standard_User | Direct redirect between teams (no queue item) |
| GET | `/api/card/asset-search/:hostId` | Admin, Standard_User | Search CARD by Ivanti Host ID (deep_search) |
| POST | `/api/card/enrich-batch` | Admin, Standard_User | Batch lookup IPs/host_ids for Granite loader fields (max 200) |
| POST | `/api/card/queue/:queueItemId/confirm` | Admin, Standard_User | Confirm ownership for a queue item |
| POST | `/api/card/queue/:queueItemId/decline` | Admin, Standard_User | Decline ownership for a queue item |
| POST | `/api/card/queue/:queueItemId/redirect` | Admin, Standard_User | Redirect ownership for a queue item |
### Atlas Action Plans
| Method | Path | Group | Description |
|---|---|---|---|
| GET | `/api/atlas/hosts/:hostId/plans` | Any | Get action plans for a host (from cache or API) |
| PUT | `/api/atlas/hosts/:hostId/plans` | Admin, Standard_User | Create a new action plan |
| PATCH | `/api/atlas/hosts/:hostId/plans` | Admin, Standard_User | Update an existing plan |
| POST | `/api/atlas/hosts/:hostId/refresh` | Admin, Standard_User | Force cache refresh from Atlas API |
All tables are defined in `backend/db-schema.sql` and created by `setup-postgres.js`. The database runs in a PostgreSQL 16 Docker container (`steam-postgres`) on port 5433.
**`knowledge_base`** — Document library entries with title, slug, category, description, file metadata, and `created_by`.
**`archer_tickets`** — Archer EXC exception tickets linked to CVE/vendor pairs. `UNIQUE(exc_number)`. Includes `created_by` for ownership tracking. Foreign key to `cves(cve_id, vendor)` with `ON DELETE CASCADE`.
**`jira_tickets`** — JIRA tickets linked to CVE/vendor pairs. Includes `created_by`. Foreign key to `cves(cve_id, vendor)` with `ON DELETE CASCADE`.
**`ivanti_sync_state`** — Single-row cache for Ivanti workflow batch data.
**`ivanti_findings`** — One row per Ivanti host finding. Indexed on `state`, `bu_ownership`, `severity`, and `(state, bu_ownership)`. Replaces the old single-row JSON blob with queryable individual rows. Includes `state` (`open`/`closed`), `workflow_id`, `workflow_state`, `note`, and `override_host_name`/`override_dns` columns.
**`ivanti_todo_queue`** — Personal per-user queue of findings staged for FP, Archer, CARD, GRANITE, DECOM, or Remediate processing. Keyed by `(user_id, finding_id)`. Workflow type constraint: `FP`, `Archer`, `CARD`, `GRANITE`, `DECOM`. Completed items can be redirected to a different workflow type via `POST /:id/redirect`, which creates a new pending item preserving the original finding data.
**`ivanti_fp_submissions`** — Record of FP workflow submissions to the Ivanti API. Tracks user, workflow batch ID, form fields, finding IDs, queue item IDs, attachment results, and submission status (success/partial/failed). Lifecycle status tracks the workflow through: submitted, approved, rejected, rework, resubmitted. Rejected submissions can be dismissed (`dismissed_at`) or re-queued to the todo queue under a different workflow type (`requeued_at`).
**`ivanti_fp_submission_history`** — Edit history for FP submissions. Tracks change_type (created, fields_updated, findings_added, attachments_added, status_changed) with change_details_json.
**`ivanti_finding_archives`** — Archived finding records with lifecycle state tracking. States: ARCHIVED, RETURNED, CLOSED, CLOSED_GONE. Tracks severity at time of archival and transition timestamps.
**`ivanti_archive_transitions`** — State transition history for archived findings. Records from_state, to_state, severity_at_transition, and reason for each transition.
**`ivanti_sync_anomaly_log`** — Sync anomaly detection log. Records count deltas, newly archived/returned counts, classification breakdown, and significance flag per sync.
**`ivanti_finding_bu_history`** — BU reassignment history per finding. Records previous_bu, new_bu, and detection timestamp.
**`ivanti_counts_history_by_bu`** — Per-BU historical open/closed counts, enabling per-BU trend lines on the findings chart.
**`atlas_action_plans_cache`** — Cached Atlas action plan data for badge rendering. Stores host_id, has_action_plan flag, plan_count, plans_json, and atlas_known flag. Indexed on host_id.
**`notifications`** — In-app notifications. Per-user notifications with type, title, message, issue_number, and read flag. Used by the NotificationBell component.
**`vcl_multi_vertical_summary`** — Per-metric summary data from VCL multi-vertical uploads. Stores metric_id, metric_desc, category, team, priority, non_compliant, compliant, total, compliance_pct, target, and status per upload per vertical. Used for executive reporting without recalculating from items.
**`compliance_snapshots`** — Monthly compliance snapshots per vertical. Used for trend charts and linear regression forecasting.
**`compliance_uploads`** — Record of each compliance xlsx upload: filename, report date, uploader, timestamp, and new/resolved/recurring counts.
**`compliance_items`** — One row per device/metric violation. Tracks hostname, IP, device type, team, metric ID, category, `extra_json` (all non-core xlsx columns), status (active/resolved), first seen upload, and times seen. Identity key: `(hostname, metric_id)`.
**`compliance_notes`** — Timestamped notes per hostname/metric. Multiple notes per combination are supported. `group_id` column links notes created in the same multi-metric submission. Foreign-key linked to compliance items.
### View
**`cve_document_status`** — Aggregates document counts per CVE/vendor and derives a `compliance_status` (`Complete` when an advisory is present, otherwise `Missing Required Docs`).
---
## Security Model
### Authentication
- Cookie-based sessions with `httpOnly: true`, `sameSite: lax`, `secure: true` (in production)
- Sessions expire after 24 hours
- Login rate-limited to 20 attempts per 15-minute window via `express-rate-limit`
-`SESSION_SECRET` is required — server refuses to start without it
### Group-based access control
Four groups with distinct permission boundaries enforced server-side via `requireGroup` middleware:
Standard_User delete restrictions are enforced at the API level: ownership check, finding state check, compliance linkage check, and cascade impact check for CVEs.
### File upload security
- Extension allowlist enforced by Multer; executables (`.exe`, `.js`, `.sh`, `.py`, `.bat`, etc.) are blocked
- MIME type prefix validation in addition to extension checking
- 10 MB per-file size limit
- Filenames are sanitized: path separators, `..` sequences, null bytes, and non-alphanumeric characters are removed
- Content-Disposition headers sanitize filenames to prevent header injection
### Path traversal prevention
-`sanitizePathSegment()` strips `/`, `\`, `..`, and null bytes from any value used in `path.join()`
-`isPathWithinUploads()` verifies resolved paths stay within the uploads root before any file operation
### Content security
- Knowledge base PDF iframe uses `sandbox="allow-same-origin"` to prevent script execution
- Markdown rendering uses `rehype-sanitize` to strip dangerous HTML
- CSP `frame-ancestors` header derived from `CORS_ORIGINS` environment variable
### Input validation
- CVE ID must match `/^CVE-\d{4}-\d{4,}$/`
- Severity must be one of: `Critical`, `High`, `Medium`, `Low`
- Status must be one of: `Open`, `Addressed`, `In Progress`, `Resolved`
- Archer EXC numbers must match `/^EXC-\d+$/`
- Finding override field must be one of: `hostName`, `dns`
- User group validated against: `Admin`, `Standard_User`, `Leadership`, `Read_Only` (enforced by DB triggers and app-level validation)
- Hostname format validated with `/^[a-zA-Z0-9._-]+$/` in compliance notes
> **Migrating from SQLite:** If this is the first upgrade after the Postgres migration, run `scripts/deploy-postgres.sh` instead of the manual steps above. It handles the full cutover including data migration. See [Postgres Migration Plan](docs/guides/postgres-migration-plan.md) for details.
> **Do not re-run `node setup.js`** on an existing deployment. The legacy SQLite setup script is retained for reference only. Use `setup-postgres.js` for schema initialization.
> **NODE_ENV reminder:** If you are running over plain HTTP (no TLS), make sure `NODE_ENV` is **not** set to `production` in `backend/.env`. See [Troubleshooting](#troubleshooting) for details.
> **Note:** The migration scripts in `backend/migrations/` are used for both PostgreSQL and legacy SQLite deployments. Run them via `node migrations/run-all.js` which executes all migrations in order. All are idempotent and safe to re-run.
For deployments upgrading from an older schema, the following legacy migration scripts are also available in `backend/`:
-`migrate_multivendor.js` — Adds multi-vendor support to an older single-vendor schema
-`migrate-audit-log.js` — Adds the `audit_logs` table to pre-auth deployments
-`migrate-to-1.1.js` — General 1.0 → 1.1 schema update
> Several columns (`fp_workflow_counts_json`, `fp_id_counts_json`, `seen_count`, `summary_json`) are added automatically via idempotent `ALTER TABLE` statements each time the server starts. No manual re-run is needed.
---
## Troubleshooting
### Login succeeds but all pages show "Error Loading" / 401 Unauthorized
**Symptom:** You can log in successfully, but the dashboard shows "Error Loading CVEs", "Failed to fetch", and the browser console shows 401 on every API call.
**Cause:** The session cookie has the `Secure` flag set (because `NODE_ENV=production` in `backend/.env`), but the application is being accessed over plain HTTP. Browsers silently refuse to send `Secure` cookies over non-HTTPS connections, so every request after login arrives without a session cookie.
**Fix:** Either:
1. Remove `NODE_ENV=production` from `backend/.env` (or set it to `development`) and restart the backend, **or**
2. Set up HTTPS (e.g., via nginx reverse proxy with TLS termination) and access the app over `https://`
### Login fails with "Too many login attempts"
**Cause:** The login endpoint is rate-limited to 20 attempts per 15-minute window. Wait 15 minutes or restart the backend to reset the counter.
### Server refuses to start: "SESSION_SECRET environment variable must be set"
**Fix:** Add a `SESSION_SECRET` to `backend/.env`:
