Security Monitoring API: CVE, Package, Domain & IP Watchlist
Watch the CVEs, products, CVE searches, packages, domains and IP addresses you care about, and read what changed. A CVE item hears when it enters CISA KEV, when its EPSS score climbs or when an exploit appears. A package item hears new advisories and fixes. A domain item hears DNS, TLS, WHOIS, header and certificate changes. An IP item hears when the address enters or leaves the DROP list, and when its hosting changes. Monitoring needs a Pro key and works over REST and as MCP tools, for developers and AI agents.
What you can ask
watchlist_edit. Add, remove, list or clear the items your key watches. API docs
watchlist_events. The change events that match your items, oldest first, grouped by item. API docs
Example
curl -X POST https://api.contrastcyber.com/watchlist_edit -H "X-API-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{"action":"add","endpoint":"package_check","ecosystem":"npm","name":"lodash","version":"4.17.20"}'
curl https://api.contrastcyber.com/watchlist_events -H "X-API-Key: $KEY"Example response of the second call, trimmed; the values are an example:
{
"limit": 20, "cursor": null, "repeat": false, "next_cursor": "14", "has_more": false,
"items": [
{"item": {"endpoint": "package_check", "ecosystem": "npm", "name": "lodash", "version": "4.17.20"}, "events": [
{"event": "fix_available", "changed_at": "2026-10-21T05:06:07Z", "advisory_id": "GHSA-35jh-r3h4-6jhm", "fixed_version": "4.17.21", "affects_version": true},
{"event": "kev_added", "changed_at": "2026-10-22T06:07:08Z", "cve_id": "CVE-2021-23337"}
]}
],
"cves": {
"CVE-2021-23337": {"risk_score": 61.2, "label": "HIGH", "in_kev": true, "kev_patch_deadline": "2026-11-12"}
}
}From an agent
Your agent calls these MCP tools: watchlist_edit and watchlist_events. Connect once with the MCP setup, then ask in plain words.
- “Watch lodash 4.17.20 on npm and tell me when a fix comes out.”
- “Watch every critical Apache CVE and tell me when one enters KEV.”
- “What changed on example.com since you last checked?”
Limits
Each call of watchlist_edit or watchlist_events costs 1 credit and needs a Pro key. A Pro key gets 500 credits per hour. A watchlist holds at most 100 items that are not package items, and at most 500 package items. One answer holds at most 100 events. Events older than 90 days are deleted.
What each item watches
An item names one endpoint and the values that endpoint takes: a CVE ID, a vendor and product pair, some cve_search filters, a domain, a package, or an IP address. The endpoint sets the events the item can emit:
| Watched endpoint | Events |
|---|---|
cve_lookup | cve_added kev_added kev_removed epss_level_up epss_level_down cvss_added cvss_risk_band_changed exploit_published product_added product_removed ransomware_linked vendor_advisory_published patch_published cve_disputed cve_rejected metasploit_added nuclei_template_added exploitdb_added ssvc_added ssvc_changed github_poc_added description_changed cvss_score_changed cwe_changed kev_updated ghsa_linked |
product_exposure | cve_added kev_added kev_removed epss_level_up epss_level_down cvss_added cvss_risk_band_changed exploit_published product_added product_removed ransomware_linked vendor_advisory_published patch_published cve_disputed cve_rejected metasploit_added nuclei_template_added exploitdb_added ssvc_added ssvc_changed github_poc_added description_changed cvss_score_changed cwe_changed kev_updated ghsa_linked eol_approaching eol_reached eol_date_changed |
cve_search | cve_added kev_added kev_removed epss_level_up epss_level_down cvss_added cvss_risk_band_changed exploit_published product_added product_removed ransomware_linked vendor_advisory_published patch_published cve_disputed cve_rejected metasploit_added nuclei_template_added exploitdb_added ssvc_added ssvc_changed github_poc_added description_changed cvss_score_changed cwe_changed kev_updated ghsa_linked epss_above_min epss_below_min |
kev_lookup | kev_added kev_removed ransomware_linked kev_updated |
cve_exploit | exploit_published metasploit_added exploitdb_added github_poc_added |
package_check | advisory_added fix_available malware_added kev_added ransomware_linked eol_approaching eol_reached eol_date_changed |
dns_lookup | domain_not_found domain_found ns_changed mx_changed ip_address_not_public ip_address_lost ip_address_restored cname_takeover_detected cname_takeover_resolved email_auth_degraded hosting_changed |
ssl_check | cert_expiring cert_invalid cert_listed tls_downgraded |
whois_lookup | domain_expiring registrar_changed transfer_lock_removed dnssec_disabled |
headers_check | security_header_removed |
cert_search | cert_unexpected |
ip_lookup | drop_listed drop_unlisted hosting_changed |
A CVE event comes when the server loads a feed that changes the CVE. A cve_search item must set at least one filter. It tests each filter against the CVE as it is now. Its KEV filter is not tested for kev_added and kev_removed: an item that asks for CVEs in KEV, or for CVEs outside it, hears both, when its other filters hold.
A package item names an ecosystem and a package name, and may name one version. An item with a version hears an advisory event only when the advisory affects that version, or when the server cannot tell. The events kev_added and ransomware_linked are CVE events. They reach the item when an advisory of its package lists the CVE as an alias. The three end-of-life events reach it when its package maps to an endoflife.date product. One watchlist_edit call with a list of packages adds or removes many package items.
A domain item gets a scan of its own. A dns_lookup, ssl_check, headers_check or cert_search item is scanned once a day. A whois_lookup item is scanned once a week, and once a day within 30 days of the registration’s end. A change becomes an event after a later scan sees it again, except a new certificate issuer, which becomes an event at once.
An item sees only the events after the moment it was added. The CVE, package, domain and IP pages give the details of each kind.
Reading the events
The server keeps the position of your key in the events. A plain call of watchlist_events reads the events after the last batch and moves the position past them. has_more says whether more events wait. repeat=true answers the last batch again and leaves the position where it is. cursor takes the next_cursor of an earlier answer. It reads the events after it again and leaves the position where it is. The answer groups the events by item. Its cves map gives the risk score, KEV state and exploit flags of each CVE as they are now. Its domains map gives the DNS values of each domain that a dns_lookup item watches.
Data sources
- CVE events: the CVE, KEV, EPSS and exploit feeds that the CVE API page lists, as the server loads them.
- Package events: the OSV.dev advisory feeds that the package API page lists. A package event answer names the source and licence of its advisories.
- Domain events: the DNS, TLS, RDAP/WHOIS, header and Certificate Transparency scans that the domain API page lists.
- IP events: the DROP list, IPtoASN and the cloud and CDN ranges that the IP API page lists, as the server loads them.
FAQ
- Does monitoring need a key?
- Yes. watchlist_edit and watchlist_events need a Pro API key. Each call costs 1 credit.
- Does the server send the events to me?
- No. You pull them with watchlist_events when you want them. The server keeps your position, so a plain call reads only the events after the last batch.
- What happens if I lose an answer?
- Call watchlist_events with repeat=true. It answers the last batch again and leaves the position where it is.
- How long are events kept?
- 90 days. Older events are deleted.