Upstream/harbor
1
0
Fork 0
mirror of https://github.com/goharbor/harbor.git synced 2024-11-18 16:25:16 +01:00
Code Issues Projects Releases Wiki Activity

Merge pull request #10208 from steven-zou/chore/clear_scanner_specs

Browse Source 
doc[scanner]:clear scanner spec related

Only document changed, merge it directly.
This commit is contained in:
Steven Zou 2019-12-09 18:40:13 +08:00 committed by GitHub
commit 7ef6e11c00
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 1 additions and 391 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

389
API/scanner/scanner-adapter-openapi-v1.0.yaml
View File

@ -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

3
README.md
View File

@ -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