{"id":20778000,"url":"https://github.com/goharbor/pluggable-scanner-spec","last_synced_at":"2025-04-30T18:40:43.118Z","repository":{"id":43038900,"uuid":"226826808","full_name":"goharbor/pluggable-scanner-spec","owner":"goharbor","description":"Open API spec definition for the scanners that can be plugged into Harbor to do artifact scanning.","archived":false,"fork":false,"pushed_at":"2024-06-06T06:18:35.000Z","size":28,"stargazers_count":20,"open_issues_count":10,"forks_count":10,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-07-30T19:44:31.045Z","etag":null,"topics":["api","harbor","openapi","scanner","swagger"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goharbor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-09T08:53:58.000Z","updated_at":"2024-05-27T03:06:14.000Z","dependencies_parsed_at":"2022-09-09T17:01:03.591Z","dependency_job_id":"4f709b2a-c588-440d-a44d-461db2f82a7a","html_url":"https://github.com/goharbor/pluggable-scanner-spec","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goharbor%2Fpluggable-scanner-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goharbor%2Fpluggable-scanner-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goharbor%2Fpluggable-scanner-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goharbor%2Fpluggable-scanner-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goharbor","download_url":"https://codeload.github.com/goharbor/pluggable-scanner-spec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225040813,"owners_count":17411539,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","harbor","openapi","scanner","swagger"],"created_at":"2024-11-17T13:18:29.280Z","updated_at":"2024-11-17T13:18:29.886Z","avatar_url":"https://github.com/goharbor.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# pluggable-scanner-spec\n\n\u003cimg src=\"http://validator.swagger.io/validator?url=https://raw.githubusercontent.com/goharbor/pluggable-scanner-spec/master/api/spec/scanner-adapter-openapi-v1.2.yaml\"\u003e\n\nOpen API spec definition for the scanners that can be plugged into Harbor to do artifact scanning.\n\n\n## Background\n\nAdd support to Harbor for using other image scanners than  _Trivy_ by providing an adapter layer implemented as an HTTP API between Harbor and the scanners' native\ninterfaces. This will provide runtime configurable scanner invocation to provide vulnerability scanning initially with\nthe option for other types of scanning in the future.\n\nIntroduce:\n1. Scanner Adapter HTTP API (defined and maintained by Harbor)\n   - Core operations:\n     - Execute a scan (non-blocking)\n     - Retrieve a scan report (polling by Harbor)\n     - Describe the scanner’s capabilities, i.e. supported artifacts and reports\n2. Scanner Adapter HTTP client in Harbor\n3. Scanner Adapter configuration management and persistence in the Harbor DB\n\nThe adapter interface is a well-defined REST API specified and maintained by Harbor. Harbor will have a client for the\nAPI, and manage configuration of the client. The configuration is primarily an endpoint registration, and multiple\nconfigurations will be supported concurrently in the system. This will allow user-selectable and configurable scanning\nof images at runtime with no restarts for Harbor required. Scanner adapters must implement the specified API, but the\ndeployment and configuration of the adapter services is out-of-scope and should be covered by the provider themselves. Harbor itself is\nnot responsible for management or deployment of the adapter services.\n\nFor more details, you can refer to the original [design proposal](https://github.com/goharbor/community/blob/master/proposals/pluggable-image-vulnerability-scanning_proposal.md).\n\n## Capabilities\n\nThis spec currently supports a collection of capabilities, before version 1.2, scanner provides the ability to produce different reports with mime type, but these capabilities are corresponding to the vulnerability, so in 1.2 spec we emphasize and added a new filed `type` in the `ScannerCapability` to describe the different scanning capabilities, the following are the currently supported capabilities matrix.\n\n| Capability Type | Supported consumed MIME types | Supported produced MIME types |\n| --------------- | ----------------------------- | ----------------------------- |\n|  vulnerability  | `application/vnd.oci.image.manifest.v1+json`\u003cbr\u003e`application/vnd.docker.distribution.manifest.v2+json` | `application/vnd.scanner.adaptevuln.report.harbor+json; version=1.0`\u003cbr\u003e`application/vnd.security.vulnerability.report; version=1.1`\u003cbr\u003e`application/vnd.scanner.adapter.vuln.report.raw`|\n|     sbom        | `application/vnd.oci.image.manifest.v1+json`\u003cbr\u003e`application/vnd.docker.distribution.manifest.v2+json` | `application/vnd.security.sbom.repo+json; version=1.0` |\n\n## Scanner Adapter API\n\nThe [Scanner Adapter v1.2 - OpenAPI Specification](./api/spec/scanner-adapter-openapi-v1.2.yaml) introduces a new [data spec model](./data/spec/SBOM.md) for the SBOMs(Software Bill of Materials), and bump several headers version to v1.1 so as to support specify the capability used, refer to the OpenAPI yaml for details.\n\n- `application/vnd.scanner.adapter.metadata+json; version=1.1`\n- `application/vnd.scanner.adapter.scan.request+json; version=1.1`\n\n\u003e Note: There is no breaking change compared to before, we extended some fields on top of the v1.1 model and bumped its version. Harbor will be compatible with both v1.1 and v1.2.\n\nThe [Scanner Adapter v1.1 - OpenAPI Specification](./api/spec/scanner-adapter-openapi-v1.1.yaml) normalizes the vulnerability schema to a base common representation and allowing scanners to provide more elaborate and richer information about vulnerabilities:\n * CVSS 3.0 scores and vectors \n * CVSS 2.0 scores and vectors\n * CWE IDs for the vulnerability\n * Ability to specify additional scanner specific details\n\nIt is mandated for the new scanner integrations to implement the current API specification.\nExisting scanner integrations should plan to migrate to the current version of the API.\nThe older [Scanner Adapter v1.0 - OpenAPI Specification](./api/spec/scanner-adapter-openapi-v1.0.yaml) is being maintained only for backward compatibility until existing scanner integrations move to the new API specification.\n \n\n\u003e Note: OpenAPI spec yaml file can be opened in the online [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/goharbor/pluggable-scanner-spec/master/api/spec/scanner-adapter-openapi-v1.1.yaml).\n\n- The deployment method is up to the vendor as long as the mounted API endpoint URL is accessible to Harbor services.\n- For each ScanRequest a Scanner Adapter generates a unique identifier which is used to poll for the corresponding\n  ScanReport.\n- The lifetime of ScanRequest identifier returned by a Scanner Adapter is defined by the adapter. The TTL of the\n  ScanReport and its identifier is long enough to support polling with reasonable timeouts.\n- Scanner Adapters are not expected to persist scan reports forever, Harbor is supposed to cache at least the latest\n  Scan Report.\n- Scanner Adapters are not expected to make responses for the given artifact immutable, i.e. Scan Reports might change\n  over time when new vulnerabilities are discovered.\n- A Scan Job may get a 404 response status for a ScanRequest identifier and should treat it as failed and return a\n  failure in the job. Harbor is expected to send a new Scan Request in that case.\n- Scanner Adapter API leverages content negotiation by using MIME types in the `Accept` header to define schema of\n  a result returned by GET `/scan/{scan_request_id}/report` requests.\n\n### Sample Interaction between Harbor and Scanner Adapter\n\n1. Make sure that the Scanner Adapter has expected capabilities:\n   ```\n   curl -H 'Accept: application/vnd.scanner.adapter.metadata+json; version=1.1\" \\\n     http://scanner-adapter:8080/api/v1/metadata\n\n   Content-Type: application/vnd.scanner.adapter.scanner.metadata+json; version=1.1\n   Status: 200 OK\n\n   {\n     \"scanner\": {\n       \"name\": \"Trivy\",\n       \"vendor\": \"Aqua Security\",\n       \"version\": \"0.18.0\",\n     },\n     \"capabilities\": [\n       {\n         \"type\": \"vulnerability\"\n         \"consumes_mime_types\": [\n           \"application/vnd.oci.image.manifest.v1+json\",\n           \"application/vnd.docker.distribution.manifest.v2+json\"\n         ],\n         \"produces_mime_types\": [\n           \"application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0\",\n           \"application/vnd.security.vulnerability.report; version=1.1\"\n         ]\n       }\n     ],\n     \"properties\": {\n       \"harbor.scanner-adapter/scanner-type\": \"os-package-vulnerability\",\n       \"harbor.scanner-adapter/vulnerability-database-updated-at\": \"2019-08-13T08:16:33.345Z\"\n     }\n   }\n   ```\n2. Submit the scan request\n   1. Submit an invalid scan request:\n       ```\n       curl http://scanner-adapter:8080/api/v1/scan \\\n       -H 'Content-Type: application/vnd.scanner.adapter.scan.request+json; version=1.1' \\\n       -d @- \u003c\u003c EOF\n       {\n         \"registry\": {\n           \"url\": \"INVALID_REGISTRY_URL\",\n           \"authorization\": \"Bearer JWTTOKENGOESHERE\"\n         },\n         \"artifact\": {\n           \"repository\": \"library/mongo\",\n           \"digest\": \"sha256:917f5b7f4bef1b35ee90f03033f33a81002511c1e0767fd44276d4bd9cd2fa8e\"\n         },\n         \"enabled_capabilities\": [\n           {\n            \"type\": \"vulnerability\"\n            \"produces_mime_types\": [\"application/vnd.security.vulnerability.report; version=1.1\"]\n           }\n         ]\n       }\n       EOF\n\n       Status: 422 Unprocessable Entity\n       Content-Type: application/vnd.scanner.adapter.error+json; version=1.0'\n\n       {\n         \"error\": {\n           \"message\": \"invalid registry_url\"\n         }\n       }\n       ```\n   2. Submit a valid scan request:\n       ```\n       curl http://scanner-adapter:8080/api/v1/scan \\\n       -H 'Content-Type: application/vnd.scanner.adapter.scan.request+json; version=1.1' \\\n       -d @- \u003c\u003c EOF\n       {\n         \"registry\": {\n           \"url\": \"harbor-harbor-registry:5000\",\n           \"authorization\": \"Bearer: JWTTOKENGOESHERE\"\n         },\n         \"artifact\": {\n           \"repository\": \"library/mongo\",\n           \"digest\": \"sha256:917f5b7f4bef1b35ee90f03033f33a81002511c1e0767fd44276d4bd9cd2fa8e\"\n         },\n        \"enabled_capabilities\": [\n           {\n            \"type\": \"vulnerability\"\n            \"produces_mime_types\": [\"application/vnd.security.vulnerability.report; version=1.1\"]\n           }\n         ]\n       }\n       EOF\n\n       Status: 202 Accepted\n       Content-Type: application/vnd.scanner.adapter.scan.response+json; version=1.0'\n\n       {\n         \"id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n       }\n       ```\n3. Try getting scan report (in the new v1.1 format understandable by Harbor Web console):\n   ```\n   curl -H 'Accept: application/vnd.security.vulnerability.report; version=1.1' \\\n     http://scanner-adapter:8080/api/v1/scan/3fa85f64-5717-4562-b3fc-2c963f66afa6/report\n\n   Retry-After: 15\n   Status: 302 Found\n   ```\n4. Wait 15 seconds or use your own retry interval ...\n5. ... and try getting scan report again:\n   ```\n    curl -H 'application/vnd.security.vulnerability.report; version=1.1' \\\n     http://scanner-adapter:8080/api/v1/scan/3fa85f64-5717-4562-b3fc-2c963f66afa6/report\n    Content-Type: application/vnd.security.vulnerability.report; version=1.1;\n    Status: 200 OK\n\n    {\n        \"generated_at\": \"2021-03-09T11:40:28.154072066Z\",\n        \"artifact\": {\n          \"repository\": \"library/docker\",\n          \"digest\": \"sha256:7215e8e09ea282e517aa350fc5380c1773c117b1867316fb59076d901e252d15\",\n          \"mime_type\": \"application/vnd.docker.distribution.manifest.v2+json\"\n        },\n        \"scanner\": {\n          \"name\": \"Trivy\",\n          \"vendor\": \"Aqua Security\",\n          \"version\": \"v0.16.0\"\n        },\n        \"severity\": \"High\",\n        \"vulnerabilities\": [\n          {\n              \"id\": \"CVE-2020-1967\",\n              \"package\": \"libcrypto1.1\",\n              \"version\": \"1.1.1c-r0\",\n              \"fix_version\": \"1.1.1g-r0\",\n              \"severity\": \"High\",\n              \"description\": \"Server or client applications that call the SSL_check_chain() function during or after a TLS 1.3 handshake may crash due to a NULL pointer dereference as a result of incorrect handling of the \\\"signature_algorithms_cert\\\" TLS extension. The crash occurs if an invalid or unrecognised signature algorithm is received from the peer. This could be exploited by a malicious peer in a Denial of Service attack. OpenSSL version 1.1.1d, 1.1.1e, and 1.1.1f are affected by this issue. This issue did not affect OpenSSL versions prior to 1.1.1d. Fixed in OpenSSL 1.1.1g (Affected 1.1.1d-1.1.1f).\",\n              \"links\": [\n                \"https://avd.aquasec.com/nvd/cve-2020-1967\"\n              ],\n              \"preferred_cvss\": {\n                \"score_v2\": 5,\n                \"score_v3\": 7.5,\n                \"vector_v2\": \"AV:N/AC:L/Au:N/C:N/I:N/A:P\",\n                \"vector_v3\": \"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H\"\n              },\n              \"cwe_ids\": [\n                \"CWE-476\"\n              ],\n              \"vendor_attributes\": {\n                \"CVSS\": {\n                  \"nvd\": {\n                    \"V2Score\": 5,\n                    \"V2Vector\": \"AV:N/AC:L/Au:N/C:N/I:N/A:P\",\n                    \"V3Score\": 7.5,\n                    \"V3Vector\": \"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H\"\n                  },\n                  \"redhat\": {\n                    \"V3Score\": 7.5,\n                    \"V3Vector\": \"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H\"\n                  }\n                }\n              }\n            }\n          ...\n        ]\n    }\n    ```\n \n6. Alternatively we could request a proprietary vulnerability report (with an example report generated\n   by MicroScanner in JSON format):\n   ```\n   curl -H 'Accept: application/vnd.scanner.adapter.vuln.report.raw' \\\n      http://scanner-adapter:8080/api/v1/scan/3fa85f64-5717-4562-b3fc-2c963f66afa6/report\n\n   Content-Type: application/vnd.scanner.adapter.vuln.report.raw\n   Status: 200 OK\n\n   {\n     \"scan_started\": {\n       \"seconds\": 1561386673,\n       \"nanos\": 390482870\n     },\n     \"scan_duration\": 2,\n     \"digest\": \"b3c8bc6c39af8e8f18f5caf53eec3c6c4af60a1332d1736a0cd03e710388e9c8\",\n     \"os\": \"debian\",\n     \"version\": \"8\",\n     \"resources\": [\n       {\n         \"resource\": {\n           \"format\": \"deb\",\n           \"name\": \"apt\",\n           \"version\": \"1.0.9.8.5\",\n           \"arch\": \"amd64\",\n           \"cpe\": \"pkg:/debian:8:apt:1.0.9.8.5\",\n           \"name_hash\": \"583f72a833c7dfd63c03edba3776247a\"\n         },\n         \"scanned\": true,\n         \"vulnerabilities\": [\n           {\n             \"name\": \"CVE-2011-3374\",\n             \"vendor_score_version\": \"Aqua\",\n             \"vendor_severity\": \"negligible\",\n             \"vendor_statement\": \"Not exploitable in Debian, since no keyring URI is defined\",\n             \"vendor_url\": \"https://security-tracker.debian.org/tracker/CVE-2011-3374\",\n             \"classification\": \"...\"\n           }\n         ]\n       }\n     ]\n   }\n   ```\n\n- The `Accept` request header is required to indicate to Scanner Adapter an intended scan report format\n- If the client does not specify the `Accept` header it's assumed to be Harbor vulnerability report with the\n  MIME type `application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0`. This behavior is currently maintained only for backward compatibility purposes.\n- In phase 1 each Scanner Adapter should support at least the following artifact MIME types:\n  - `application/vnd.oci.image.manifest.v1+json`\n  - `application/vnd.docker.distribution.manifest.v2+json`\n- In phase 1 each Scanner Adapter should support at least the following scan report MIME types:\n  - `application/vnd.scanner.adapter.vuln.report.harbor+json; version=1.0` - corresponds to `HarborVulnerabilityReport`\n     - fixed schema described in Scanner Adapter API spec\n     - can be parsed in type-safe manner and displayed in Harbor Web console.\n  - `application/vnd.scanner.adapter.vuln.report.raw`\n    - corresponds to a raw scan report\n    - no fixed schema, documented by a scanner's vendor\n- New scan report MIME types might be introduced without breaking the backward compatibility of the API and introducing\n  new URL paths to the Scanner Adapter API spec.\n- For example, there can be a vendor specific policy report returned by Anchore with the corresponding MIME type\n  `application/vnd.anchore.policy.report+json; version=0.3`:\n  ```json\n  [\n    {\n      \"sha256:57334c50959f26ce1ee025d08f136c2292c128f84e7b229d1b0da5dac89e9866\": {\n        \"docker.io/alpine:latest\": [\n          {\n            \"detail\": {},\n            \"last_evaluation\": \"2019-08-07T06:33:48Z\",\n            \"policyId\": \"2c53a13c-1765-11e8-82ef-23527761d060\",\n            \"status\": \"pass\"\n          }\n        ]\n      }\n    }\n  ]\n  ```\n\n## Scanner Adapter Implementations\n\n* [Aqua Trivy](https://github.com/aquasecurity/harbor-scanner-trivy)\n* [Clair](https://github.com/goharbor/harbor-scanner-clair)\n* [Anchore](https://github.com/anchore/harbor-scanner-adapter)\n* [Aqua CSP](https://github.com/aquasecurity/harbor-scanner-aqua)\n* [DoSec Scanner](https://github.com/dosec-cn/harbor-scanner/blob/master/README_en.md)\n* [Sysdig](https://github.com/sysdiglabs/harbor-scanner-sysdig-secure)\n* [TensorSecurity](https://github.com/tensorsecurity/harbor-scanner)\n\nFor more details, please refer to the [Harbor compatibility list](https://goharbor.io/docs/edge/install-config/harbor-compatibility-list/) document.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoharbor%2Fpluggable-scanner-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoharbor%2Fpluggable-scanner-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoharbor%2Fpluggable-scanner-spec/lists"}