chore(openapi): [main] update client/openapi/trustd.yaml

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: |-