CVEs v2 (Threat Intelligence) Integration Guide

Overview

The CVEs v2 integration connects your NINA workflows to the internal Threat Intelligence (TI) API for searching vulnerabilities (/ti/vulnerabilities) and CPE software entries (/ti/software).

It supersedes the original CVEs integration with a new contract:

• No authentication — the service is reachable in-cluster
• Cursor-based pagination — pass the cursor_value returned by the previous response to retrieve the next page
• Flat snake_case filters — filters are top-level parameters, not nested under a filters object
• Richer filter set — boolean flags, score thresholds, ISO 8601 date ranges, exploit sources, and label-based filtering

This integration is intended for security operations, vulnerability management, and threat assessment workflows running inside the cluster.

Credential Configuration

This integration requires no authentication — only a base URL for the TI service.

Authentication Method

Field	Description	Example
Domain	TI API base URL	https://ti.internal.example.com

How to obtain your Domain:

1. Contact your organization's security administrator for in-cluster access
2. Request the internal Threat Intelligence API domain
3. Ensure network access to the service (internal)

Creating a CVEs v2 Credential

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in the credential details:
   • Name: A descriptive name (e.g., "TI API Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "CVEs v2 (Threat Intelligence)"
   • Auth Type: "No Authentication" (automatically selected)
   • Domain: Enter the TI API base URL (include https://)
4. Click Test Connection to verify the endpoint is reachable
5. Click Save to store the credential

Supported Resources and Operations

Vulnerability

Operation	Description
List Vulnerabilities	Cursor-paginated list of vulnerabilities with optional filters

CPEs

Operation	Description
Search CPEs	Cursor-paginated search of CPE software entries with optional filters

Parameter Merging

The CVEs v2 integration uses NINA's standard parameter merging.

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the integration node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

The integration only extracts parameters whose keys match its schema — anything else in the input is ignored.

Pagination

Both operations use cursor-based pagination.

• page_size — number of items per page (1–100, default 20)
• cursor — opaque cursor returned by the previous response as cursor_value. Omit on the first page; pass the previous cursor_value to fetch the next page.

When the response contains no cursor_value (or it is empty), you have reached the end of the result set.

Example: Listing Vulnerabilities

Basic List (First Page)

{
  "resource": "vulnerability",
  "operation": "list",
  "parameters": {
    "page_size": 20
  }
}

Fetching the Next Page

{
  "resource": "vulnerability",
  "operation": "list",
  "parameters": {
    "page_size": 20,
    "cursor": "eyJwYWdlIjoyfQ=="
  }
}

Filter by Name and Labels

{
  "resource": "vulnerability",
  "operation": "list",
  "parameters": {
    "name_in": ["CVE-2024-40711", "CVE-2021-44228"],
    "labels_in": ["critical", "patched"]
  }
}

Filter for Exploitable + KEV-Listed CVEs

{
  "resource": "vulnerability",
  "operation": "list",
  "parameters": {
    "has_exploit": true,
    "is_cisa_kev": true,
    "exploit_sources_in": ["exploit:metasploit", "exploit:exploitdb"],
    "cvss_v3__score_gte": 9.0,
    "epss_score_gte": 0.9
  }
}

Filter by Date Range and Vector

{
  "resource": "vulnerability",
  "operation": "list",
  "parameters": {
    "published_at_gte": "2024-01-01T00:00:00Z",
    "published_at_lte": "2024-12-31T23:59:59Z",
    "cvss_v3__vector_string_contains": ["AV:N", "PR:N"],
    "is_patched": false
  }
}

Keyword Search

{
  "resource": "vulnerability",
  "operation": "list",
  "parameters": {
    "keywords_in": ["remote code execution", "apache"],
    "cvss_v3__score_gte": 7.0
  }
}

Example: Searching CPEs

Basic Search by Vendor and Name

{
  "resource": "cpes",
  "operation": "search",
  "parameters": {
    "vendor_in": ["microsoft"],
    "name_in": ["windows"],
    "is_vulnerable": true,
    "page_size": 50
  }
}

Substring Search

{
  "resource": "cpes",
  "operation": "search",
  "parameters": {
    "vendor_contains": "apache",
    "name_contains": "tomcat",
    "version_contains": "8.5"
  }
}

Filter by CPE Substrings

{
  "resource": "cpes",
  "operation": "search",
  "parameters": {
    "cpe_contains": [
      "cpe:2.3:a:apache:http_server",
      "cpe:2.3:a:nginx:nginx"
    ],
    "is_vulnerable": true
  }
}

Pagination Loop

{
  "resource": "cpes",
  "operation": "search",
  "parameters": {
    "page_size": 100,
    "cursor": "<cursor_value from previous response>"
  }
}

Response Structure

Both operations return the same paginated envelope:

{
  "items": [ /* operation-specific objects */ ],
  "total": 1234,
  "cursor_value": "<opaque string or null>"
}

• items — array of result objects (vulnerability or CPE software entries)
• total — total number of matching records on the server
• cursor_value — opaque cursor for the next page; absent or empty when no more results

Item shapes are defined by the TI API contract and may evolve. Treat unknown fields as opaque and forward them through your workflow.

Available Parameters

Vulnerability — List

Parameter	Type	Description	Required	Default
cursor	string	Opaque cursor from a previous cursor_value	No	-
page_size	number	Results per page (1–100)	No	20
name_in	array	Filter by any of the provided vulnerability names	No	-
labels_in	array	Filter by any of the provided labels	No	-
has_exploit	boolean	true requires the has-exploit label	No	-
is_patched	boolean	true requires the patched label	No	-
is_cisa_kev	boolean	Filter by CISA KEV membership	No	-
exploit_sources_in	array	Filter by exploit source. Enum: exploit:nuclei, exploit:poc-github, exploit:metasploit, exploit:feedly, exploit:exploitdb	No	-
published_at_gte	string	Minimum publication date (inclusive, ISO 8601)	No	-
published_at_lte	string	Maximum publication date (inclusive, ISO 8601)	No	-
cisa_kev_added_at_gte	string	Minimum CISA KEV added date (inclusive, ISO 8601)	No	-
cisa_kev_added_at_lte	string	Maximum CISA KEV added date (inclusive, ISO 8601)	No	-
epss_score_gte	number	Minimum EPSS score (0.0–1.0)	No	-
cvss_v2__score_gte	number	Minimum CVSS v2 score	No	-
cvss_v3__score_gte	number	Minimum CVSS v3 score	No	-
cvss_v4__score_gte	number	Minimum CVSS v4 score	No	-
cvss_v3__vector_string_contains	array	CVSS v3 vector substrings (repeat for multiple, OR logic)	No	-
keywords_in	array	Keywords matched against the description (repeat for multiple, AND logic)	No	-

CPEs — Search

Parameter	Type	Description	Required	Default
cursor	string	Opaque cursor from a previous cursor_value	No	-
page_size	number	Results per page (1–100)	No	20
name_in	array	Filter by software names	No	-
vendor_in	array	Filter by vendor names	No	-
labels_in	array	Filter by labels	No	-
cpe_contains	array	Filter by CPE substrings (repeat for multiple, OR logic)	No	-
vendor_contains	string	Vendor substring (case-insensitive)	No	-
name_contains	string	Name substring (case-insensitive)	No	-
version_contains	string	Version substring (case-insensitive)	No	-
is_vulnerable	boolean	true returns only software entries with known vulnerabilities	No	-

Filter Behavior

• Omitted parameters and empty arrays ([]) are silently ignored — the filter is not applied.
• Array filters (*_in, *_contains) use repeat-style query parameters: each element is sent as its own query value. Comma-joined strings are not parsed — pass actual arrays.
• Multiple filters are combined with AND logic. Within a single array-valued filter, the values are typically combined with OR logic (any match), except where explicitly noted (keywords_in uses AND).

Integration in Workflow Context

Common patterns where CVEs v2 fits naturally:

1. Vulnerability Triage Schedule Node → CVEs v2 (vulnerability.list, is_cisa_kev=true, has_exploit=true) → Script Node (rank by EPSS + CVSS) → Slack/Email notification.

2. Asset Exposure Assessment Asset Inventory Node → CVEs v2 (cpes.search, is_vulnerable=true) → Script Node (join with assets) → Jira Integration Node (create tickets).

3. Continuous Page Walk Loop Node → CVEs v2 with cursor from previous step → terminate when cursor_value is empty.

Troubleshooting

Issue	Resolution
Connection timeout / unreachable	Verify the Domain URL, that it includes https://, and that the worker has in-cluster access to the TI service.
page_size must be between 1 and 100	Adjust page_size to a value within [1, 100].
Empty items with non-empty filters	Confirm filter values are not over-constraining — try removing one filter at a time. Remember that omitted/empty arrays are no-ops.
Array filter not applied	Make sure you pass an actual JSON array, not a comma-separated string. The integration uses repeat-style query parameters.
cursor_value keeps appearing	Pagination continues until cursor_value is empty or absent. Pass it back as cursor to fetch the next page.
invalid request parameters	The upstream returned HTTP 422. Check your date formats (ISO 8601 date-time), numeric ranges, and enum values for exploit_sources_in.
upstream service unavailable	The TI API returned 5xx or could not be reached. Retry with backoff; escalate to the security team if it persists.
Slow responses on large pages	Reduce page_size and paginate via cursor instead of requesting a single large page.

Updated: 2026-05-14