165 lines
7.8 KiB
Markdown
165 lines
7.8 KiB
Markdown
# 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
|
|
```
|