Hole Monitor

Payload

By default every delivery body is one OSV 1.9.2 record. Facts OSV has no field for are under database_specific. The body's JSON Schema is at /schemas/webhook-v1.json. An endpoint can receive CSAF or CycloneDX instead; see Formats.

Content modes

Each endpoint has a content setting. The default, structured, sends no text that a third party wrote. See Security for why.

structured (default) full
summary, details, credits Omitted Sent
references Only URLs the service builds from validated IDs As the sources gave them
IDs, versions, package names, CVSS vectors Sent when they match their pattern, dropped when not Sent
Vendor and product names Cleaned, sent if within 128 characters and a fixed character set Sent as given
Numbers, dates, enumerated values Sent Sent
Attribution Source name and a link to Attribution Notices and licence text
Marking content: "structured", omitted: count of dropped values content: "full", untrusted_fields: JSON pointers to third-party text

In both modes invisible characters (controls, zero-width, bidi overrides, Unicode tags, supplementary variation selectors) are removed from all text, and a body that had any removed carries sanitized: true.

Formats

Each endpoint has a format setting. Every format is built from the OSV record in the endpoint's content mode, so structured withholds the same text in all of them.

format Body content-type
osv (default) One OSV 1.9.2 record application/json
csaf One CSAF 2.0 document, category csaf_security_advisory application/json
cyclonedx One CycloneDX 1.6 BOM with the affected components and one vulnerability application/vnd.cyclonedx+json; version=1.6

How the record maps:

OSV CSAF CycloneDX
id, aliases vulnerabilities[0].cve and ids; document.tracking.id and aliases vulnerabilities[0].id and references
affected product_tree: vendor (or ecosystem), product name, then a product_version_range per affected interval in vers syntax components, and affects with range (vers) or version
Fixed versions product_status.first_fixed and a vendor_fix remediation affects version with status unaffected
CVE-record unaffected entries product_status.known_not_affected affects status unaffected
database_specific.cvss scores: the first CVSS v3.x and v2.0 score with a number ratings: every score
summary, details (full only) Vulnerability notes summary and description description, detail
references Vulnerability references, category external advisories
kev A threat of category exploit_status Properties holemonitor:kev:*
epss, drupal.risk Vulnerability notes Properties holemonitor:epss:*, holemonitor:drupal:risk
cwes Not sent: CSAF 2.0 needs each CWE's name cwes as numbers
withdrawn A document note titled Withdrawn rejected
event, content, omitted, sanitized, previous_id, sources A document note titled Hole Monitor event, its text a JSON object Metadata properties holemonitor:event:* and others

Both formats number revisions. Each event raised for an advisory adds one: CSAF lists them all in revision_history and sets tracking.version to the latest, and CycloneDX sends it as the BOM version under a serialNumber fixed for the advisory. Revisions start at 1 for each advisory; an advisory re-keyed to a CVE ID keeps its count.

Left out: CVSS v4.0 in CSAF, which 2.0 has no field for; GIT ranges, which are commits rather than ordered versions; and untrusted_fields, which are OSV pointers. In full content the third-party text is in CSAF notes, titles and references and in CycloneDX description, detail and advisories.

A record with no affected product cannot meet the csaf_security_advisory profile and is sent with category csaf_base. Verification requests are sent as described below in every format.

Record fields

Field Built from
id CVE ID when one exists, else GHSA ID, else Drupal OSV ID (DRUPAL-CONTRIB-2026-001), else x_WORDFENCE-<uuid>
aliases Every other known ID
published Earliest publication time across sources
modified Time of the last rebuild that changed the record materially
withdrawn CVE state REJECTED, GHSA withdrawal, or a Wordfence deletion
summary, details CVE title and description, else GHSA, Drupal or Wordfence text. full only
severity One entry per distinct CVSS vector, typed CVSS_V2, CVSS_V3 or CVSS_V4
affected[].package Ecosystem and name from GHSA, Drupal, Wordfence. WordPress uses WordPress:Plugin, WordPress:Theme, WordPress:Core
affected[].ranges, versions GHSA, the Drupal OSV files, Wordfence
affected[].database_specific vendor, product, cpes and the CVE record's version entries, unconverted, for entries with no package
references See content modes

A record whose affected entries carry vendor and product but no package is valid OSV. CVE-record version data is passed through unconverted.

database_specific

Field Meaning
event { id, type, changed, created }. type is published, updated, kev_added or withdrawn. changed names what differs for updated: severity, affected, aliases, drupal, kev, withdrawn, epss, redhat, exploited. test: true on a test event
sources Sources that contributed: cve, nvd, ghsa, drupal, drupal_osv, kev, wordfence, epss, redhat, vulncheck_kev, osv
cvss [{ version, base_score, vector, source }]. OSV's severity holds no number, so scores are here, beside the issuer: cna, adp:cisa, nvd, ghsa, wordfence
max_base_score Highest base score, or null. Versions 3.x and 4.0 are compared as if on one scale
epss { score, percentile, date } from FIRST
kev { date_added, due_date, ransomware_use } from CISA KEV
exploited [{ source, date_added, ransomware_use }], one per source other than CISA KEV that reports exploitation: vulncheck_kev. Evidence links are in references with type EVIDENCE
drupal { advisory_id, risk }
wordfence { id, url }
cwes CWE IDs
cve_state, nvd_status As the sources state them
previous_id Set when a record keyed by a GHSA, Drupal or Wordfence ID gains a CVE ID and is re-keyed
attribution Per-source notice, see Attribution
content, omitted, untrusted_fields, sanitized See content modes

Events

Type Raised when
published A record is first stored and its source published it within the last 7 days
updated The record's material facts change: CVSS vectors and scores, affected entries, aliases, Drupal risk
kev_added The CVE appears in CISA's KEV catalog
withdrawn The CVE is rejected or the advisory withdrawn

Description text, references, timestamps and NVD status are not material: changing them raises no event. An EPSS score raises updated with epss in changed only when it crosses a min_epss value some filter uses. A record that VulnCheck KEV adds raises updated with exploited in changed; kev_added is kept for CISA's catalog.

CVEs published in the year before the service started are backfilled from NVD and the CVE List as baselines, without events. Other sources are forward-only.

Example delivery (structured)

POST /hole-monitor HTTP/1.1
Host: hooks.example.com
content-type: application/json
webhook-id: dlv_01jd8m3k7q4x9w2v5n6p8r0s1t
webhook-timestamp: 1763700000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{
  "schema_version": "1.9.2",
  "id": "CVE-2026-12345",
  "modified": "2026-11-20T14:05:11.000Z",
  "published": "2026-11-20T13:58:02.000Z",
  "aliases": ["GHSA-abcd-efgh-jkmp"],
  "severity": [{ "type": "CVSS_V3", "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H" }],
  "affected": [
    {
      "package": { "ecosystem": "npm", "name": "example-lib" },
      "ranges": [{ "type": "SEMVER", "events": [{ "introduced": "0" }, { "fixed": "4.2.1" }] }]
    }
  ],
  "references": [
    { "type": "ADVISORY", "url": "https://www.cve.org/CVERecord?id=CVE-2026-12345" },
    { "type": "ADVISORY", "url": "https://nvd.nist.gov/vuln/detail/CVE-2026-12345" },
    { "type": "ADVISORY", "url": "https://github.com/advisories/GHSA-abcd-efgh-jkmp" }
  ],
  "database_specific": {
    "sources": ["cve", "ghsa"],
    "cvss": [{ "version": "3.1", "base_score": 9.8, "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H", "source": "ghsa" }],
    "max_base_score": 9.8,
    "attribution": [
      { "source": "cve", "url": "https://holemonitor.live/docs/attribution#cve" },
      { "source": "ghsa", "url": "https://holemonitor.live/docs/attribution#ghsa" }
    ],
    "content": "structured",
    "omitted": 0,
    "event": { "id": "evt_01jd8m3k5c2b7a9z4y6x8w0v1u", "type": "published", "changed": [], "created": "2026-11-20T14:05:11.000Z" }
  }
}

The IDs, package and scores in this example are placeholders.

Verification request

A new endpoint receives one signed request whose body is:

{ "type": "verification", "endpoint_id": "ep_...", "code": "...", "instructions": "..." }

Answer with a 2xx response whose body contains the code, or submit the code with POST /v1/endpoints/{id}/verify. The verification body is not an OSV record; a receiver can tell it apart by its top-level type.