cve-dashboard/docs/kb-compliance-guide.md

# 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