goharbor / goharbor/pluggable-scanner-spec
Proposal v1.3: SBOM reference fields on the scan request artifact; document fields already sent in practice
- Dominant language
- No language data
- Stars
- 26
- Forks
- 15
- PR merge metrics
- No merged PRs in 30d
Description
Proposal for a v1.3 revision of the scanner adapter API spec with two changes:
1. New optional fields on the `Artifact` object of `ScanRequest` that let the client (Harbor) pass a reference to an existing SBOM of the scanned artifact.
2. Document fields that Harbor already sends today but that are absent from the v1.2 schemas.
Both changes are additive and non-breaking.
## 1. SBOM reference on the scan request artifact
Motivation: vulnerability scan time is dominated by pulling and analyzing image layers. When the registry already holds an SBOM of the artifact that was generated by the same scanner (Harbor generates and stores these as OCI accessories in the same repository), the scanner can produce an identical vulnerability report from the SBOM at a fraction of the cost, since the vulnerability database is applied at scan time either way. Measurements with the Trivy adapter show 6-35x faster scans with identical results. Full proposal on the Harbor side: https://github.com/container-registry/harbor-next/issues/461
Proposed addition to the `Artifact` schema (used in `ScanRequest`):
- `sbom_digest` (string, optional): digest of an SBOM artifact stored in the same repository, whose subject is the artifact being scanned. Only sent for vulnerability scan requests, and only when the client can attest the SBOM was produced by its scan pipeline.
- `sbom_media_type` (string, optional): media type of the SBOM content, for example `application/spdx+json` or `application/vnd.cyclonedx+json`.
Semantics: the scanner MAY fetch the referenced SBOM (the authorization provided in the request covers it, same repository) and derive the vulnerability report from it instead of pulling the artifact's layers. Scanners that do not support this ignore the fields and scan the artifact as before. On any failure to use the SBOM, the scanner falls back to a regular scan.
## 2. Document fields already sent in practice
Harbor currently sends two fields that the v1.2 schemas do not define:
- `Artifact.size` (integer): size of the artifact manifest in bytes.
- `Registry.insecure` (boolean): whether certificate verification for the registry URL should be skipped.
Adapters have tolerated these unknown fields for years because the schemas are open, but the spec should describe the wire format that is actually in use. v1.3 should add both properties with descriptions.
## Compatibility
All proposed fields are optional. Object schemas in the spec do not set `additionalProperties: false`, and existing adapters use permissive decoders, so v1.2 adapters remain fully compatible with v1.3 clients and vice versa.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating the v1.2 schemas for Artifact, ScanRequest, and Registry in the specification. Add the two optional SBOM reference fields and document Artifact.size and Registry.insecure, then verify that the changes remain additive and compatible with the stated fallback behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100