chore: reorganize docs, document migrations, gitignore operational files for v1.0.0 release

docs/guides/kb-compliance-guide.md

@@ -0,0 +1,94 @@
+# AEO Compliance Tracking Guide
+
+## Overview
+
+The Compliance page tracks AEO security posture metrics for the STEAM and ACCESS-ENG teams. It processes weekly xlsx compliance reports, shows per-metric health cards, and tracks non-compliant devices down to the individual hostname level.
+
+## Teams Tracked
+
+Only two teams are monitored:
+- **STEAM** (NTS-AEO-STEAM)
+- **ACCESS-ENG** (NTS-AEO-ACCESS-ENG)
+
+## Uploading a Compliance Report
+
+### Prerequisites
+- You must have editor or admin access
+- The report must be an `.xlsx` file (the standard NTS_AEO compliance export)
+
+### Upload Process
+
+1. Navigate to the **Compliance** page
+2. Click the **Upload Report** button
+3. Drag and drop the xlsx file or click to browse
+4. The system parses the spreadsheet using a Python backend script and shows a **preview**:
+   - **New items**: Devices/metrics appearing for the first time
+   - **Recurring items**: Devices/metrics that were already non-compliant
+   - **Resolved items**: Previously non-compliant items no longer in the report
+5. Review the diff summary
+6. Click **Commit** to save the data
+
+The upload is a two-step process (preview then commit) so you can verify the data before it's written to the database.
+
+## Health Cards
+
+After uploading, the page displays metric health cards for each team. Each card shows:
+
+- **Metric ID** — the compliance metric identifier
+- **Category** — the metric category (Vulnerability Management, Access & MFA, Logging & Monitoring, etc.)
+- **Compliance %** — current compliance percentage
+- **Target** — the required target percentage
+- **Status** — color-coded:
+  - Green: Meets/Exceeds Target
+  - Amber: Within 15% of Target
+  - Red: Below 15% of Target
+
+Click a health card to filter the device list to that specific metric.
+
+## Metric Categories
+
+| Category | Color |
+|----------|-------|
+| Vulnerability Management | Red |
+| Access & MFA | Amber |
+| Logging & Monitoring | Purple |
+| End-of-Life OS | Orange |
+| Decommissioned Assets | Slate |
+| Asset Data Quality | Slate |
+| Application Security | Blue |
+| Disaster Recovery | Teal |
+| Endpoint Protection | Orange |
+
+## Device-Level Tracking
+
+Below the health cards, the device list shows non-compliant devices grouped by hostname. Each device entry shows:
+
+- Hostname and IP address
+- Device type and team assignment
+- Failing metrics with first-seen and last-seen dates
+- Seen count (how many consecutive reports the device has been non-compliant)
+
+### Device Detail Panel
+
+Click a device to open the detail panel showing:
+- All metrics the device is failing
+- Upload history (when the device first appeared, when it was last seen)
+- Per-metric notes with timestamps
+
+### Adding Notes
+
+You can add notes to one or more metrics on a device at once:
+1. Open the device detail panel
+2. Select the metrics the note applies to using the chip selector — click individual metric chips to toggle them, or use **Select All** / **Deselect All** for bulk selection
+3. Type your note and click send
+4. Notes are timestamped and attributed to the logged-in user
+
+When a note is submitted for multiple metrics, it appears as a single grouped entry in the notes history with all associated metric chips displayed together. Notes are useful for tracking remediation progress, vendor ticket numbers, or explaining why a device is non-compliant.
+
+## Data Flow
+
+1. Weekly xlsx report is uploaded through the dashboard
+2. Python parser extracts team metrics and non-compliant devices
+3. Diff is computed against existing data (new/recurring/resolved)
+4. On commit: new items are inserted, recurring items have their seen_count incremented, resolved items are marked with resolved_on date
+5. Health cards and device lists update automatically

docs/guides/kb-cve-tracking-guide.md

@@ -0,0 +1,104 @@
+# CVE Tracking & NVD Sync Spec
+
+## Overview
+
+The Home page (CVE Management) is where you track individual CVEs across vendors, store supporting documentation, and link Archer risk acceptance tickets. It serves as the reference library for all vulnerability research and evidence.
+
+## Adding a CVE
+
+1. Click "Add CVE" on the Home page
+2. Enter the **CVE ID** (format: CVE-YYYY-NNNNN, e.g., CVE-2024-6387)
+3. Click the NVD lookup button to auto-populate fields from the National Vulnerability Database:
+   - Description
+   - Severity (Critical, High, Medium, Low)
+   - Published date
+4. Select or type the **Vendor/Platform** (e.g., Cisco, Juniper, ADTRAN)
+5. Review and adjust any fields as needed
+6. Click Save
+
+### NVD Auto-Population
+
+The NVD lookup queries the NIST NVD 2.0 API and extracts:
+- English description
+- CVSS severity using a cascade: v3.1 → v3.0 → v2.0
+- Published date
+
+If the NVD API is rate-limited (429 response), wait a few seconds and try again. Having an NVD API key configured in the backend `.env` file increases the rate limit.
+
+## CVE Details
+
+Each CVE entry tracks:
+
+| Field | Description |
+|-------|-------------|
+| CVE ID | The CVE identifier (e.g., CVE-2024-6387) |
+| Vendor | The affected vendor/platform |
+| Severity | Critical, High, Medium, or Low |
+| Description | Vulnerability description (from NVD or manual entry) |
+| Published Date | When the CVE was published |
+| Status | Open, In Progress, Addressed, or Resolved |
+
+## Document Storage
+
+Each CVE/vendor pair can have supporting documents attached. These serve as evidence for FP workflows, Archer tickets, and audit purposes.
+
+### Uploading Documents
+1. Open a CVE entry
+2. Click "Upload Document"
+3. Select the file (max 10 MB)
+4. Documents are stored in `uploads/cves/{cveId}/{vendor}/` on the server
+
+### Document Types
+- **Advisory** — vendor security advisories
+- **Email** — vendor communications or support ticket responses
+- **Screenshot** — device screenshots showing version info
+- **Patch** — patch notes or release documentation
+- **Other** — any other supporting evidence
+
+### Why Store Documents Here?
+Documents uploaded to CVE entries can be reused across multiple FP workflows. When an FP expires and needs renewal, the evidence is already in the dashboard rather than having to track it down again.
+
+## Archer Ticket Tracking
+
+Archer risk acceptance tickets (EXC-XXXXX) are linked to CVE/vendor pairs.
+
+### Adding an Archer Ticket
+1. Open a CVE entry
+2. Click "Add Archer Ticket"
+3. Enter the EXC number (e.g., EXC-12345)
+4. Optionally add the Archer URL and status
+
+### EXC Badge Integration
+Once an EXC number is entered:
+- An EXC badge appears on the CVE card on the Home page
+- Clicking the badge navigates to the Reporting page pre-filtered to findings with that EXC number in their notes
+- The Action Coverage chart on the Reporting page classifies findings with EXC numbers as "Archer Exception"
+
+## Vendor Tracking
+
+CVEs can be tracked across multiple vendors. Each CVE/vendor combination is a separate entry, allowing you to:
+- Track different remediation statuses per vendor
+- Store vendor-specific documentation
+- Link different Archer tickets per vendor
+
+## Editing CVEs
+
+1. Click the edit icon on a CVE card
+2. Modify any fields
+3. Use the NVD lookup button to refresh data from NVD if needed
+4. Click Save
+
+## Quick Check
+
+The Quick Check feature on the Home page lets you look up a CVE ID without adding it to the database:
+1. Type a CVE ID in the Quick Check field
+2. Press Enter — the NVD data is fetched and displayed
+3. If you want to track it, click "Add CVE" to create an entry
+
+## Tips
+
+- Always upload screenshots and vendor advisories to the CVE entry before submitting an FP workflow — reviewers may ask for this evidence
+- Use the status field to track progress: Open → In Progress → Addressed → Resolved
+- Link Archer EXC numbers as soon as the ticket is created — this updates the Action Coverage chart immediately
+- The search bar on the Home page searches across CVE ID, vendor, and description
+- Filter by vendor or severity using the dropdowns to focus on specific areas

docs/guides/kb-fp-submission-editing-guide.md

@@ -0,0 +1,110 @@
+# FP Workflow Queue & Submission Editing Guide
+
+## Overview
+
+The STEAM Security Dashboard allows you to create, track, and edit False Positive (FP) workflow submissions directly from the Reporting Page. This guide covers the full workflow from adding findings to the queue through editing and resubmitting FP workflows.
+
+## Adding Findings to the Queue
+
+1. On the Reporting Page, select findings by clicking the checkboxes in the findings table
+2. Use Shift+Click to select a range of findings
+3. In the selection toolbar that appears, choose the workflow type (FP, Archer, or CARD)
+4. Enter the vendor name (not required for CARD)
+5. Click "Add to Queue"
+
+The findings will appear in the Ivanti Queue panel (click the "Queue" button in the top-right).
+
+## Creating an FP Workflow
+
+1. Open the Queue panel
+2. Select the pending FP items you want to submit using the checkboxes
+3. Click "Create FP Workflow" at the bottom of the panel
+4. Fill in the required fields:
+   - **Workflow Name**: Use the format `FP — CVE-XXXX-XXXX — Vendor` (e.g., `FP — CVE-2024-6387 — Cisco_STEAM`)
+   - **Reason / Justification**: Explain why these findings are false positives
+   - **Description** (optional): Additional context
+   - **Expiration Date**: Must be a future date
+   - **Scope Override**: Leave as "Authorized" for standard FP workflows
+5. Attach supporting files (screenshots, evidence) — up to 10 files, 10 MB each
+6. Click Submit
+
+The workflow is created in the Ivanti platform and the queue items are marked as complete.
+
+## Viewing Submissions
+
+Your FP submissions appear in the "Submissions" section at the bottom of the Queue panel. Each submission shows:
+- Workflow name
+- Ivanti batch ID
+- Lifecycle status badge (color-coded)
+- Finding count
+- Submission date
+
+Click any submission to open the Edit Modal.
+
+## Lifecycle Status
+
+Submissions go through these states:
+
+| Status | Color | Meaning |
+|--------|-------|---------|
+| Submitted | Sky Blue | Awaiting review |
+| Rework | Amber | Reviewer sent it back — action needed |
+| Rejected | Red | Reviewer denied the FP request |
+| Resubmitted | Sky Blue | Edited and sent back for review |
+| Approved | Green | FP accepted — no further action |
+
+The status badge automatically syncs with the Ivanti platform state when findings data is refreshed.
+
+## Editing an Existing Submission
+
+Open a submission from the Queue panel to access the Edit Modal with four tabs:
+
+### Details Tab
+- Edit the workflow name, reason, description, expiration date, and scope override
+- Click "Save Details" to push changes to the Ivanti platform
+- If the submission was in Rework or Rejected status, saving automatically changes it to Resubmitted
+
+### Findings Tab
+- View the current list of finding IDs mapped to this workflow
+- Add more findings from your pending FP queue items
+- Select the items to add and click "Add Findings"
+- Each finding is mapped individually to the Ivanti workflow
+
+### Attachments Tab
+- View files that were uploaded with the original submission
+- **Note**: Adding attachments to an existing workflow is not supported via the Ivanti API. To add more files, upload them directly in the Ivanti platform.
+
+### History Tab
+- View a chronological log of all changes made to the submission
+- Shows finding additions with the actual finding IDs
+- Displays Ivanti reviewer notes (rework feedback, approval notes) pulled directly from the Ivanti platform
+
+## Handling Rework Requests
+
+When a submission comes back for rework:
+
+1. Open the submission from the Queue panel — the status badge will show "Rework" (amber)
+2. Go to the **History** tab to read the reviewer's notes explaining what needs to change
+3. Common rework reasons:
+   - Need more screenshots showing remediation
+   - Need to verify specific software versions
+   - Missing evidence for some findings
+4. Go to the **Findings** tab to add any additional findings if needed
+5. Upload additional screenshots directly in the Ivanti platform (Attachments tab has a link)
+6. Go to the **Details** tab to update the reason/description if needed
+7. Click "Save Details" — the status automatically changes to Resubmitted
+
+## Changing Status Manually
+
+Use the status dropdown in the Edit Modal to manually change the lifecycle status. This is useful when:
+- You receive notification outside the dashboard that a submission was rejected
+- You want to mark a submission as approved after confirming in Ivanti
+
+**Note**: Approved submissions are locked and cannot be edited.
+
+## Tips
+
+- Always include enough screenshots per audit guidance (e.g., 10 screenshots for 20-50 findings)
+- Use the naming convention `FP — CVE-XXXX-XXXX — Vendor_Team` for easy identification
+- Check the FP Workflow Status donut chart on the Reporting Page for an overview of all your FP ticket states
+- The workflow column in the findings table shows the current Ivanti state for each finding

docs/guides/kb-ivanti-queue-guide.md

@@ -0,0 +1,89 @@
+# Ivanti Queue & Batch Operations Guide
+
+## Overview
+
+The Ivanti Queue is a personal staging area for batch-processing vulnerability findings. You select findings from the Reporting Page table, assign them a workflow type and vendor, and stage them in the queue. From there you can create FP workflows, track Archer exceptions, or manage CARD dispositions.
+
+## Workflow Types
+
+| Type | Color | Purpose | Vendor Required? |
+|------|-------|---------|-----------------|
+| FP | Amber | False Positive — finding is not actually a vulnerability | Yes |
+| Archer | Blue | Risk Acceptance — vulnerability exists but can't be patched | Yes |
+| CARD | Green | Asset disposition — device not owned by your BU | No |
+
+## Adding Findings to the Queue
+
+### Single Finding
+1. In the findings table, click the checkbox area on a row (not the checkbox itself — click the cell)
+2. A popover appears with:
+   - The finding ID
+   - Vendor/Platform input field (required for FP and Archer)
+   - Workflow type toggle (FP / Archer / CARD)
+3. Enter the vendor name and select the workflow type
+4. Click "Add to Queue"
+
+### Batch Add (Multiple Findings)
+1. Select multiple findings using checkboxes (Shift+Click for range selection)
+2. The selection toolbar appears at the top of the table
+3. Choose the workflow type (FP / Archer / CARD)
+4. Enter the vendor name (not needed for CARD)
+5. Click "Add to Queue" — all selected findings are added at once (up to 200 per batch)
+
+## The Queue Panel
+
+Click the **Queue** button (top right of the Reporting Page) to open the slide-out panel. The badge shows the count of pending items.
+
+### Layout
+- Items are grouped by vendor (alphabetically)
+- CARD items appear in their own green section at the top
+- Each item shows: finding ID, CVEs, hostname, IP address, and workflow type badge
+
+### Item Actions
+
+| Action | How |
+|--------|-----|
+| Mark complete | Click the green checkbox |
+| Mark pending | Uncheck the green checkbox |
+| Select for deletion | Click the red checkbox (left side) |
+| Delete selected | Click "Delete (N)" button in footer |
+| Clear all completed | Click "Clear Completed" button in footer |
+| Redirect workflow | Click the redirect arrow (↗) on completed items |
+
+### Redirect Feature
+
+When a finding is completed under one workflow type but needs to be processed under another:
+1. Complete the item first
+2. Click the redirect arrow (↗) icon
+3. Choose the new workflow type
+4. A new pending item is created with the same finding data but the new workflow type
+
+Example: You submitted an FP but it was rejected. You now need to open an Archer ticket instead. Complete the FP item, then redirect it to Archer.
+
+## Creating FP Workflows from the Queue
+
+1. Open the Queue panel
+2. Select pending FP items using the checkboxes
+3. Click "Create FP Workflow" in the footer (only enabled when FP items are selected)
+4. Fill in the workflow details (name, reason, description, expiration date)
+5. Attach supporting files (screenshots, evidence)
+6. Submit — the workflow is created in Ivanti and queue items are marked complete
+
+See the [FP Submission Editing Guide](kb-fp-submission-editing-guide.md) for details on editing submitted workflows.
+
+## FP Submissions Section
+
+Below the queue items, a "Submissions" section shows your previously submitted FP workflows with:
+- Workflow name and Ivanti batch ID
+- Lifecycle status badge (Submitted, Rework, Rejected, Resubmitted, Approved)
+- Finding count and submission date
+
+Click any submission to open the Edit Modal for viewing details, adding findings, or reading reviewer notes.
+
+## Tips
+
+- Group related findings by vendor before adding to the queue — this makes it easier to create batch FP workflows
+- Use CARD for findings on devices that belong to another team — no vendor entry needed
+- The queue is per-user — other team members can't see or modify your queue items
+- Completed items stay in the queue until you clear them, so you have a record of what was processed
+- Use the redirect feature when a workflow type needs to change after initial processing

docs/guides/kb-reporting-page-guide.md

@@ -0,0 +1,92 @@
+# Reporting Page Guide
+
+## Overview
+
+The Reporting Page is the primary operational page in the STEAM Security Dashboard. It provides a live view of all open Ivanti host findings with filtering, sorting, inline editing, metric charts, and export capabilities.
+
+## Getting Started
+
+1. Navigate to the Reporting page from the sidebar
+2. Click **Sync** (top right) to pull the latest findings from Ivanti
+3. The sync timestamp updates when complete — findings, charts, and counts all refresh together
+
+## Metric Charts
+
+Four donut charts appear at the top of the page:
+
+### Open vs Closed
+Shows the total count of open and closed findings across all synced data.
+
+### Action Coverage
+Breaks down open findings into three categories:
+- **FP Request** (blue) — findings with an FP workflow ticket in Ivanti
+- **Archer Exception** (amber) — findings with an EXC-XXXXX number in their notes
+- **Pending** (red) — findings with no action taken yet
+
+Click a chart segment to filter the table to that category. Click again or use "clear filter" to remove.
+
+### FP Finding Status
+Shows the distribution of findings across FP workflow states (Requested, Reworked, Actionable, Approved, Rejected, Expired).
+
+### FP Workflow Status
+Shows the count of unique FP ticket IDs per state — one FP ticket can cover many findings.
+
+## Findings Table
+
+### Columns
+The table has 13 columns. All are visible by default:
+
+| Column | Description |
+|--------|-------------|
+| Finding ID | Ivanti host finding identifier |
+| Severity | VRR score with severity group (Critical, High, Medium) |
+| Title | Vulnerability title |
+| CVEs | Associated CVE identifiers (hover for tooltip details) |
+| Host | Hostname (inline editable) |
+| IP Address | Device IP |
+| DNS | DNS name (inline editable) |
+| Due Date | SLA deadline — red if overdue, amber if within 30 days |
+| SLA | SLA status (Overdue, At Risk, Within SLA) |
+| BU | Business unit ownership (STEAM or ACCESS-ENG) |
+| Workflow | FP workflow badge showing ticket ID and state |
+| Last Found | Date the finding was last detected by scanner |
+| Notes | Free-text notes field (inline editable) |
+
+### Column Management
+Click the **Columns** button (gear icon) to:
+- Show/hide columns by clicking the eye icon
+- Drag columns to reorder them
+- Your column configuration is saved in your browser
+
+### Sorting
+Click any sortable column header to sort. Click again to reverse direction. The active sort column is highlighted in blue.
+
+### Filtering
+Click the filter icon on any filterable column header to open a dropdown with all unique values. Check/uncheck values to filter. Use "Select All" or "Clear" for bulk operations. A search box lets you find specific values quickly.
+
+Active filters show as amber badges above the table. Click "Clear Filters" to remove all column filters at once.
+
+### Inline Editing
+
+Three columns support inline editing:
+
+- **Host**: Click the hostname to edit. An amber dot appears when an override is active. Click the revert button (↻) to restore the original Ivanti value. Overrides survive re-syncs.
+- **DNS**: Same behavior as Host.
+- **Notes**: Click to type. Saves automatically on blur. Use notes to record EXC numbers (e.g., `EXC-12345`) — the Action Coverage chart will classify these as "Archer Exception".
+
+## Selecting Findings
+
+Check the checkbox on any row to select it. Use Shift+Click for range selection. The "select all" checkbox in the header selects all visible (non-queued) findings.
+
+When findings are selected, a toolbar appears with:
+- Workflow type toggle (FP / Archer / CARD)
+- Vendor input field (not needed for CARD)
+- "Add to Queue" button to stage findings for batch processing
+
+## Export
+
+Click the **Export** dropdown to download the current filtered/sorted view as:
+- **CSV** — comma-separated values with UTF-8 BOM
+- **Excel (.xlsx)** — formatted spreadsheet with auto-fit column widths
+
+Only visible columns are included in the export.

docs/guides/kb-user-management-guide.md

@@ -0,0 +1,106 @@
+# User Management & Roles Guide
+
+## Overview
+
+The STEAM Security Dashboard uses role-based access control with four user groups. Only administrators can manage users. All user operations are logged in the audit trail.
+
+## User Groups
+
+| Group | Access Level | Description |
+|-------|-------------|-------------|
+| Admin | Full access | All operations including user management, delete, audit log |
+| Standard_User | Operational access | Create, edit, limited delete (own resources only), exports |
+| Leadership | Read-only + exports | View all data, download CSV/XLSX exports |
+| Read_Only | View only | Read-only access to all pages, no modifications |
+
+## Permission Matrix
+
+| Action | Admin | Standard_User | Leadership | Read_Only |
+|--------|-------|---------------|------------|-----------|
+| View findings/CVEs | Yes | Yes | Yes | Yes |
+| Sync Ivanti data | Yes | Yes | No | No |
+| Edit hostname/DNS overrides | Yes | Yes | No | No |
+| Edit notes | Yes | Yes | No | No |
+| Add to queue | Yes | Yes | No | No |
+| Create FP workflows | Yes | Yes | No | No |
+| Edit FP submissions | Yes | Yes | No | No |
+| Upload compliance reports | Yes | Yes | No | No |
+| Add CVEs | Yes | Yes | No | No |
+| Upload documents | Yes | Yes | No | No |
+| Export CSV/XLSX | Yes | Yes | Yes | No |
+| Delete CVEs/documents | Yes | Own only | No | No |
+| Manage users | Yes | No | No | No |
+| View audit log | Yes | No | No | No |
+
+## Managing Users (Admin Only)
+
+### Accessing User Management
+1. Click the user icon in the top navigation bar
+2. Select "User Management" from the menu
+3. The user list shows all accounts with their group, status, and last login
+
+### Creating a New User
+1. Click "Add User"
+2. Fill in the required fields:
+   - **Username** — must be unique
+   - **Email** — user's email address
+   - **Password** — initial password (user should change on first login)
+   - **Group** — select from Admin, Standard_User, Leadership, or Read_Only
+3. Click Save
+
+New users default to Read_Only if no group is specified.
+
+### Editing a User
+1. Click the edit icon on the user row
+2. Modify username, email, or group
+3. Optionally set a new password (leave blank to keep current)
+4. Click Save
+
+### Changing User Groups
+When changing a user's group, a confirmation dialog appears. Extra warnings are shown when:
+- Removing Admin privileges from a user
+- Upgrading a user to Admin
+
+Group changes are logged separately in the audit trail with the previous and new group recorded.
+
+### Deactivating Users
+Users can be deactivated rather than deleted. Deactivated users cannot log in but their data and audit history are preserved.
+
+## Authentication
+
+- Sessions use httpOnly cookies with 24-hour expiry
+- Passwords are hashed with bcryptjs
+- All API endpoints (except login) require a valid session
+- Failed login attempts are not rate-limited at the application level
+
+## Audit Log
+
+The audit log records all significant actions in the dashboard. Only admins can view it.
+
+### What's Logged
+- User creation, updates, group changes, deletion
+- CVE creation, updates, deletion
+- Document uploads and deletions
+- Ivanti sync operations
+- FP workflow submissions and edits
+- Queue operations
+- Compliance uploads
+- Login/logout events
+
+### Audit Entry Fields
+Each entry includes:
+- Timestamp
+- User who performed the action
+- Action type (e.g., user_create, ivanti_fp_workflow_created)
+- Entity type and ID
+- Details (JSON with specifics of what changed)
+- IP address
+
+## Default Admin Account
+
+On first setup (`node setup.js`), a default admin account is created:
+- Username: `admin`
+- Password: set during setup
+- Group: `Admin`
+
+Change the default password immediately after first login.

docs/guides/python-venv-setup.md

@@ -0,0 +1,73 @@
+# Python Dependencies — Compliance xlsx Parsing
+
+`parse_compliance_xlsx.py` requires `pandas` and `openpyxl`. This doc
+explains how each server has (or should have) these installed.
+
+---
+
+## Dev server — how it works
+
+Pandas and openpyxl are installed as **system apt packages**, not via pip
+or a venv. This is why there is no venv on dev and no `--break-system-packages`
+gymnastics. They were installed at some point via:
+
+```bash
+apt install python3-pandas python3-openpyxl
+```
+
+You can verify with:
+
+```bash
+python3 -c "import pandas; print(pandas.__file__)"
+# /usr/lib/python3/dist-packages/pandas/__init__.py  ← apt-managed
+```
+
+---
+
+## Production server — how to fix it
+
+Production was missing pandas entirely. The fix mirrors what dev has:
+
+```bash
+apt-get update --fix-missing
+apt install -y python3-pandas python3-openpyxl
+```
+
+No venv, no pip, no `PYTHON_BIN` env var needed. After installing, restart
+the backend and the compliance xlsx upload will work.
+
+---
+
+## If apt packages are unavailable (fallback)
+
+If you're on a system where apt doesn't have pandas (unlikely on Ubuntu
+22.04/24.04), or you want isolation, use a venv:
+
+```bash
+apt install -y python3-venv python3-full
+python3 -m venv /home/cve-dashboard/venv
+/home/cve-dashboard/venv/bin/pip install -r /home/cve-dashboard/backend/scripts/requirements.txt
+```
+
+Then set `PYTHON_BIN` in the Node backend's environment:
+
+```bash
+export PYTHON_BIN=/home/cve-dashboard/venv/bin/python3
+```
+
+The backend reads `process.env.PYTHON_BIN` and falls back to `python3` if
+not set, so this only needs to be done if you're using a venv.
+
+---
+
+## Why pip3 may fail on modern Ubuntu/Debian
+
+PEP 668 (enforced in Ubuntu 23.04+) blocks `pip3 install` system-wide to
+prevent breaking apt-managed packages. The error looks like:
+
+```
+error: externally-managed-environment
+```
+
+Using `apt install python3-pandas` is the correct solution — pip is not
+needed when the distro packages the library directly.

docs/guides/team-training-agenda.md

@@ -0,0 +1,158 @@
+# STEAM Security Dashboard — Team Training Agenda
+
+**Session length:** 30–40 minutes
+**Format:** Live walkthrough (share your screen on the dashboard)
+**Reference docs:** `security-posture-workflow.md` for full detail on anything covered here
+
+---
+
+## Pre-meeting prep
+
+- Have the dashboard open and logged in before the meeting starts
+- Sync Vulnerability Triage page so data is fresh when you get there
+- Print or share `security-posture-workflow.md` as a take-home reference
+
+---
+
+## Segment 1 — Why this tool exists (3 min)
+
+**Talking points:**
+- We have open Ivanti findings in the 8.5–9.9 VRR range — these are the ones we own and are accountable for
+- Every finding needs a documented action within **60 days of detection** (the SLA rule)
+- Findings that age past their Due Date make a device non-compliant in AEO posture reporting
+- This dashboard is how we track, triage, and prove we've actioned everything — replaces manual spreadsheet tracking
+
+---
+
+## Segment 2 — Dashboard orientation (4 min)
+
+**Show on screen:** Navigate through each page in the nav drawer
+
+- **Home (CVE Management)** — our CVE research library; this is where we store screenshots, advisories, and Archer EXC numbers against each CVE/vendor pair
+- **Vulnerability Triage (Host Findings)** — the daily operational page; this is where you spend most of your time
+- **Compliance** — AEO posture data uploaded from the NTS_AEO xlsx; shows metric health per team
+- **Knowledge Base** — internal docs, runbooks, advisories
+- **Exports** — bulk data extracts when needed
+
+> Tell the team: *"The Vulnerability Triage page is what we'll focus on today — that's where the workflow lives."*
+
+---
+
+## Segment 3 — The three things you can do with a finding (5 min)
+
+**Talking points — before showing the table, set context:**
+
+Every finding in our range gets one of three designations:
+
+1. **Remediation** — you fix the root cause
+   - Firmware/software upgrade → no ticket needed, finding drops off on next scan
+   - Configuration change → **Archer EXC ticket required** (if the config is ever rolled back, the vulnerability comes back — the ticket documents that we know)
+
+2. **False Positive (FP)** — the scanner flagged something that doesn't actually apply to our platform or version
+   - Requires an FP workflow opened in Ivanti
+   - Evidence requirements: (a) **screenshot from the device** showing hostname, IP, and SW version — CLI text is not accepted; (b) vendor documentation (advisory, email, support ticket) confirming it doesn't affect us
+   - Upload evidence to the CVE database on the Home page so we can reuse it when the FP expires
+
+3. **Risk Acceptance (Archer EXC)** — we can't patch, for a documented reason
+   - Vendor hasn't released a patch yet
+   - Device is EOL/EOS — needs mitigation steps + remediation plan in the ticket
+   - Business constraint — needs justification and compensating controls
+   - Format: enter `EXC-XXXXX` in the finding's Notes cell after the ticket is created
+
+> Tell the team: *"Knowing which path you're on before you touch the dashboard makes triage fast. The workflow is just deciding which of these three it is."*
+
+---
+
+## Segment 4 — The 5-step workflow on the Vulnerability Triage page (15 min)
+
+**Show on screen:** Vulnerability Triage page, live walkthrough on a real finding
+
+### Step 1 — Sync and sort (1 min)
+- Click **Sync** top-right, wait for timestamp to update
+- Click **Due Date** column to sort ascending — reds first, then ambers
+- Red = overdue, Amber = due within 30 days — work these first
+
+### Step 2 — Identify the host (3 min)
+- Use the **IP address** in the row to verify the hostname in Infoblox (preferred) or IPControl
+- If Ivanti has a stale hostname: click the **Host cell** directly in the table — it's inline editable
+- An amber dot appears on overridden cells; original value is preserved and can be restored
+- Show the revert button (↻) so they know corrections aren't permanent unless they want them to be
+
+### Step 3 — Check who owns the asset (2 min)
+- Look at the **BU column**
+- If it's `NTS-AEO-STEAM` or `NTS-AEO-ACCESS-ENG` → our team, continue
+- Anything else (or blank) → not ours → **CARD queue**
+  - Check the row checkbox, select CARD, click Add to Queue
+  - IP address is captured automatically for the CARD search
+  - Process CARD items in a separate session
+
+### Step 4 — Look up the CVEs (4 min)
+- Each row shows up to 2 CVEs; hover the **+N badge** to see more
+- Go to Home page, search for the CVE ID
+  - If it exists → review existing notes, docs, and any EXC numbers already linked
+  - If not → click **Add CVE**, enter the CVE ID, NVD auto-fill populates the rest
+- Research: vendor advisory portal (Juniper PSN, Cisco Bug Search) — determine if it's an FP, can be patched, or needs an Archer ticket
+
+### Step 5 — Take action (5 min)
+- **Patch available (firmware/SW)** — plan the upgrade, add a note to the finding row, done
+- **Config change only** — checkbox → Vendor → select **Archer** → Add to Queue → process in Ivanti later
+- **False Positive** — collect screenshot + vendor doc, upload to Home page CVE entry, then checkbox → Vendor → select **FP** → Add to Queue → submit FP in Ivanti in a separate session
+- **Can't patch (Archer)** — same as config change path; once EXC number is issued, paste it into the finding's **Notes cell** (`EXC-XXXXX` format)
+
+---
+
+## Segment 5 — The Ivanti Queue (5 min)
+
+**Show on screen:** Click the Queue button, show the panel
+
+- **Purpose:** tag findings as you triage, then batch all the Ivanti / Archer work in one focused session instead of context-switching constantly
+- Three types: **FP** (amber), **Archer** (sky blue), **CARD** (green)
+- CARD items show the IP address so you can search directly in CARD
+- Check the green checkbox on an item when the Ivanti/Archer action is done
+- Multi-select delete: check the small red boxes, click **Delete (N)** in the footer
+- Queue is **personal to your login** — each person has their own; it persists across sessions
+
+---
+
+## Segment 6 — Workflow badge colours (3 min)
+
+**Show on screen:** Workflow column on the Vulnerability Triage table
+
+Quick rule: **red = act now, amber = act soon, blue = monitor, no badge = needs triage**
+
+| Badge | What it means | What to do |
+|---|---|---|
+| Red — Expired | FP ticket lapsed, finding re-opened | Submit a new FP in Ivanti |
+| Red — Rejected | Security team denied the FP | Remediate — do not resubmit without new evidence |
+| Amber — Reworked | Reviewer returned the ticket | Open in Ivanti, update justification, resubmit |
+| Amber — Actionable | Ticket flagged for team response | Open in Ivanti and respond |
+| Blue — Requested | FP submitted, awaiting approval | Monitor; follow up if SLA is approaching |
+| No badge | Never been triaged | Run it through the 5-step workflow |
+
+---
+
+## Segment 7 — Quick tips (2 min)
+
+Quick features worth pointing out before Q&A:
+
+- **Filter to untriaged only** — click the **Pending** segment on the Action Coverage donut chart
+- **Find all findings tied to an Archer ticket** — click the EXC badge on the Home page CVE row
+- **Filter by vendor, IP, SLA status** — click the filter icon (⊙) on any column header
+- **Save evidence once, reuse it** — uploading screenshots/advisories to the CVE database means when an FP expires you already have the files
+
+---
+
+## Segment 8 — Q&A (remaining time)
+
+Suggested prompts to open discussion if no questions come up:
+- *"Walk me through what you'd do if you saw a red 'Rejected' badge on a finding."*
+- *"When would you use the Ivanti Queue versus just actioning something immediately?"*
+- *"What's the difference between Path B (config change) and Path D (risk acceptance) — when does each apply?"*
+
+---
+
+## Takeaway for the team
+
+Point them to:
+- `docs/security-posture-workflow.md` — the full process guide with all the steps, evidence requirements, and decision matrix
+- `docs/security-posture-workflow-diagrams.md` — the Mermaid flowcharts if they're visual learners

docs/guides/time-based-reporting-recommendations.md

@@ -0,0 +1,333 @@
+# Time-Based Reporting Recommendations
+**Date:** 2026-04-02
+**Author:** Engineering (Claude Code)
+**Status:** Draft — for director review
+
+---
+
+## Executive Summary
+
+This document analyzes the current CVE Dashboard data model and recommends a set of time-based visualizations that can be added to the Reporting page. Recommendations are grouped by feasibility: **Tier 1** can be built with data already in the database, **Tier 2** requires a lightweight new tracking table, and **Tier 3** requires structural additions.
+
+---
+
+## Current Data Inventory
+
+### What Already Has Time-Series History
+
+| Source | Table | Date Fields | History? |
+|--------|-------|-------------|----------|
+| Compliance uploads | `compliance_uploads` | `report_date`, `uploaded_at` | **Yes** — one row per report cycle |
+| Compliance items | `compliance_items` | `created_at`, `first_seen_upload_id`, `resolved_upload_id` | **Yes** — tracks lifecycle |
+| Archer tickets | `archer_tickets` | `created_at`, `updated_at` | **Yes** — full history |
+| Todo queue | `ivanti_todo_queue` | `created_at`, `updated_at` | **Yes** — by action |
+| Finding notes | `ivanti_finding_notes` | `updated_at` | **Yes** — note activity |
+
+### What Is Point-in-Time Only (no history yet)
+
+| Source | Table | Problem |
+|--------|-------|---------|
+| Ivanti findings | `ivanti_findings_cache` | Single-row cache — overwritten on every sync |
+| Ivanti counts | `ivanti_counts_cache` | Single-row cache — no snapshots stored |
+| FP workflow states | Computed from `findings_json` | Ephemeral — not persisted historically |
+
+---
+
+## Tier 1 Recommendations — Build Now (No Schema Changes)
+
+All of these use data that is already in the database.
+
+---
+
+### 1.1 Compliance Trend Line — Total Active Findings Over Time
+
+**Description:** A line chart showing the total number of active (non-compliant) items per compliance upload date. This directly answers "are we improving over time?"
+
+**Data Source:**
+```sql
+SELECT
+  cu.report_date,
+  COUNT(ci.id) AS active_count
+FROM compliance_uploads cu
+JOIN compliance_items ci ON ci.upload_id = cu.id AND ci.status = 'active'
+GROUP BY cu.id
+ORDER BY cu.report_date ASC;
+```
+
+**Chart Type:** Line chart with data points per upload
+**Axes:** X = Report Date, Y = Number of Active Findings
+**Value-add:** Overlay a trend line (linear regression) to show trajectory
+
+---
+
+### 1.2 New / Recurring / Resolved Bar Chart — Per Report Cycle
+
+**Description:** A grouped or stacked bar chart showing the delta breakdown for each compliance upload: how many findings were newly introduced, how many recurred from a prior cycle, and how many were resolved.
+
+**Data Source:** Already computed and stored in `compliance_uploads`:
+```sql
+SELECT report_date, new_count, recurring_count, resolved_count
+FROM compliance_uploads
+ORDER BY report_date ASC;
+```
+
+**Chart Type:** Stacked bar chart (one bar per upload date)
+**Legend:** New (red/amber), Recurring (yellow), Resolved (green)
+**Value-add:** Shows whether each reporting cycle is improving (more resolved than new) or degrading
+
+---
+
+### 1.3 Team Compliance Health Over Time — Multi-Line Chart
+
+**Description:** A multi-line chart showing the active finding count per team per upload date. Answers "which team is trending better or worse?"
+
+**Data Source:**
+```sql
+SELECT
+  cu.report_date,
+  ci.team,
+  COUNT(ci.id) AS active_count
+FROM compliance_uploads cu
+JOIN compliance_items ci ON ci.upload_id = cu.id AND ci.status = 'active'
+GROUP BY cu.id, ci.team
+ORDER BY cu.report_date ASC;
+```
+
+**Chart Type:** Multi-line chart (one line per team)
+**Teams:** STEAM, ACCESS-ENG, ACCESS-OPS, INTELDEV
+**Value-add:** Immediately visible which team is outlier or improving fastest
+
+---
+
+### 1.4 Mean Time to Resolution (MTTR) — Per Team
+
+**Description:** A bar chart showing average number of upload cycles between when a finding first appeared and when it was resolved, broken out by team.
+
+**Data Source:**
+```sql
+SELECT
+  ci.team,
+  AVG(ci.resolved_upload_id - ci.first_seen_upload_id) AS avg_cycles_to_resolve,
+  COUNT(*) AS resolved_count
+FROM compliance_items ci
+WHERE ci.resolved_upload_id IS NOT NULL
+GROUP BY ci.team;
+```
+
+**Chart Type:** Horizontal bar chart
+**Axes:** Y = Team, X = Average Cycles to Resolution
+**Value-add:** Normalize to calendar days by joining with upload dates for true MTTR in days
+
+---
+
+### 1.5 Recurring Findings Heatmap — Seen Count Distribution
+
+**Description:** A heatmap or bubble chart showing findings grouped by how many times they have recurred (`seen_count`). Identifies chronic, long-standing compliance gaps.
+
+**Data Source:**
+```sql
+SELECT
+  team,
+  metric_id,
+  metric_desc,
+  seen_count,
+  COUNT(*) AS host_count
+FROM compliance_items
+WHERE status = 'active'
+GROUP BY team, metric_id
+ORDER BY seen_count DESC;
+```
+
+**Chart Type:** Horizontal bar chart sorted by `seen_count`, grouped by team
+**Value-add:** Highlights the "chronic" findings that repeatedly appear — high priority for remediation
+
+---
+
+### 1.6 Archer Exception Ticket Status Over Time
+
+**Description:** A line chart or cumulative area chart showing Archer ticket status transitions over time using `created_at` and `updated_at`.
+
+**Data Source:**
+```sql
+SELECT
+  DATE(created_at) AS date,
+  status,
+  COUNT(*) AS count
+FROM archer_tickets
+GROUP BY DATE(created_at), status
+ORDER BY date ASC;
+```
+
+**Chart Type:** Stacked area chart
+**Statuses:** Draft, Open, Under Review, Accepted
+**Value-add:** Tracks exception request pipeline velocity — are exceptions getting processed or stacking up?
+
+---
+
+### 1.7 Compliance Category Breakdown Over Time
+
+**Description:** A stacked area chart showing what categories of compliance failures are driving the total over time (if the `category` field in `compliance_items` is populated).
+
+**Data Source:**
+```sql
+SELECT
+  cu.report_date,
+  ci.category,
+  COUNT(ci.id) AS count
+FROM compliance_uploads cu
+JOIN compliance_items ci ON ci.upload_id = cu.id AND ci.status = 'active'
+WHERE ci.category IS NOT NULL
+GROUP BY cu.id, ci.category
+ORDER BY cu.report_date ASC;
+```
+
+**Chart Type:** Stacked area chart
+**Value-add:** Shows whether one category dominates or if failures are spread across areas
+
+---
+
+## Tier 2 Recommendations — Lightweight Schema Addition Required
+
+These require adding one new table to persist snapshots of data that is currently overwritten on each sync.
+
+---
+
+### 2.1 Ivanti Findings Count Over Time — Open vs Closed Trend
+
+**Description:** The single most-requested metric: "are we making progress on vulnerabilities?" A line chart showing open and closed Ivanti finding counts over time.
+
+**Problem:** The current `ivanti_counts_cache` is a single-row table overwritten on each sync. No history is kept.
+
+**Solution:** Add a `ivanti_counts_history` table and append a row on every successful sync:
+```sql
+CREATE TABLE ivanti_counts_history (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  open_count  INTEGER NOT NULL,
+  closed_count INTEGER NOT NULL,
+  recorded_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+**Backend change:** In the sync route (`POST /api/ivanti/findings/sync`), after updating the cache, also `INSERT INTO ivanti_counts_history`.
+
+**New API endpoint:** `GET /api/ivanti/findings/counts/history`
+```sql
+SELECT open_count, closed_count, recorded_at
+FROM ivanti_counts_history
+ORDER BY recorded_at ASC;
+```
+
+**Chart Type:** Dual-line chart
+**Lines:** Open findings (red), Closed findings (green)
+**Value-add:** Most direct measure of vulnerability remediation velocity
+
+---
+
+### 2.2 FP Workflow State Snapshots Over Time
+
+**Description:** A stacked area or line chart showing how FP workflow states (Actionable, Requested, Approved, Rejected, Expired) trend over sync cycles.
+
+**Solution:** Add a `ivanti_fp_workflow_history` table:
+```sql
+CREATE TABLE ivanti_fp_workflow_history (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  state           TEXT NOT NULL,
+  finding_count   INTEGER NOT NULL DEFAULT 0,
+  id_count        INTEGER NOT NULL DEFAULT 0,
+  recorded_at     DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+**Chart Type:** Stacked area chart
+**Value-add:** Shows whether FP requests are being worked through or stacking up in "Requested" state
+
+---
+
+### 2.3 Todo Queue Velocity — Items Added vs Completed Per Week
+
+**Description:** A bar chart showing weekly queue throughput (items added vs items marked complete).
+
+**Data Source:** Already available in `ivanti_todo_queue.created_at` and `updated_at` + `status = 'complete'`:
+```sql
+SELECT
+  STRFTIME('%Y-W%W', created_at) AS week,
+  COUNT(*) AS items_added,
+  SUM(CASE WHEN status = 'complete' THEN 1 ELSE 0 END) AS items_completed
+FROM ivanti_todo_queue
+GROUP BY week
+ORDER BY week ASC;
+```
+
+**Chart Type:** Grouped bar chart (weekly)
+**Value-add:** Measures operational pace of the team's workflow action throughput
+
+---
+
+## Tier 3 Recommendations — Structural Additions (Future Consideration)
+
+These require more significant changes but would provide powerful long-term reporting.
+
+---
+
+### 3.1 Finding Age / Dwell Time Distribution
+
+**Description:** A histogram showing how long open findings have been open (age in days). The `lastFoundOn` field exists in the Ivanti findings JSON but is not persisted to a structured table.
+
+**Requirement:** Parse and store `lastFoundOn` from findings JSON into a structured column during sync.
+
+**Value-add:** Highlights findings that have been open for 90+ days — high-priority remediation targets.
+
+---
+
+### 3.2 SLA Breach Trends
+
+**Description:** Track how many findings breach SLA (Due Date exceeded) over time. Currently SLA status is computed in the frontend on-the-fly.
+
+**Requirement:** Add SLA breach tracking during sync — stamp findings that cross SLA date.
+
+**Value-add:** Compliance and audit reporting for SLA adherence metrics.
+
+---
+
+## Recommended Implementation Order
+
+| Priority | Chart | Effort | Impact |
+|----------|-------|--------|--------|
+| 1 | 1.2 — New/Recurring/Resolved bar chart | Low (data ready) | High |
+| 2 | 1.1 — Compliance trend line | Low (data ready) | High |
+| 3 | 1.3 — Team health multi-line | Low (data ready) | High |
+| 4 | 2.1 — Ivanti open/closed history | Medium (new table) | Very High |
+| 5 | 1.4 — MTTR per team | Low (data ready) | Medium |
+| 6 | 1.6 — Archer ticket pipeline | Low (data ready) | Medium |
+| 7 | 2.3 — Queue velocity | Low (data ready) | Medium |
+| 8 | 1.5 — Recurring findings heatmap | Low (data ready) | Medium |
+| 9 | 2.2 — FP workflow snapshots | Medium (new table) | Medium |
+| 10 | 1.7 — Category breakdown | Low (data ready) | Low–Medium |
+
+---
+
+## Charting Library Consideration
+
+The current implementation uses **hand-rolled SVG donut charts** (no external library). For time-series line/bar/area charts, the team should decide:
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **Continue hand-rolled SVG** | Zero dependencies, full style control | Significant effort for axes, labels, tooltips |
+| **Recharts** (React-native) | Well-matched to React 19, composable, responsive | ~500KB dependency |
+| **Chart.js via react-chartjs-2** | Mature, widely documented | Less React-idiomatic |
+| **Lightweight: uPlot or Chart.xkcd** | Very small bundle | Less community support |
+
+**Recommendation:** Recharts aligns best with the React 19 stack and allows declaring charts as JSX components consistent with the existing code style. It supports all chart types listed above.
+
+---
+
+## Notes for Director Review
+
+- All **Tier 1** recommendations can be implemented with zero database migrations — the data is already there.
+- The **single highest-value addition** is `2.1 — Ivanti open/closed count history`, as it captures the most direct remediation progress metric. It only requires one new table and one line added to the sync handler.
+- **Compliance charts (1.1–1.5)** will only be meaningful once multiple compliance uploads have been committed. If only 1–2 uploads exist currently, the trend will not show much until more data accumulates — but building the charts now means data will automatically populate them.
+- All queries listed above have been validated against the actual database schema.
+
+---
+
+*Next step: Review with director, confirm priority order, then schedule sprint for implementation.*