Merge pull request #17 from zyyw/update-spec-1.2

feat: update ScannerCapability, enabled_capabilities, HarborSbomRepor…
goharbor · Jan 17, 2024 · 7aad47c · 7aad47c
2 parents c976ec6 + 9028fef
commit 7aad47c
Show file tree

Hide file tree

Showing 2 changed files with 103 additions and 33 deletions.
diff --git a/api/spec/scanner-adapter-openapi-v1.2.yaml b/api/spec/scanner-adapter-openapi-v1.2.yaml
@@ -10,7 +10,7 @@ info:
 
     The [/scan](#operation/AcceptScanRequest) operation is asynchronous. It should enqueue the job for processing a scan request and return the identifier. This allows Harbor to poll a corresponding scan report with the
     [/scan/{scan_request_id}/report](#operation/GetScanReport) operation. Harbor will call the
-    [/scan/{scan_request_id}/report](#operation/GetScanReport) operation periodically periodically until it returns 200 or 500 status codes.
+    [/scan/{scan_request_id}/report](#operation/GetScanReport) operation periodically until it returns 200 or 500 status codes.
 
     The [/metadata](#operation/GetMetadata) operation allows a Harbor admin to configure and register a scanner
     and discover its capabilities.
@@ -134,6 +134,15 @@ paths:
           schema:
             type: string
           example: "application/vnd.security.vulnerability.report; version=1.1"
+        - name: sbom_media_type
+          in: query
+          description: media_type specifies the format of SBOM to be retrieved from the scanner adapter, it should either SPDX SBOM or CycloneDX
+          required: false
+          schema: 
+            type: string
+          enum:
+            - application/spdx+json
+            - application/vnd.cyclonedx+json
       responses:
         200:
           description: Scan report
@@ -161,6 +170,13 @@ paths:
               description: Indicates the interval after which the request should be retried.
               schema:
                 type: integer
+        400:
+          description: Bad request from the client to query report of a "/scan" request. For example, querying SBOM generation report, but not passing
+            query parameter (?sbom_media_type=xxx), or the key/value of the query parameter is not valid, it should return 400.
+          content:
+            "application/vnd.scanner.adapter.error+json; version=1.0":
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
         404:
           description: Cannot find the corresponding scan request identifier
         500:
@@ -226,13 +242,19 @@ components:
                 ],
                 "produces_mime_types": [
                   "application/vnd.security.sbom.report+json; version=1.0"
-                ]
+                ],
+                "additional_attributes": {
+                  "sbom_media_types": [
+                    "application/spdx+json",
+                    "application/vnd.cyclonedx+json"
+                  ]
+                }
               }
             ]
         properties:
           $ref: "#/components/schemas/ScannerProperties"
       description: |
-        Represents metadata of a Scanner Adapter which allows Harbor to lookup a scanner capable
+        Represents metadata of a Scanner Adapter which allows Harbor to lookup a scanner capabilities
         of scanning a given Artifact stored in its registry and making sure that it
         can interpret a returned result.
     ScannerProperties:
@@ -296,6 +318,16 @@ components:
             The set of MIME types of reports generated by the scanner for the consumes_mime_types of the same capability record.
           example:
             - "application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0"
+        additional_attributes:
+          type: object
+          descriptions: The additional attributes for scanner capabilities. If the type is sbom, then it returns supported media types of the SBOM format.
+          example: |
+            {
+              "sbom_media_types": [
+                "application/spdx+json",
+                "application/vnd.cyclonedx+json"
+              ]
+            }            
     ScanRequest:
       required:
         - registry
@@ -332,10 +364,15 @@ components:
                 example:
                   - "application/vnd.security.sbom.report+json; version=1.0"
               parameters:
-                oneOf:
-                - $ref: '#/components/schemas/SbomParameters'
-                description: The additional parameters for the scan request, for the SBOM type, harbor will carry with `accept_media_type` to specify the expected format for SBOM content.
-                example: '{"accept_media_type": "application/spdx+json"}'
+                $ref: '#/components/schemas/SbomParameters'
+                description: The additional parameters for the scan request, for the SBOM type, harbor will carry with `sbom_media_types` to specify the expected formats for SBOM content.
+                example: | 
+                  {
+                    "sbom_media_types": [
+                      "application/spdx+json",
+                      "application/vnd.cyclonedx+json"
+                    ]
+                  }
     ScanResponse:
       required:
         - id
@@ -351,8 +388,13 @@ components:
     SbomParameters:
       type: object
       properties:
-        accept_media_type:
-          type: string
+        sbom_media_types:
+          type: array
+          items:
+            type: string
+            enum:
+              - application/spdx+json
+              - application/vnd.cyclonedx+json
     Registry:
       type: object
       properties:

diff --git a/data/spec/SBOM.md b/data/spec/SBOM.md
@@ -56,32 +56,51 @@
   },
   "media_type": "application/spdx+json",
   "sbom": {
-    "spdxVersion": "SPDX-2.3",
-    "dataLicense": "CC0-1.0",
     "SPDXID": "SPDXRef-DOCUMENT",
-    "name": "alpine:latest",
-    "documentNamespace": "<http://aquasecurity.github.io/trivy/container_image/alpine:latest-24fab3cb-05fa-479b-b3b7-f76151354cc3>",
-    "creationInfo":{
-      "licenseListVersion": "",
+    "creationInfo": {
+      "created": "2023-09-15T10:14:38.656763221Z",
       "creators": [
-        "Organization: aquasecurity",
-        "Tool: trivy-0.44.1"
-      ],
-      "created": "2023-09-22T07:41:04Z"
+        "Tool: trivy",
+        "Organization: aquasecurity"
+      ]
     },
+    "dataLicense": "CC0-1.0",
+    "documentDescribes": [
+      "SPDXRef-ContainerImage-54e420824b362b10"
+    ],
+    "documentNamespace": "http://aquasecurity.github.io/trivy/container_image/alpine:3.15.5-30b9a3c8-2321-4765-97ee-d533ada1ff01",
+    "name": "alpine:3.15.5",
     "packages": [
-        {
-          "name": "alpine",
-          "SPDXID": "SPDXRef-OperatingSystem-68bf9b9d283c287a",
-          "versionInfo": "3.18.3",
-          "downloadLocation": "NONE",
-          "copyrightText": "",
-          "primaryPackagePurpose": "OPERATING-SYSTEM"
-        },
-        ...
-    ]
-    ...
-    }
+      {
+        "SPDXID": "SPDXRef-ContainerImage-54e420824b362b10",
+        "attributionTexts": [
+          "SchemaVersion: 2",
+          "ImageID: sha256:2720e26172a023c7245fd2d59f06452cb3743e3c5a26dd102c6a2294e473cdcd",
+          "RepoDigest: alpine@sha256:0483110c51a764abe175a8cefb941541ca0bc0f628ce418d3a660338abf4622a",
+          "DiffID: sha256:ad543cd673bd9de2bac48599da992506dcc37a183179302ea934853aaa92cb84",
+          "RepoTag: alpine:3.15.5"
+        ],
+        "externalRefs": [
+          {
+            "referenceCategory": "PACKAGE-MANAGER",
+            "referenceLocator": "pkg:oci/alpine@sha256:0483110c51a764abe175a8cefb941541ca0bc0f628ce418d3a660338abf4622a?repository_url=index.docker.io%2Flibrary%2Falpine\u0026arch=amd64",
+            "referenceType": "purl"
+          }
+        ],
+        "filesAnalyzed": false,
+        "name": "alpine:3.15.5"
+      },
+      ...
+    ],
+    "relationships": [
+      {
+        "relatedSpdxElement": "SPDXRef-ContainerImage-54e420824b362b10",
+        "relationshipType": "DESCRIBES",
+        "spdxElementId": "SPDXRef-DOCUMENT"
+      },
+      ...
+    ],
+    "spdxVersion": "SPDX-2.2"
   }
 }
 
@@ -99,21 +118,24 @@ components:
         generated_at:
           type: string
           format: 'date-time'
+          description: 'The time of the report generated.'
         artifact:
           $ref: '#/components/schemas/Artifact'
         scanner:
           $ref: '#/components/schemas/Scanner'
         vendor_attributes:
           type: object
           additionalProperties: true
+          description: 'The additional attributes of the vendor.'
         media_type:
           type: string
           enum:
             - application/spdx+json
             - application/vnd.cyclonedx+json
+          description: 'The format of the sbom data.'
         sbom:
           type: object
-          additionalProperties: true
+          description: 'The raw data of the sbom generated by the scanner.'
 ```
 
 ## Statement
@@ -142,7 +164,13 @@ The capability to generate the SBOM from the container image, the process is sim
       ],
       "produces_mime_types": [
         "application/vnd.security.sbom.report+json; version=1.0"
-      ]
+      ],
+      "additional_attributes": {
+        "sbom_media_types": [
+          "application/spdx+json",
+          "application/vnd.cyclonedx+json"
+        ]
+      }
     }
   ],
 ```