diff --git a/client/openapi/trustd.yaml b/client/openapi/trustd.yaml index fb5235dd5..fe964da9e 100644 --- a/client/openapi/trustd.yaml +++ b/client/openapi/trustd.yaml @@ -5,7 +5,7 @@ info: license: name: Apache License, Version 2.0 identifier: Apache-2.0 - version: 0.5.0-rc.1 + version: 0.6.0-rc.1 paths: /.well-known/trustify: get: @@ -325,6 +325,7 @@ paths: - osv - csaf - cve + - nvd - spdx - cyclonedx - clearlydefinedcuration @@ -1036,6 +1037,148 @@ paths: description: Uploaded the dataset '400': description: The file could not be parsed as an dataset + /api/v3/exploit-intelligence/analyze: + post: + tags: + - exploit-intelligence + summary: Trigger an Exploit Intelligence analysis for a CVE against an SBOM. + description: |- + Creates a job record that the background worker will pick up and + process. Returns immediately after persisting the job. + operationId: analyzeExploitIntelligence + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AnalyzeRequest' + required: true + responses: + '200': + description: Active analysis job already exists + content: + application/json: + schema: + $ref: '#/components/schemas/AnalyzeResponse' + '201': + description: Analysis job created + content: + application/json: + schema: + $ref: '#/components/schemas/AnalyzeResponse' + '404': + description: SBOM not found + '503': + description: Exploit Intelligence service not configured + /api/v3/exploit-intelligence/jobs: + get: + tags: + - exploit-intelligence + summary: List Exploit Intelligence analysis jobs. + operationId: listExploitIntelligenceJobs + parameters: + - name: q + in: query + description: | + Query for advisories defined using the following EBNF grammar (ISO/IEC 14977): + ```text + (* Query Grammar - EBNF Compliant *) + query = ( values | filter ) , { "&" , query } ; + values = value , { "|" , value } ; + filter = field , operator , values ; + operator = "=" | "!=" | "~" | "!~" | ">=" | ">" | "<=" | "<" ; + field = ("id" | "sbom_id" | "vulnerability_id" | "status" | "created" | "updated") + value = { value_char } ; + value_char = escaped_char | normal_char ; + escaped_char = "\" , special_char ; + normal_char = ? any character except '&', '|', '=', '!', '~', '>', '<', '\' ? ; + special_char = "&" | "|" | "=" | "!" | "~" | ">" | "<" | "\" ; + ``` + Examples: + - Simple filter: title=example + - Multiple values filter: title=foo|bar|baz + - Complex filter: modified>2024-01-01 + - Combined query: title=foo&average_severity=high + - Escaped characters: title=foo\\&bar + required: false + schema: + type: string + - name: sort + in: query + description: |- + EBNF grammar for the _sort_ parameter: + ```text + sort = field [ ':', order ] { ',' sort } + order = ( "asc" | "desc" ) + field = ("id" | "sbom_id" | "vulnerability_id" | "status" | "created" | "updated") + ``` + The optional _order_ should be one of "asc" or "desc". If + omitted, the order defaults to "asc". + + Each _field_ name must correspond to one of the columns of the + table holding the entities being queried. Those corresponding + to JSON objects in the database may use a ':' to delimit the + column name and the object key, + e.g. `purl:qualifiers:type:desc` + required: false + schema: + type: string + - name: offset + in: query + description: |- + The first item to return, skipping all that come before it. + + NOTE: The order of items is defined by the API being called. + required: false + schema: + type: integer + format: int64 + minimum: 0 + - name: limit + in: query + description: |- + The maximum number of entries to return. + + Zero means: return no items (the total count is still computed if requested). + required: false + schema: + type: integer + format: int64 + minimum: 0 + - name: total + in: query + description: Whether to compute and return the total count of matching items. + required: false + schema: + type: boolean + responses: + '200': + description: List of analysis jobs + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedResults_ExploitIntelligenceJobSummary' + /api/v3/exploit-intelligence/jobs/{id}: + get: + tags: + - exploit-intelligence + summary: Get details of a specific Exploit Intelligence analysis job. + operationId: getExploitIntelligenceJob + parameters: + - name: id + in: path + description: Job identifier + required: true + schema: + type: string + responses: + '200': + description: Job details + content: + application/json: + schema: + $ref: '#/components/schemas/ExploitIntelligenceJobDetails' + '404': + description: Job not found /api/v3/group/sbom: get: tags: @@ -2731,6 +2874,7 @@ paths: - osv - csaf - cve + - nvd - spdx - cyclonedx - clearlydefinedcuration @@ -4343,6 +4487,34 @@ components: cache: $ref: '#/components/schemas/CacheStatusDetails' description: Details about the cache + AnalyzeRequest: + type: object + description: Request body for triggering an Exploit Intelligence analysis. + required: + - sbom_id + - vulnerability_id + properties: + sbom_id: + type: string + format: uuid + description: The SBOM identifier to analyze. + vulnerability_id: + type: string + description: The vulnerability identifier (e.g., "CVE-2024-9680"). + AnalyzeResponse: + type: object + description: Response returned when an analysis job is successfully created. + required: + - job_id + - status + properties: + job_id: + type: string + format: uuid + description: The unique job identifier. + status: + $ref: '#/components/schemas/ExploitIntelligenceJobStatus' + description: Current lifecycle status of the job. BasePurlDetails: allOf: - $ref: '#/components/schemas/BasePurlHead' @@ -4563,6 +4735,54 @@ components: period: type: string description: The period the importer should be run. + ComponentResult: + type: object + description: Per-component analysis result within an analysis job. + required: + - id + - component_ref + - status + - excluded + - created + - updated + properties: + advisory_id: + type: + - string + - 'null' + format: uuid + description: FK to advisory — set when a VEX document is ingested from the result. + component_ref: + type: string + description: Identifier of the component (purl or container image reference). + created: + type: string + description: Timestamp when the component record was created. + excluded: + type: boolean + description: |- + Whether this component was excluded by the EI service (e.g., + unsupported ecosystem) rather than genuinely failing. + finding: + oneOf: + - type: 'null' + - $ref: '#/components/schemas/ExploitIntelligenceFinding' + description: Analysis result from Exploit Intelligence, if completed. + id: + type: string + format: uuid + description: The unique component record identifier. + report_url: + type: + - string + - 'null' + description: Link to the EI human-readable justification report for this component. + status: + $ref: '#/components/schemas/ExploitIntelligenceJobStatus' + description: Current lifecycle status of this component's analysis. + updated: + type: string + description: Timestamp when the component record was last updated. Cpe: type: string format: uri @@ -4639,6 +4859,206 @@ components: message: type: string description: A human-readable error message + ExploitIntelligenceFinding: + type: string + description: |- + Analysis finding from the Exploit Intelligence service. + + Represents the outcome of a vulnerability analysis for a given component/CVE pair. + enum: + - vulnerable + - not_vulnerable + - uncertain + ExploitIntelligenceJobDetails: + type: object + description: Detailed view of an Exploit Intelligence analysis job. + required: + - id + - sbom_id + - vulnerability_id + - status + - components + - created + - updated + properties: + completed_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components (computed at query time, not stored). + components: + type: array + items: + $ref: '#/components/schemas/ComponentResult' + description: Per-component analysis results (populated for multi-component jobs). + created: + type: string + description: Timestamp when the job was created. + excluded_components: + type: + - integer + - 'null' + format: int32 + description: Number of components excluded by the EI service (computed at query time, not stored). + failed_components: + type: + - integer + - 'null' + format: int32 + description: Number of genuinely failed components (computed at query time, not stored). + finding: + oneOf: + - type: 'null' + - $ref: '#/components/schemas/ExploitIntelligenceFinding' + description: Analysis result computed from component findings. + id: + type: string + format: uuid + description: The unique job identifier. + not_vulnerable_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components with NotVulnerable finding (computed at query time). + product_id: + type: + - string + - 'null' + description: EI product ID for multi-component SPDX flow. + report_url: + type: + - string + - 'null' + description: Link to the EI human-readable justification report. + sbom_id: + type: string + format: uuid + description: FK to the SBOM being analysed. + status: + $ref: '#/components/schemas/ExploitIntelligenceJobStatus' + description: Current lifecycle status of the job. + total_components: + type: + - integer + - 'null' + format: int32 + description: Total components in the product. + uncertain_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components with Uncertain finding (computed at query time). + updated: + type: string + description: Timestamp when the job was last updated. + vulnerability_id: + type: string + description: CVE identifier. + vulnerable_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components with Vulnerable finding (computed at query time). + ExploitIntelligenceJobStatus: + type: string + description: Lifecycle status of an Exploit Intelligence analysis job. + enum: + - pending + - running + - completed + - failed + ExploitIntelligenceJobSummary: + type: object + description: Summary of an Exploit Intelligence analysis job. + required: + - id + - sbom_id + - vulnerability_id + - status + - created + - updated + properties: + completed_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components (computed at query time, not stored). + created: + type: string + description: Timestamp when the job was created. + excluded_components: + type: + - integer + - 'null' + format: int32 + description: Number of components excluded by the EI service (computed at query time, not stored). + failed_components: + type: + - integer + - 'null' + format: int32 + description: Number of genuinely failed components (computed at query time, not stored). + finding: + oneOf: + - type: 'null' + - $ref: '#/components/schemas/ExploitIntelligenceFinding' + description: Analysis result from Exploit Intelligence. + id: + type: string + format: uuid + description: The unique job identifier. + not_vulnerable_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components with NotVulnerable finding (computed at query time). + product_id: + type: + - string + - 'null' + description: EI product ID for multi-component SPDX flow. + report_url: + type: + - string + - 'null' + description: Link to the EI human-readable justification report. + sbom_id: + type: string + format: uuid + description: FK to the SBOM being analysed. + status: + $ref: '#/components/schemas/ExploitIntelligenceJobStatus' + description: Current lifecycle status of the job. + total_components: + type: + - integer + - 'null' + format: int32 + description: Total components in the product. + uncertain_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components with Uncertain finding (computed at query time). + updated: + type: string + description: Timestamp when the job was last updated. + vulnerability_id: + type: string + description: CVE identifier. + vulnerable_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components with Vulnerable finding (computed at query time). ExternalReferenceQuery: type: object properties: @@ -4692,6 +5112,7 @@ components: - osv - csaf - cve + - nvd - spdx - cyclonedx - clearlydefinedcuration @@ -4806,6 +5227,12 @@ components: properties: cve: $ref: '#/components/schemas/CveImporter' + - type: object + required: + - nvd + properties: + nvd: + $ref: '#/components/schemas/NvdImporter' - type: object required: - clearlyDefined @@ -5016,6 +5443,37 @@ components: items: type: string description: Warnings when processing this node. + NvdImporter: + allOf: + - $ref: '#/components/schemas/CommonImporter' + - type: object + properties: + source: + type: string + description: |- + The base URL of the GitHub repository publishing NVD data as per-year + release assets (`CVE-.json.xz` + `.meta`), in the NVD-API JSON + schema. The latest release is always used. + startYear: + type: + - integer + - 'null' + format: int32 + description: |- + The first feed year to import when `years` is empty; all years from + here through the current year are imported. Defaults to 1999, the + first year with NVD data. + minimum: 0 + years: + type: array + items: + type: integer + format: int32 + minimum: 0 + description: |- + An explicit set of feed years to import. When non-empty, exactly these + years are imported and `start_year` is ignored. + uniqueItems: true OrganizationDetails: allOf: - $ref: '#/components/schemas/OrganizationHead' @@ -5135,6 +5593,107 @@ components: - 'null' format: int64 minimum: 0 + PaginatedResults_ExploitIntelligenceJobSummary: + type: object + required: + - items + properties: + items: + type: array + items: + type: object + description: Summary of an Exploit Intelligence analysis job. + required: + - id + - sbom_id + - vulnerability_id + - status + - created + - updated + properties: + completed_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components (computed at query time, not stored). + created: + type: string + description: Timestamp when the job was created. + excluded_components: + type: + - integer + - 'null' + format: int32 + description: Number of components excluded by the EI service (computed at query time, not stored). + failed_components: + type: + - integer + - 'null' + format: int32 + description: Number of genuinely failed components (computed at query time, not stored). + finding: + oneOf: + - type: 'null' + - $ref: '#/components/schemas/ExploitIntelligenceFinding' + description: Analysis result from Exploit Intelligence. + id: + type: string + format: uuid + description: The unique job identifier. + not_vulnerable_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components with NotVulnerable finding (computed at query time). + product_id: + type: + - string + - 'null' + description: EI product ID for multi-component SPDX flow. + report_url: + type: + - string + - 'null' + description: Link to the EI human-readable justification report. + sbom_id: + type: string + format: uuid + description: FK to the SBOM being analysed. + status: + $ref: '#/components/schemas/ExploitIntelligenceJobStatus' + description: Current lifecycle status of the job. + total_components: + type: + - integer + - 'null' + format: int32 + description: Total components in the product. + uncertain_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components with Uncertain finding (computed at query time). + updated: + type: string + description: Timestamp when the job was last updated. + vulnerability_id: + type: string + description: CVE identifier. + vulnerable_components: + type: + - integer + - 'null' + format: int32 + description: Number of completed components with Vulnerable finding (computed at query time). + total: + type: + - integer + - 'null' + format: int64 + minimum: 0 PaginatedResults_GroupDetails: type: object required: