Skip to content

README.md

Latest commit

 

History

History
66 lines (51 loc) · 2.78 KB

README.md

File metadata and controls

66 lines (51 loc) · 2.78 KB
Raw

Vulnerability labeling

This folder turns retained CVE claims and reference evidence into explicit, rule-based suggestions for the Iuliano and Di Nucci, CWE, and SWC taxonomies. Complete manual decisions replace an automatic result when review is needed. The resulting public mapping is labels.json.

Build

Validation must first have produced validation/generated/cve_texts.jsonl. Then run:

python labeling/scripts/build_labels.py

The builder runs generate_label_suggestions.py, loads any manual decisions, validates all identifiers against the frozen taxonomy snapshots, and writes labels.json. Use --skip-suggestions only for decision-only iteration after the evidence, rules, and taxonomies have remained unchanged.

The explicit rules in rules/vulnerability_rules.json are the only automatic classification mechanism. They are applied at the evidence tiers CVE descriptions, titles, manual evidence, direct references, OCR, reference metadata, and source artifacts, in descending precedence. Source code affects a suggestion only when a rule explicitly opts into code evidence.

If a rule applies, it produces a labeling suggestion. If multiple rules apply to a record with the same deciding evidence tier, the labeling is considered ambiguous. A record with an ambiguous or insufficient suggestion is emitted as not_classifiable unless a manual decision exists.

Manual decisions

Files under decisions/ conform to label_decision.schema.json. A decision contains complete Iuliano and Di Nucci 2026, CWE, and SWC assignments and a required justification. It replaces rather than patches the generated result. See decisions/README.md for the format.

Important files

  • rules/vulnerability_rules.json: declarative three-taxonomy rules.
  • generated/label_suggestions.json: canonical, formatted suggestions, evidence, CNA/ADP CWE assertions, and diagnostics.
  • decisions/CVE-*.json: complete current manual decisions
  • labels.json: resolved automatic and manual labels for every indexed CVE.
  • labels.schema.json: schema for labels.json.
  • label_decision.schema.json: schema for manual decisions.
  • taxonomies/: frozen Iuliano and Di Nucci 2026, CWE, and SWC representations.

Validate rule syntax, taxonomy identifiers, and embedded examples without rewriting suggestions using:

python labeling/scripts/generate_label_suggestions.py --self-test

The generator does not create a CSV by default. For a temporary flattened spreadsheet review view, pass --csv-output /path/to/suggestions.csv.

Only the resolved taxonomy assignments are embedded under labels in the corresponding cve.json catalog record when that CVE passes catalog selection. Classification and automatic or manual provenance remain in labels.json.