The CRDS schema

Every card on this site is one JSON document in the same shape. That shape is the Common Risk Definition Set (CRDS), a JSON Schema you can read here and validate against.

Open the schema See a card as JSON

VERSION 0.1 / JSON SCHEMA DRAFT 2020-12

Two documents, kept apart

A CRDS document is one of two kinds, and the difference is who it is true for.

BaseCard: Facts that hold for everyone: what the flaw is, how severe it is, whether it is being exploited, what to do. Shareable. Every card on this site is a BaseCard.
OrgOverlay: One organization's context: its assets, owner, priority, status and due date. Private. It stacks on a BaseCard when rendered and is never merged into it.

This site publishes BaseCards only. It stores no overlays and offers no way to submit one. The schema defines them so that a team can keep its own context beside a card without changing the card.

A card keeps its identity

The id never changes. When the facts do, such as a new CISA listing, the card is reprinted: revision goes up and supersedes can name the revision it replaces. An overlay follows the latest revision unless it pins one.

A card is not deleted because its CVE leaves KEV. It stays, marked retired.

Every fact says where it came from

The provenance list names the source behind each group of fields, when it was retrieved and what extracted it. references lists where a reader can check the card. Both are required, and each needs at least one entry.

severity is a normalized judgment, not raw CVSS, so the score stays in its own field. confidence rates the card as a whole.

Use it

The schema lives at the address in its own $id. Any JSON Schema validator for draft 2020-12 can check a card against it, and the format keywords need that validator's format support. The file can be fetched from any origin, so a web app can load it directly.

curl -O https://scrty.net/schemas/crds/0.1/crds.schema.json
curl -O https://scrty.net/card/cve-2021-44228.json

Each card is served at /card/<cve-id>.json.

Licence

The schema is published under the Creative Commons Attribution 4.0 International licence (CC BY 4.0), like the cards. You may copy, adapt and build on it for any purpose, with attribution to SCRTY:CRDS (scrty.net) and a link to the licence. The about page says what the licence covers on a card.

BaseCard fields

Unknown fields are rejected, so a valid card holds only what is listed here.

Fields of a BaseCard, generated from the schema
Field	Type	Meaning
`crds_version`required	"0.1"	The version of this schema the document follows.
`kind`required	"base"	Marks the document as a BaseCard.
`id`required	string	Immutable card identity. Never changes across revisions ('reprints'). Overlays reference this.
`revision`required	integer	Monotonic revision ('errata/reprint'). New facts, e.g. a CISA KEV listing, bump the revision. Overlays re-stack onto the latest revision automatically unless pinned.
`supersedes`	integer	Optional: previous revision this one replaces.
`retired`	boolean	The CVE has left CISA KEV. The card stays: it is never deleted for that reason.
`subtitle`	string (max 60)	One line that tells this card apart from others sharing its name.
`cvss_vendor`	object	The score the vendor or CNA published, shown beside the NVD score in cvss. Set by the pipeline from a curated list.
`cvss_vendor.score`required	number (0–10)
`cvss_vendor.version`required	string
`cvss_vendor.source`required	string (uri)
`cvss_vendor.as_of`required	string (date)
`aliases`	array of string (max 60)	Other names the flaw goes by. Set by the pipeline from a curated list.
`affected`	array of string (max 80)	Products and runtimes the flaw reaches. Set by the pipeline from a curated list.
`title`required	string (max 80)	Card name. Short, recognizable. 'Log4Shell — Log4j JNDI RCE'.
`summary`required	string (max 280)	What is it, in one breath. Plain language, no acronym soup.
`source_type`	cve · vendor_advisory · threat_intel · pentest_finding · scanner_finding · incident · other	What kind of input this card was normalized from.
`severity`required	critical · high · medium · low · info	Card frame color. Normalized judgment, not raw CVSS.
`cvss`	object	The score recorded by NVD.
`cvss.score`	number (0–10)
`cvss.vector`	string
`cvss.version`	string
`epss`	number (0–1)	Exploit Prediction Scoring System probability, if known.
`exploitation`required	object	What is known about attacks on this flaw.
`exploitation.known_exploited`required	boolean	Exploitation observed in the wild (e.g. CISA KEV). Foil treatment.
`exploitation.exploit_available`required	boolean	Public PoC or weaponized exploit exists.
`exploitation.exploit_override`	object	Present when exploit_available comes from a curated source because NVD's reference tags do not record it.
`exploitation.exploit_override.source`required	string (uri)
`exploitation.exploit_override.as_of`required	string (date)
`exploitation.exploit_override.note`	string (max 200)
`exploitation.attack_complexity`required	low · medium · high
`exploitation.kev_added`	string (date)	Date CISA listed the CVE in the Known Exploited Vulnerabilities catalog.
`exploitation.kev_due`	string (date)	Remediation due date CISA set for the listing.
`exploitation.prerequisites`	string (max 200)	What an attacker needs. 'Network access to the service' / 'Valid low-priv account'.
`remediation`	object	Global remediation facts only. Effort estimates are org-specific and live in the overlay.
`remediation.patch_available`	boolean
`remediation.workaround_available`	boolean
`remediation.fixed_in`	array of string	Fixed versions, e.g. ['log4j >= 2.17.1'].
`mitre_attack`	array of string	ATT&CK technique IDs. The card's 'type line'.
`kill_chain`	reconnaissance · resource_development · initial_access · execution · persistence · privilege_escalation · defense_evasion · credential_access · discovery · lateral_movement · collection · command_and_control · exfiltration · impact	The attack stage the flaw belongs to.
`recommended_action`required	string (max 200)	The one sentence at the bottom of the card. Imperative. 'Patch immediately.'
`confidence`required	high · medium · low	Overall confidence in the card as a whole.
`provenance`required	array of object	Auditability: which source supports which fields. Every AI-extracted fact must be traceable.
`provenance[].fields`required	array of string	JSON pointers or field names this source supports, e.g. ['exploitation.known_exploited'].
`provenance[].source`required	string	URL of the source.
`provenance[].retrieved_at`required	string (date-time)
`provenance[].confidence`	high · medium · low
`provenance[].extractor`	string	'human' or the model/pipeline id that extracted the fact.
`references`required	array of object	Where a reader can check the card.
`references[].type`required	cve · vendor_advisory · cisa · exploit · writeup · other
`references[].url`required	string (uri)
`references[].label`	string
`published_at`	string (date-time)	When the CVE record was published, per NVD. Not when the card was made.
`issued_at`required	string (date-time)	When this revision of the card was written.
`tags`	array of string	Free-form labels.

OrgOverlay fields

Fields of an OrgOverlay, generated from the schema
Field	Type	Meaning
`crds_version`required	"0.1"	The version of this schema the document follows.
`kind`required	"overlay"	Marks the document as an OrgOverlay.
`overlay_id`required	string	Identity of the overlay.
`base_ref`required	object	The BaseCard this overlay stacks on.
`base_ref.id`required	string	Immutable id of the BaseCard this stacks on.
`base_ref.pinned_revision`	integer	Optional: pin to a specific base revision. Default: always latest ('re-stack on reprint').
`org`	string	Owning organization identifier. Overlays never leave the org boundary.
`status`required	new · triaged · in_progress · mitigated · resolved · accepted · false_positive	Where the organization is with this card.
`priority`	p0 · p1 · p2 · p3	Org's own play order — may differ from base severity.
`affected_assets`	object	What this organization runs that the flaw reaches.
`affected_assets.count`	integer
`affected_assets.internet_facing`	integer
`affected_assets.asset_refs`	array of string	IDs in the org's CMDB/inventory.
`business_impact`	string (max 280)	Impact in this org's terms. 'Customer portal takeover; regulatory exposure.'
`owner`	string	Team or person holding the card.
`remediation_estimate`	string	ISO 8601 duration, e.g. 'PT2H', 'P3D'.
`due_date`	string (date)	When this organization means to have it done.
`exceptions`	string (max 500)	Risk acceptance rationale, if status is 'accepted'.
`notes`	string	Free text.
`updated_at`required	string (date-time)	When the overlay last changed.
`updated_by`	string	Who changed it last.