diff --git a/api/spec/scanner-adapter-openapi-v1.2.yaml b/api/spec/scanner-adapter-openapi-v1.2.yaml index a690cf5..674a057 100644 --- 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 index feb5b35..a3f8d7f 100644 --- 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": "", - "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,6 +118,7 @@ components: generated_at: type: string format: 'date-time' + description: 'The time of the report generated.' artifact: $ref: '#/components/schemas/Artifact' scanner: @@ -106,14 +126,16 @@ components: 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" + ] + } } ], ```