Skip to main content

Search and vulnerability associations

Availability and authentication​

Catalogue associations

CVE/KEV selectors, observed_products explanations and badge search criteria are described in the personal OpenAPI contract. These searches use existing observations and catalogue associations; they do not confirm a vulnerability or start a scan.

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 example searches existing observations. 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:

SelectorMeaning
cve:CVE-2021-41773Association with this catalogue advisory
cve:CVE-2024-*Associations with advisories under this CVE prefix
cve:*At least one catalogue CVE association
kev:trueAt least one associated advisory in the available KEV catalogue
kev:falseNegative 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.

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.