fix: carry SBOM annotations in metadata-only GetSBOM payload

[matthyx]

Problem

GetSBOMStream's metadata-only path (metadata_only=true) returns an SBOMMetadata that carries only image_digest, syft_version, source, blob_size_bytes, created_at, and last_referenced_at — but no annotations.

Consumers that only need to branch on the SBOM's Kubernetes annotations (status, tool-version, node-name, scanner-memory-limit, …) are therefore forced onto the full-fetch path: node-agent's GetSBOMMeta downloads the entire blob and UnmarshalSBOMs it just to read a handful of strings.

Fix

Add a generic map<string, string> annotations field (field 7) to the SBOMMetadata proto message. It maps 1:1 onto SBOMSyft.ObjectMeta.Annotations, so a metadata_only=true fetch becomes sufficient for any annotation-only decision — no per-annotation proto churn as new keys are added.

• storage_service.proto: new annotations field with doc comment.
• storage_service.pb.go: regenerated via make proto (gogo bindings); the gRPC stub regenerated identically.
• storageclient.go: GetSBOMStream doc comment now notes annotations are available on the metadata-only path.
• storageclient_test.go: the metadata-only round-trip subtest now asserts annotations survive the metadata_only path end-to-end over bufconn.

This is a backward-compatible, additive proto change (new field number, no renumbering).

Follow-ups (separate repos)

• Server: populate SBOMMetadata.annotations from the stored SBOM row on GetSBOMStream.
• node-agent: switch GetSBOMMeta to metadata_only=true and reconstruct SBOMSyft.Annotations from md.SbomMetadata.Annotations instead of fetching the full blob.

Testing

go build ./... and go test ./pkg/client/v1/... pass.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • SBOM metadata now includes annotations (Kubernetes-style), enabling efficient metadata-only queries and probe handling without downloading full SBOM payloads.

• Tests

  • Expanded tests to verify annotations are preserved and returned correctly in metadata-only query scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0a1e949d-67cb-4ad6-8bab-bf6c5887ead6

📥 Commits

Reviewing files that changed from the base of the PR and between 5288fa3 and 4375e76.

⛔ Files ignored due to path filters (1)

• pkg/client/v1/proto/storage_service.pb.go is excluded by !**/*.pb.go

📒 Files selected for processing (3)

• pkg/client/v1/proto/storage_service.proto
• pkg/client/v1/storageclient.go
• pkg/client/v1/storageclient_test.go

✅ Files skipped from review due to trivial changes (1)

• pkg/client/v1/storageclient.go

🚧 Files skipped from review as they are similar to previous changes (2)

• pkg/client/v1/proto/storage_service.proto
• pkg/client/v1/storageclient_test.go

---

📝 Walkthrough

Walkthrough

SBOM metadata is extended with a new annotations map field to support annotation-based branching in metadata-only probes. The proto schema, API documentation, and round-trip test coverage are updated together to define, document, and verify the new field's behavior.

Changes

SBOM Metadata Annotations

Layer / File(s)	Summary
SBOM metadata annotations schema definition pkg/client/v1/proto/storage_service.proto	SBOMMetadata message gains a new annotations map field (tag 7) with documentation explaining its role in supporting efficient metadata_only=true workflows without requiring full SBOM blob downloads.
Metadata-only probe documentation and testing pkg/client/v1/storageclient.go, pkg/client/v1/storageclient_test.go	GetSBOMStream API documentation is expanded to explain how callers use md.Exists and the new md.SbomMetadata.Annotations for probe branching. The metadata-only test case is updated to populate annotations with kubescape.io/* keys and verify they are returned unchanged on the metadata-only path.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• kubescape/backend#50: Introduced the SBOM streaming feature that this PR extends with annotation support to the SBOMMetadata contract and metadata-only probe behavior.

Poem

🐰 I hopped through fields both small and grand,
A map of annotations held in hand,
No blobs to fetch, just keys to read,
Metadata probes find what they need,
Hooray — lightweight and ready to land!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the primary change: adding SBOM annotations to the metadata-only GetSBOM payload via a new protobuf field.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/sbom-metadata-annotations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}