cve-dashboard/docs/guides/kb-vcl-reporting-guide.md

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