diff --git a/API/scanner/scanner-adapter-openapi-v1.0.yaml b/API/scanner/scanner-adapter-openapi-v1.0.yaml deleted file mode 100644 index db71d4744..000000000 --- a/API/scanner/scanner-adapter-openapi-v1.0.yaml +++ /dev/null @@ -1,389 +0,0 @@ -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 diff --git a/README.md b/README.md index 49af8df36..20ca01b07 100644 --- a/README.md +++ b/README.md @@ -42,8 +42,7 @@ Harbor is hosted by the [Cloud Native Computing Foundation](https://cncf.io) (CN ## API -* [Harbor RESTful API](https://editor.swagger.io/?url=https://raw.githubusercontent.com/goharbor/harbor/master/API/harbor/swagger.yaml): The APIs for most administrative operations of Harbor and can be used to perform integrations with Harbor programmatically. -* [Scanner Open API](https://editor.swagger.io/?url=https://raw.githubusercontent.com/goharbor/harbor/master/API/scanner/scanner-adapter-openapi-v1.0.yaml): This API must be implemented in order to register a new artifact scanner in Harbor registry. +* [Harbor RESTful API](https://editor.swagger.io/?url=https://raw.githubusercontent.com/goharbor/harbor/master/api/harbor/swagger.yaml): The APIs for most administrative operations of Harbor and can be used to perform integrations with Harbor programmatically. ## Install & Run