A vulnerability metrics data dictionary is a short document that defines every field and every reported number: its meaning, unit, source system, time zone, filters, known limits and owner. It prevents two people computing different values for the same metric, and it makes audits of dashboard numbers much faster.
Field level entries
For each field in your findings table, write:
| Attribute | Example content |
|---|---|
| Name | detected_at |
| Meaning | Time the first complete scan reported the finding |
| Type and format | Instant, UTC, RFC 3339 |
| Source | Which system writes it |
| Allowed values | For status fields, the full list |
| Can be empty? | Yes or no, and what empty means |
| Changes over time? | Whether a later scan can overwrite it |
Pay special attention to fields that can be empty, such as severity, owner and environment, since an undefined empty value is where most silent errors begin.
Metric level entries
For every number that appears on a chart or in a report, answer these questions in one short block.
- Question answered. For example, how long do we take to fix serious issues?
- Formula. In words and, if helpful, a query.
- Unit of count. Unique IDs, findings or instances.
- Population. Which assets are included, and which are excluded with reasons.
- Time window. The date field used and the period.
- Treatment of open items. Included, excluded, or counted separately.
- Treatment of reopened, suppressed and paused items.
- Data freshness. How often it refreshes and the last refresh time shown.
- Known limits. Where the number can mislead.
- Owner. Person or team responsible for the definition.
Keep it in a place people will use
A dictionary in a document nobody opens does no good. Link each chart to its definition, show a short version in a tooltip, and require a definition for any new chart. Version it, with a change log: when a definition changes, record the date and what changed, so trend breaks can be explained.
Review rhythm
Review the dictionary when you change scanners, add an ecosystem, restructure teams, or when an audit of a dashboard number finds a mismatch. A short review each quarter is usually enough.
Example metric block
A good entry might read: "Open critical findings. Count of findings with status open and severity critical under the CVSS v3 band, in production assets, as of the latest complete scan per asset. Excludes accepted items, which are reported separately. Refreshed daily. Limit: assets never scanned are not included and are shown in a separate figure."
That is five sentences and answers most of the questions a reviewer will ask. For a related approach, see the metric definition card template.
Safeguard does this kind of counting in one place: SBOM and dependency scanning, asset discovery and reachability analysis feed the same inventory, so each number can be traced back to its source. Compliance and evidence automation can keep definitions and the numbers they produce together for review. You can try a free scan at gold.safeguard.sh/scan.
Quick check
How long should an entry be?
A short block per metric, a few sentences. If it is long, the metric is probably doing too much.
Who owns the dictionary?
A named owner per metric, often the person who reports it, with a periodic review by someone independent.
Last reviewed: 19 October 2026.
