docs: add knowledge base guides for reporting, compliance, queue operations, user management, and CVE tracking

docs/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 any device/metric combination:
+1. Open the device detail panel
+2. Find the metric you want to annotate
+3. Type your note and save
+4. Notes are timestamped and attributed to the logged-in user
+
+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/kb-cve-tracking-guide.md

@@ -0,0 +1,104 @@
+# CVE Tracking & NVD Sync Guide
+
+## 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/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/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/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.