diff --git a/client/openapi/trustd.yaml b/client/openapi/trustd.yaml index 88f88990b..3f06a8519 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: @@ -331,6 +331,7 @@ paths: - clearlydefinedcuration - clearlydefined - cwecatalog + - cisakev - advisory - sbom - unknown @@ -1037,6 +1038,125 @@ paths: description: Uploaded the dataset '400': description: The file could not be parsed as an dataset + /api/v3/exploit: + get: + tags: + - exploit + summary: List exploit entries + description: |- + Source-specific fields can be filtered through the JSON syntax of the query + language, e.g. `q=metadata:known_ransomware_campaign_use=Known`. + operationId: listExploits + parameters: + - name: q + in: query + description: | + EBNF grammar for the _q_ parameter: + ```text + q = ( values | filter ) { '&' q } + values = value { '|', values } + filter = field, operator, values + operator = "=" | "!=" | "~" | "!~" | ">=" | ">" | "<=" | "<" + value = (* any text but escape special characters with '\' *) + field = (* must match an entity attribute name *) + ``` + Any values in a _q_ will result in a case-insensitive "full + text search", effectively producing an OR clause of LIKE + clauses for every string-ish field in the resource being + queried. + + Examples: + - `foo` - any field containing 'foo' + - `foo|bar` - any field containing either 'foo' OR 'bar' + - `foo&bar` - some field contains 'foo' AND some field contains 'bar' + + A _filter_ may also be used to constrain the results. The + filter's field name must correspond to one of the resource's + attributes. If it doesn't, an error will be returned + containing a list of the valid fields for that resource. + + An ASCII value of `NUL`, percent-encoded as `%00`, may be used + to find resources on which a particular field isn't set. For + example, `name=%00` and `name!=%00` yield the WHERE clauses, + 'NAME IS NULL' and 'NAME IS NOT NULL', respectively. + + Examples: + - `name=foo` - entity's _name_ matches 'foo' exactly + - `name~foo` - entity's _name_ contains 'foo', case-insensitive + - `name~foo|bar` - entity's _name_ contains either 'foo' OR 'bar', case-insensitive + - `name=` - entity's _name_ is the empty string, '' + - `name=%00` - entity's _name_ isn't set + - `published>3 days ago` - date values can be "human time" + + Multiple full text searches and/or filters should be + '&'-delimited -- they are logically AND'd together. + + - `red hat|fedora&labels:type=cve|osv&published>last wednesday 17:00` + + Fields corresponding to JSON objects in the database may use a + ':' to delimit the column name and the object key, + e.g. `purl:qualifiers:type=pom` + + Any operator or special character, e.g. '|', '&', within a + value should be escaped by prefixing it with a backslash. + 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 = (* must match the name of entity's attributes *) + ``` + 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: Matching exploit entries + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedResults_Exploit' /api/v3/exploit-intelligence/analyze: post: tags: @@ -1179,6 +1299,27 @@ paths: $ref: '#/components/schemas/ExploitIntelligenceJobDetails' '404': description: Job not found + /api/v3/exploit/{id}: + get: + tags: + - exploit + summary: Retrieve an exploit entry + operationId: getExploit + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: The exploit entry + content: + application/json: + schema: + $ref: '#/components/schemas/Exploit' + '404': + description: The exploit entry could not be found /api/v3/group/sbom: get: tags: @@ -2880,6 +3021,7 @@ paths: - clearlydefinedcuration - clearlydefined - cwecatalog + - cisakev - advisory - sbom - unknown @@ -4859,6 +5001,48 @@ components: message: type: string description: A human-readable error message + Exploit: + type: object + description: |- + An assertion by some source that a vulnerability is exploited in the wild, + or that working exploit code for it exists. + + The named fields are those every source can be expected to carry; everything + specific to one source is in `metadata`. For CISA KEV, that is + `vendor_project`, `product`, `vulnerability_name`, `short_description`, + `required_action`, `known_ransomware_campaign_use`, `notes` and `cwes`. + required: + - id + - source + - cve_id + - date_reported + - remediation_due_date + - metadata + properties: + cve_id: + type: string + description: The vulnerability this entry refers to. + date_reported: + type: + - string + - 'null' + format: date + description: The date the source first reported the exploitation. + id: + type: string + description: Opaque identifier of this entry, stable across resyncs of the source. + metadata: + type: object + description: Structured data specific to the reporting source. + remediation_due_date: + type: + - string + - 'null' + format: date + description: The date by which the source mandates remediation, if it mandates one. + source: + type: string + description: The source that reported the exploitation (e.g. "cisa-kev"). ExploitIntelligenceFinding: type: string description: |- @@ -5118,6 +5302,7 @@ components: - clearlydefinedcuration - clearlydefined - cwecatalog + - cisakev - advisory - sbom - unknown @@ -5251,6 +5436,12 @@ components: properties: cwe: $ref: '#/components/schemas/CweImporter' + - type: object + required: + - kev + properties: + kev: + $ref: '#/components/schemas/KevImporter' - type: object required: - quay @@ -5341,6 +5532,25 @@ components: items: type: string description: Warnings that occurred during the import process + KevImporter: + allOf: + - $ref: '#/components/schemas/CommonImporter' + description: Common importer options. + - type: object + properties: + catalog: + type: + - string + - 'null' + description: |- + Catalog source identifier under which the imported entries are stored + (and replaced on each run). Defaults to "cisa-kev". + source: + type: string + description: URL of the catalog document to import. + description: |- + Importer configuration for known-exploited-vulnerability catalogs + (e.g. CISA KEV). Labels: type: object additionalProperties: @@ -5593,6 +5803,61 @@ components: - 'null' format: int64 minimum: 0 + PaginatedResults_Exploit: + type: object + required: + - items + properties: + items: + type: array + items: + type: object + description: |- + An assertion by some source that a vulnerability is exploited in the wild, + or that working exploit code for it exists. + + The named fields are those every source can be expected to carry; everything + specific to one source is in `metadata`. For CISA KEV, that is + `vendor_project`, `product`, `vulnerability_name`, `short_description`, + `required_action`, `known_ransomware_campaign_use`, `notes` and `cwes`. + required: + - id + - source + - cve_id + - date_reported + - remediation_due_date + - metadata + properties: + cve_id: + type: string + description: The vulnerability this entry refers to. + date_reported: + type: + - string + - 'null' + format: date + description: The date the source first reported the exploitation. + id: + type: string + description: Opaque identifier of this entry, stable across resyncs of the source. + metadata: + type: object + description: Structured data specific to the reporting source. + remediation_due_date: + type: + - string + - 'null' + format: date + description: The date by which the source mandates remediation, if it mandates one. + source: + type: string + description: The source that reported the exploitation (e.g. "cisa-kev"). + total: + type: + - integer + - 'null' + format: int64 + minimum: 0 PaginatedResults_ExploitIntelligenceJobSummary: type: object required: @@ -7344,12 +7609,20 @@ components: - type: object required: - advisories + - exploits properties: advisories: type: array items: $ref: '#/components/schemas/VulnerabilityAdvisorySummary' description: Advisories addressing this vulnerability, if any. + exploits: + type: array + items: + $ref: '#/components/schemas/Exploit' + description: |- + Reports that this vulnerability is exploited, or that working exploit + code for it exists (e.g. from the CISA KEV catalog), if any. scores: $ref: '#/components/schemas/RequestedField_Vec_Vec_ScoredVector' description: |-