Search and vulnerability associations
Availability and authentication
CVE/KEV selectors, observed_products explanations and badge search criteria described here target staging. The revised staging OpenAPI contract becomes available with its backend deployment. This page does not announce their production availability.
Personal integrations use /api/v2/common/data with a personal API key in X-API-KEY, or Authorization: Bearer carrying a personal key or OAuth access token with profundis.read. Every data request requires a current paid subscription or purchased credit balance above zero. Field permissions and available credits still apply. A free enrichment operation does not remove this access requirement.
Browser calls use /api/v2/data with a session and CSRF protection for POST requests. They are a separate surface; see Session contracts.
Search existing observations
POST /search combines the relevant hosts, DNS, certificate (vhosts) and WHOIS datasets. Send stream: false for one JSON response:
POST /api/v2/common/data/search
X-API-KEY: <personal-key>
Content-Type: application/json
{"raw_query":"host:example.com AND kev:true","time_frame":"all_time","per_type_limit":20,"stream":false}
This is a staging example, not a request to run a scan. The body is limited to 4 KiB; the trimmed query must be nonempty and at most 512 UTF-8 bytes. time_frame accepts all_time, last_24h, last_7d, last_30d or this_year. The per-dataset limit defaults to 20; positive values are capped at 25. broad: true disables smart interpretation of bare inputs while retaining permissions and query validation.
The initial query is charged according to its target datasets. POST /search/more loads one dataset using raw_query, dataset (hosts, dns, vhosts, whois), page ≥ 2 and the same time_frame and effective per_type_limit. Additional pages use the dataset's depth pricing. GET /search/fields returns the searchable vocabulary without a search charge; a listed field may still require a higher entitlement.
With stream omitted or true, the response is SSE. JSON data chunks identify their type as partial, results, facets or final; retain outcomes through the final chunk. For JSON and streaming responses, inspect partial, per_type_status, lower_bound, per_type_failed, per_type_timed_out and per_type_capped when present. Dataset states include ok, timeout, busy, error, invalid_query and cancelled. A failed or partial dataset does not establish that it contains zero matches.
A stream can also terminate with an error chunk. Treat a connection ending without a final result as incomplete.
CVE and KEV selectors
These selectors apply to hosts observations:
| Selector | Meaning |
|---|---|
cve:CVE-2021-41773 | Association with this catalogue advisory |
cve:CVE-2024-* | Associations with advisories under this CVE prefix |
cve:* | At least one catalogue CVE association |
kev:true | At least one associated advisory in the available KEV catalogue |
kev:false | Negative selector over the indexed association; never proof of safety |
A bare exact CVE identifier is also recognized by unified search. Prefix wildcards must be a supported trailing CVE prefix; cve:apache, internal wildcards and kev:* are invalid. Use Boolean expressions to combine these fields with host criteria. Neither field is a sortable or aggregatable stored host attribute.
These results associate observed software identities with catalogue conditions. They do not confirm configuration, exploitability, ownership or the current state of a server. Missing versions, incomplete observations and unavailable catalogue data remain unknown. KEV describes known exploitation of an advisory in the catalogue; it does not prove exploitation of the returned asset.
Explain the matched product and version
POST /enrich/vulnerabilities reads the catalogue without charging search credits or contacting the asset. The account limit is 60 requests per minute across personal and organization enrichment; honor Retry-After on HTTP 429.
Prefer the opaque vulnerability_ref returned on a host observation (raw.vulnerability_ref in unified results, or data[].vulnerability_ref in granular results):
{"reference":"<vulnerability_ref-from-the-result>"}
References expire after 24 hours. They authorize only advisory enrichment for the returned software observations; they do not grant access to a host record or workspace. Do not decode or construct them. Alternatively, entitled callers may submit {"cpes":["<precise-observed-CPE>"]} with 1–8 CPEs. Raw CPE input on the personal surface requires the CPE field entitlement, currently Enterprise. Send one input form, not both; body limit is 100 KiB.
Each returned finding includes id, advisory details, nullable kev, additional_conditions, and observed_products: an array of {vendor, product, version} associated with that CVE. Do not attach every technology on the host to every finding. A schematic example is:
{
"id": "CVE-2021-41773",
"observed_products": [{"vendor":"apache","product":"http_server","version":"2.4.49"}]
}
This fragment illustrates an association, not an observed customer finding or active test result. Reference-based responses keep CPE identifiers private (cpes: null, empty evaluation cpe); the product/version explanation remains available.
Always read top-level evaluated_at, kev_source, and each evaluation's status, complete, reason, source, total and findings. status is matched, no_match or indeterminate. HTTP 200 can include incomplete or indeterminate evaluations. kev: null means unknown, not false. Only a complete no_match describes a completed negative catalogue lookup; even that is not a security assessment of the asset.
Invalid input/reference returns 422, a forbidden raw-CPE request 403, and reference lookup failure may return 503. Check the HTTP status and error code rather than retrying an invalid reference indefinitely.
Badge evidence and related searches
POST /enrich/badges adds contextual badges to returned result items without a search charge. A badge may contain an optional search object with field, value, match (exact, prefix, suffix), query and datasets. This represents the indexed criterion supporting that badge; it is not an exact query for the badge's display label.
Its body is {"items":[{"key":"row-1","type":"host","value":"example.com"}]}. Up to 50 items fit in a 256 KiB request; keys must be unique and at most 256 UTF-8 bytes. Supported item types are host, domain, ip, cert, whois and dns. An optional record object (at most 4 KiB) is accepted for compatibility but does not become trusted evidence. At most two enrichment batches per account can run concurrently across surfaces; a third receives 429 background_busy.
Use the supplied query only when the user chooses to start a related search. That search has normal credit, dataset and field restrictions. Do not invent tag:<badge-id> syntax. Some historical, privacy or combined evidence has no supported selector; an absent search is intentional. Inspect partial before treating an absent badge as a negative conclusion.