openapi: 3.0.0 info: title: Harbor Scanner Adapter API description: | ## Overview This API must be implemented in order to register a new artifact scanner in [Harbor](https://goharbor.io) registry. The [/scan](#operation/AcceptScanRequest) and [/scan/{scan_request_id}/report](#operation/GetScanReport) operations are responsible for the actual scanning and return a scan report that is visible in the Harbor web console. 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. The [/metadata](#operation/GetMetadata) operation allows a Harbor admin to configure and register a scanner and discover its capabilities. ## Supported consumed MIME types - `application/vnd.oci.image.manifest.v1+json` - `application/vnd.docker.distribution.manifest.v2+json` ## Supported produced MIME types - `application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0` - `application/vnd.scanner.adapter.vuln.report.raw` contact: email: cncf-harbor-maintainers@lists.cncf.io license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: "1.0" servers: - url: /api/v1 security: - BasicAuth: [] - BearerAuth: [] paths: /metadata: get: tags: - Scanner summary: Get scanner metadata description: | Used to fetch scanner's metadata and capabilities. The operation is invoked to build an index of scanners capable of analysing a given type of artifacts and making sure that scan reports can be parsed and rendered. operationId: GetMetadata responses: 200: description: Scanner's metadata and capabilities content: "application/vnd.scanner.adapter.metadata+json; version=1.0": schema: $ref: '#/components/schemas/ScannerAdapterMetadata' 500: description: Internal server error content: "application/vnd.scanner.adapter.error+json; version=1.0": schema: $ref: '#/components/schemas/ErrorResponse' /scan: post: tags: - Scanner summary: Accept artifact scanning request description: | A non-blocking operation which enqueues a scan job and returns immediately. It returns a unique identifier which can be used to poll for generated scan reports by Harbor. operationId: AcceptScanRequest requestBody: description: | Contains data required to pull the given artifact and save it for scanning in the file system or any other location accessible to the scanner. content: "application/vnd.scanner.adapter.scan.request+json; version=1.0": schema: $ref: '#/components/schemas/ScanRequest' responses: 202: description: Scan request accepted content: "application/vnd.scanner.adapter.scan.response+json; version=1.0": schema: $ref: "#/components/schemas/ScanResponse" 400: description: Received invalid JSON or the wrong type of JSON values content: "application/vnd.scanner.adapter.error+json; version=1.0": schema: $ref: "#/components/schemas/ErrorResponse" 422: description: Received invalid field content: "application/vnd.scanner.adapter.error+json; version=1.0": schema: $ref: "#/components/schemas/ErrorResponse" 500: description: Internal server error content: "application/vnd.scanner.adapter.error+json; version=1.0": schema: $ref: '#/components/schemas/ErrorResponse' /scan/{scan_request_id}/report: get: tags: - Scanner summary: Get scan report description: | Get a scan report for the given scan request identifier. Clients will periodically poll this operation and check `$response.status` until its value equals `200` or `500`. operationId: GetScanReport parameters: - name: scan_request_id in: path description: The identifier of the corresponding scan request required: true style: simple explode: false schema: $ref: '#/components/schemas/ScanRequestId' - name: Accept in: header schema: type: string example: "application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0" responses: 200: description: Scan report content: "application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0": schema: $ref: '#/components/schemas/HarborVulnerabilityReport' "application/vnd.scanner.adapter.vuln.report.raw": schema: type: string example: | { "vendor_specific": "vulnerabilities_report" } 302: description: Status indicating the scan report is being generated and the request should be retried. headers: Refresh-After: description: Indicates the interval after which the request should be retried. schema: type: integer 404: description: Cannot find the corresponding scan request identifier 500: description: Internal server error content: "application/vnd.scanner.adapter.error+json; version=1.0": schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: Scanner: type: object properties: name: type: string description: The name of the scanner. example: Microscanner vendor: type: string description: The name of the scanner's provider. example: Aqua Security version: type: string description: The version of the scanner. example: 3.0.5 description: | Basic scanner properties such as name, vendor, and version. ScannerAdapterMetadata: required: - scanner - capabilities type: object properties: scanner: $ref: '#/components/schemas/Scanner' capabilities: type: array items: $ref: '#/components/schemas/ScannerCapability' properties: $ref: "#/components/schemas/ScannerProperties" description: | Represents metadata of a Scanner Adapter which allows Harbor to lookup a scanner capable of scanning a given Artifact stored in its registry and making sure that it can interpret a returned result. ScannerProperties: type: object additionalProperties: type: string example: "harbor.scanner-adapter/scanner-type": "os-package-vulnerability" "harbor.scanner-adapter/vulnerability-database-updated-at": "2019-08-13T08:16:33.345Z" description: | A set of custom properties that can further describe capabilities of a given scanner. ScannerCapability: description: | Capability consists of the set of recognized artifact MIME types and the set of scanner report MIME types. For example, a scanner capable of analyzing Docker images and producing a vulnerabilities report recognizable by Harbor web console might be represented with the following capability: - consumes MIME types: - `application/vnd.oci.image.manifest.v1+json` - `application/vnd.docker.distribution.manifest.v2+json` - produces MIME types: - `application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0` required: - consumes_mime_types - produces_mime_types type: object properties: consumes_mime_types: type: array items: type: string description: | The set of MIME types of the artifacts supported by the scanner to produce the reports specified in the "produces_mime_types". A given mime type should only be present in one capability item. example: - "application/vnd.oci.image.manifest.v1+json" - "application/vnd.docker.distribution.manifest.v2+json" produces_mime_types: type: array items: type: string description: | 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" ScanRequest: required: - registry - artifact type: object properties: registry: $ref: '#/components/schemas/Registry' artifact: $ref: '#/components/schemas/Artifact' ScanResponse: required: - id properties: id: $ref: '#/components/schemas/ScanRequestId' ScanRequestId: description: | A unique identifier returned by the [/scan](#/operation/AcceptScanRequest] operations. The format of the identifier is not imposed but it should be unique enough to prevent collisons when polling for scan reports. type: string example: "3fa85f64-5717-4562-b3fc-2c963f66afa6" Registry: type: object properties: url: type: string description: A base URL or the Docker Registry v2 API. format: url example: https://core.harbor.domain authorization: type: string description: | An optional value of the HTTP Authorization header sent with each request to the Docker Registry v2 API. It's used to exchange Base64 encoded robot account credentials to a short lived JWT access token which allows the underlying scanner to pull the artifact from the Docker Registry. example: "Basic BASE64_ENCODED_CREDENTIALS" Artifact: type: object properties: repository: type: string description: The name of the Docker Registry repository containing the artifact. example: library/mongo digest: type: string description: The artifact's digest, consisting of an algorithm and hex portion. example: "sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b" mime_type: type: string description: The MIME type of the artifact. example: "application/vnd.docker.distribution.manifest.v2+json" HarborVulnerabilityReport: type: object properties: generated_at: type: string format: 'date-time' artifact: $ref: '#/components/schemas/Artifact' scanner: $ref: '#/components/schemas/Scanner' severity: $ref: "#/components/schemas/Severity" vulnerabilities: type: array items: $ref: '#/components/schemas/VulnerabilityItem' VulnerabilityItem: type: object properties: id: type: string description: The unique identifier of the vulnerability. example: CVE-2017-8283 package: type: string description: | An operating system package containing the vulnerability. example: dpkg version: type: string description: | The version of the package containing the vulnerability. example: 1.17.27 fix_version: type: string description: | The version of the package containing the fix if available. example: 1.18.0 severity: $ref: "#/components/schemas/Severity" description: type: string description: | The detailed description of the vulnerability. example: | dpkg-source in dpkg 1.3.0 through 1.18.23 is able to use a non-GNU patch program and does not offer a protection mechanism for blank-indented diff hunks, which allows remote attackers to conduct directory traversal attacks via a crafted Debian source package, as demonstrated by using of dpkg-source on NetBSD. links: type: array items: type: string format: uri description: | The list of links to the upstream databases with the full description of the vulnerability. format: uri example: - https://security-tracker.debian.org/tracker/CVE-2017-8283 Severity: type: string description: | A standard scale for measuring the severity of a vulnerability. * `Unknown` - either a security problem that has not been assigned to a priority yet or a priority that the scanner did not recognize. * `Negligible` - technically a security problem, but is only theoretical in nature, requires a very special situation, has almost no install base, or does no real damage. * `Low` - a security problem, but is hard to exploit due to environment, requires a user-assisted attack, a small install base, or does very little damage. * `Medium` - a real security problem, and is exploitable for many people. Includes network daemon denial of service attacks, cross-site scripting, and gaining user privileges. * `High` - a real problem, exploitable for many people in a default installation. Includes serious remote denial of service, local root privilege escalations, or data loss. * `Critical` - a world-burning problem, exploitable for nearly all people in a default installation. Includes remote root privilege escalations, or massive data loss. example: Low enum: - None - Unknown - Negligible - Low - Medium - High - Critical ErrorResponse: type: object properties: error: $ref: "#/components/schemas/Error" Error: type: object properties: message: type: string example: "Some unexpected error" securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer