goharbor / goharbor/pluggable-scanner-spec

Proposal v1.3: SBOM reference fields on the scan request artifact; document fields already sent in practice

Open
#24 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.