diff --git a/docs/content/metrics_reports/dashboards/PRO__command_center.md b/docs/content/metrics_reports/dashboards/PRO__command_center.md new file mode 100644 index 0000000000..d5cd5025e6 --- /dev/null +++ b/docs/content/metrics_reports/dashboards/PRO__command_center.md @@ -0,0 +1,52 @@ +--- +title: "Command Center" +description: "The flagship DefectDojo Pro dashboard family: posture score, instrumented pipeline funnel, honest coverage, TV mode, and the scheduled executive pack" +draft: false +audience: pro +weight: 11 +slug: command-center +--- +Note: the Command Center is a DefectDojo Pro feature in beta. It builds on [Customizable Dashboards](../custom-dashboards/) and is off by default. A superuser can turn on the command_center flag from Settings > Feature Flags (it requires the dashboard_v2 flag). + +The Command Center expands DefectDojo Pro's customizable dashboards into a full security command center: one screen that answers, in fixed zones, **what's on fire**, **are we winning**, and **is the machine healthy**. It is not a new page: it ships as a family of preset layouts plus new widget types on the same dashboard system, so everything stays customizable, shareable, cloneable, exportable, and drivable from the [dashboards REST API](../custom-dashboards-api/). + +> **💡 Tip:** In DefectDojo Pro, **Assets** were formerly called **Products** and **Organizations** were formerly **Product Types**. The UI follows your instance's naming setting. + +## The preset family + +Turning the flag on publishes four seeded, cloneable layouts under the **Command Center** group of the Shared Templates picker: + +* **Command Center** (the new starter): the flagship screen. New users land on it; existing users keep their current dashboards and defaults, and can clone it whenever they like. +* **Exec Brief**: the board-facing view. The posture score with its why panel, the quarter's trajectory, risk acceptance debt, fix durability, and a fairness-normalized team scorecard. +* **Ops Triage**: queue first. Your work, what breaches next, this week's intake funnel, live activity, backlog aging. +* **Platform Health**: the machinery deep dive. The pipeline funnel at full width, the sensors rail, automation throughput, coverage freshness, license headroom. + +With the flag on, the sidebar **Home** entry lands on your default customizable dashboard; the classic dashboard stays reachable as **Legacy Dashboard** while your team migrates. + +## The daily snapshot backbone + +Every Command Center trend reads from an append-only daily snapshot table that the nightly rollup writes: open findings by severity, SLA state (a five-state model that distinguishes "resolved late" from "still open and late"), the dedupe funnel's flows, scan freshness, automation counts, and the posture score's full input vector. History is kept indefinitely, and a backfill command reconstructs what the ledgers can honestly support so trendlines are not empty on day one. Reconstructed periods are labeled as such; nothing is interpolated or fabricated. Trend charts also carry event markers (a scanner onboarded, an SLA policy change, a score model version change) so a step in a line is never mistaken for a posture change. + +## The pipeline funnel, with receipts + +The centerpiece widget shows what the platform did with everything your tools submitted, in five exact stages: **ingested**, **unique after dedupe**, **after rules and triage**, **prioritized**, and **actionable now**. Every gap between stages is itemized from a ledger (matched dedupe outcomes, rule actions, the manual remainder), every stage clicks through to the exact findings list behind it with the filter chips visible, and the **receipts export** downloads the raw evidence rows: which findings each stage dropped, and why. It is compliance evidence, not a marketing percentage. + +## Honest coverage + +The coverage freshness widget buckets assets by days since their last scan, with **never scanned** as its own visually distinct state. Never scanned is not zero findings, and neither is ever rendered green. An optional matrix breaks freshness down by scan type. + +## TV / wall mode + +Any dashboard (or a playlist of several) can run full screen on a wall monitor: open the **Present on TV** dialog from the dashboard toolbar, pick the layouts and cadences, and bookmark the generated URL on the wall box. The kiosk auto-cycles with a dwell indicator, refreshes data on its own cadence, pins the wall for 90 seconds when a new Critical arrives, reloads itself every 8 hours, shows when its numbers were last true, and says so plainly when the connection is lost. Sign the wall box in as a dedicated read-only user: the screen shows exactly what that user is authorized to see, and nothing more. + +## The scheduled executive pack + +From the same toolbar you can schedule the **executive posture pack**: a server-rendered PDF (or HTML) of the score with its component breakdown, the funnel, current pressure numbers, and coverage honesty, generated on your cadence and delivered as a link to Generated Reports. Authorization is enforced again at download time, the pack's numbers come from the same snapshot ledger as the screen, and disabling the schedule is one toggle. + +## New widget types + +The Command Center adds thirteen widget types to the catalog, each wired to real tables and available on any layout: Big KPI, Posture Score, Pipeline Funnel, Coverage Freshness, Ingest Health, Automation Rate, Threat Pulse, Risk Acceptance Debt, Fix Durability, Top Fixes, Morning Brief, Team Scorecard, and Insights Plot. Four existing widgets gained modes: MTTR/MTTD (survival curve), SLA Burndown (five-state model), Recent Activity (live feed), and KPI/Trend (snapshot-backed deltas). Details and configuration schemas are discoverable at `GET /api/v2/dashboards/widget_catalog/`. + +**Insights Plot** puts one of three charts from the Insights pages onto a dashboard: noise reduction by category, average EPSS score by tool, or findings past SLA. Pick the plot and a window in the widget's settings. These run the same aggregation as the matching Insights chart rather than a dashboard-side copy of it, so the two screens cannot report different numbers for the same window, and both are scoped to the findings you are authorized to see. + +The posture score's scale, weights, and versioning policy are published: see [Posture Score](../posture-score/). diff --git a/docs/content/metrics_reports/dashboards/PRO__posture_score.md b/docs/content/metrics_reports/dashboards/PRO__posture_score.md new file mode 100644 index 0000000000..15c0b49dec --- /dev/null +++ b/docs/content/metrics_reports/dashboards/PRO__posture_score.md @@ -0,0 +1,42 @@ +--- +title: "Posture Score" +description: "DefectDojo Pro's published, versioned security posture score: the scale, every weight, every formula, and the counterfactual semantics" +draft: false +audience: pro +weight: 12 +slug: posture-score +--- +Note: the Posture Score ships with the DefectDojo Pro Command Center (beta). See Command Center for enabling it. + +Most security scores are opaque: a number with no published scale, no published weights, and no way to check it. DefectDojo's posture score makes the opposite commitment. The formula below is the formula; the same descriptor is served machine-readable at `GET /api/v2/dashboards/widget_data/posture_formula/`; every input is stored in the daily snapshot ledger, so any historical score can be recomputed and audited; and formula changes are versioned events drawn on the trend line, never silent rewrites of history. + +## The scale + +0 to 1000, higher is better. Bands: **strong** at 800 and above, **needs attention** at 600 to 799, **at risk** below 600. A score is computed over the viewer's authorized assets, so two users with different access correctly see different scores; instance-wide scores require a global view permission. + +## The formula (version 1) + +The score is the weighted sum of five components. Each component is normalized to a 0 to 1 value by a monotone function of raw inputs, then multiplied by its weight. Weights sum to exactly 1000. + +| Component | Weight | Normalized value | +|---|---|---| +| Open severity burden | 300 | `1 / (1 + density / 25)` where `density` is severity-weighted open findings (Critical 10, High 5, Medium 2, Low 1, Info 0) divided by assessed assets | +| SLA posture | 200 | `1 - (breached / SLA-tracked open)`; neutral 1.0 when nothing is SLA-tracked, flagged as such | +| Coverage confidence | 200 | assets scanned in the last 90 days / all assets | +| Exploit pressure | 150 | `0.5 ^ (open KEV findings / 4)`, multiplied by `1 - 0.5 x EPSS p90` of the open backlog | +| Automation health | 150 | rule actions / (rule actions + manual closures) over the window; neutral 0.5 when there was no triage activity, flagged as such | + +Design commitments, stated so they can be challenged: + +* **Ratios, not raw counts**, wherever growth would otherwise punish scope: burden is a per-assessed-asset density, SLA and coverage are shares. Growing your inventory without scanning it lowers the score through coverage, which is the honest direction. +* **KEV is deliberately absolute.** A known-exploited vulnerability open anywhere is an emergency regardless of estate size, so it is an exponential penalty, not a ratio. It saturates, so it cannot zero the score alone. +* **Priority bands are excluded** from the score because their thresholds are per-instance configuration; a published formula must not change meaning when an admin edits a threshold. +* **Neutral rules are visible.** Where a component has nothing to measure (no SLA tracking, no triage activity, no EPSS data), the why panel says so instead of hiding a default. + +## The why panel and the counterfactual + +The score widget's why panel decomposes the number into the five components (weight, value, contribution, and a plain sentence each), shows the raw stored inputs (the receipt), and ranks the **levers**: exact counterfactuals computed by substituting one input and re-running the same formula. "Fix the 12 known-exploited findings: at least +84 points." Deltas are lower bounds where levers overlap in reality, which is why every lever says "at least". + +## Versioning + +Formula versions are immutable once shipped. Changing a weight or a normalization means publishing a new version; the daily snapshot records both the score as published that day and the full input vector, so trends can be rendered two ways: recomputed under the current formula (the default, so a formula release never masquerades as a posture change) or as published at the time, with version-change markers on the chart. The version history is part of the formula endpoint's response.