# VCL Executive Reporting — How It Works

## Overview

The VCL (Vulnerability Compliance Level) Report page generates an executive-level compliance summary from device-level data already tracked in the STEAM Security Dashboard. It aggregates individual device findings into team-level metrics, burndown projections, and compliance percentages — the same data leadership uses in the VCL deck for quarterly reporting.

The report is not a separate data source. It reads from the same `compliance_items` table that the AEO Compliance page uses. The difference is the view: Compliance shows device-level detail, VCL shows team-level aggregation.

---

## Metrics Explained

### Stats Bar

| Metric | What It Means | What Feeds It |
|---|---|---|
| Total Devices | Count of unique hostnames across all compliance items (active + resolved) | Weekly compliance xlsx upload |
| In-Scope | Same as Total Devices (all tracked devices are considered in-scope) | Weekly compliance xlsx upload |
| Compliant | Devices with NO active findings (all their findings are resolved) | Compliance upload resolves findings when devices drop off the report |
| Non-Compliant | Devices with at least one active finding | Compliance upload adds new findings; devices stay non-compliant until all findings resolve |
| Remediations Required | Same as Non-Compliant (each non-compliant device needs remediation) | Same as Non-Compliant |
| Current % | `(Compliant / In-Scope) * 100`, rounded to whole number | Computed from the counts above |
| Target % | Organization-defined compliance target (default 95%) | Set via `VCL_TARGET_PCT` environment variable on the backend |

### Status of Non-Compliant Assets (Donut Chart)

| Segment | What It Means | What Feeds It |
|---|---|---|
| Blocked | Non-compliant devices with NO resolution date set — the team has not committed to a remediation timeline | Devices without a `resolution_date` value |
| In-Progress | Non-compliant devices WITH a resolution date set — the team has a target fix date | Devices with a `resolution_date` value |

**How to move devices from Blocked to In-Progress:** Set a resolution date on the device, either by clicking into it on the Compliance page and entering a date, or by using the Bulk Upload with a "Resolution Date" column.

### Heavy Hitters Table

| Column | What It Means | What Feeds It |
|---|---|---|
| Vertical / Team | The team responsible for the non-compliant devices | `team` field on compliance items (set during xlsx upload) |
| Non-Compliant | Count of unique hostnames with active findings for that team | Computed from compliance_items |
| Compliance Date | The team's stated target for full remediation (e.g., "Q3 2026") | Manually entered on this page (click to edit) |
| Notes | Team-level summary of their remediation approach | Manually entered on this page (click to edit) |

### Vertical Breakdown Table

| Column | What It Means | What Feeds It |
|---|---|---|
| Vertical | Team name | `team` field on compliance items |
| Compliance % | `(Compliant devices in team / Total devices in team) * 100` | Computed from compliance_items |
| Team | Same as Vertical | Same |
| Non-Compliant | Count of non-compliant devices for that team | Computed from compliance_items |
| Forecast Burndown (monthly columns) | How many devices are expected to be remediated each month | Grouped by the `resolution_date` month on individual devices |
| Blockers | Non-compliant devices with NO resolution date (no committed timeline) | Count of devices where `resolution_date` is NULL |
| RAs | Risk Acceptances — count of approved exceptions for that team | Manually entered on this page (click to edit) |
| Notes | Team-level remediation narrative | Manually entered on this page (click to edit) |

### Compliance Overview Trend Chart

| Element | What It Means | What Feeds It |
|---|---|---|
| Green bars | Count of compliant devices for each month | Monthly snapshots (created automatically on each compliance upload) |
| Solid teal line | Actual compliance percentage for each month | Monthly snapshots |
| Dashed teal line | Forecasted compliance percentage (projected forward) | Linear regression on the last 3+ months of actual data |
| Amber horizontal line | Target compliance threshold | `VCL_TARGET_PCT` environment variable |

> The trend chart requires at least one compliance upload to create the first snapshot. After 3+ monthly uploads, the forecast line appears.

---

## What Feeds the Data

### Automatic (from compliance uploads)

These values update automatically when a new weekly compliance xlsx is uploaded:

- Total Devices, In-Scope, Compliant, Non-Compliant counts
- Current Compliance %
- Per-team compliance percentages
- Monthly trend snapshots (one snapshot per upload)
- Devices moving between active/resolved status

### Manual (entered by engineers or BIs)

These values are entered by users and persist until changed:

| Field | Where to Enter It | Scope |
|---|---|---|
| Resolution Date | Compliance page → click device → Resolution Date field | Per device |
| Remediation Plan | Compliance page → click device → Remediation Plan field | Per device |
| Compliance Date | VCL Report → Heavy Hitters table → click the cell | Per team |
| Notes | VCL Report → Heavy Hitters or Vertical Breakdown → click the cell | Per team |
| RAs (Risk Acceptances) | VCL Report → Vertical Breakdown → click the cell | Per team |

### Bulk Upload

For updating many devices at once (e.g., 1000 devices), use the **Bulk Upload** button on the VCL Report page:

1. Prepare an xlsx file with columns: `Hostname`, `Resolution Date`, `Remediation Plan`, `Notes`
2. Click Bulk Upload and select the file
3. Review the diff preview (shows matched/unmatched/changed/invalid counts)
4. Confirm to commit changes

---

## How Metrics Adjust Over Time

### Weekly Compliance Upload Cycle

Each weekly xlsx upload triggers these changes:

1. **New findings** appear as active items → Non-Compliant count increases
2. **Resolved findings** (devices no longer on the report) get marked resolved → Compliant count increases
3. **A monthly snapshot** is created/updated in `compliance_snapshots` → feeds the trend chart
4. **Stats bar** reflects the new totals immediately

### As Teams Set Resolution Dates

When resolution dates are added to devices:

1. **Donut chart shifts** — devices move from "Blocked" (red) to "In-Progress" (amber)
2. **Forecast burndown columns populate** — showing expected remediations per month per team
3. **Blockers count decreases** — fewer devices without a committed timeline

### As Devices Get Remediated

When a device drops off the weekly compliance report (finding resolved):

1. **Non-Compliant count decreases**
2. **Compliant count increases**
3. **Current % improves**
4. **Team compliance % improves**
5. **The device's resolution_date no longer contributes to forecast** (it's done)

### Trend Chart Over Months

After 3+ monthly compliance uploads:

1. The trend chart shows actual compliance % per month (solid line)
2. A linear regression projects the trend forward 3 months (dashed line)
3. You can see whether the organization is on track to hit the target % (amber line)

---

## Summary: Data Flow

```
Weekly xlsx upload
    → compliance_items (active/resolved findings per device)
    → compliance_snapshots (monthly aggregate for trend chart)
    → Stats bar, donut, heavy hitters, vertical breakdown auto-update

Engineers set resolution_date on devices (manual or bulk upload)
    → Donut shifts from Blocked to In-Progress
    → Forecast burndown columns populate
    → Blockers count decreases

BIs edit team-level fields on VCL Report page
    → Compliance Date, Notes, RAs saved per team
    → Displayed in Heavy Hitters and Vertical Breakdown tables

Devices remediated (drop off next weekly upload)
    → Compliance % improves
    → Trend chart shows upward movement
    → Forecast adjusts based on new regression
```