mirror of
https://github.com/goharbor/harbor
synced 2025-05-09 00:08:47 +00:00
doc[scanner]:clear scanner spec related
- remove the scanner open API spec from api folder - update README doc to remove the API reference Signed-off-by: Steven Zou <szou@vmware.com>
This commit is contained in:
Steven Zou
parent
5fe6337e02
commit
2cd90963ef
@ -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
|
|
||||||
@ -42,8 +42,7 @@ Harbor is hosted by the [Cloud Native Computing Foundation](https://cncf.io) (CN
|
|||||||
|
|
||||||
## API
|
## 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.
|
* [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.
|
|
||||||
|
|
||||||
## Install & Run
|
## Install & Run
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user