Improve documentation: Kubewarden's QA feedback

[fabriziosestito]

• (1) I need to read a lot of sbomscanner docs just to do hello world from UI!

• (1) Explain concept of registry scanning, why would I want to scan registry?
  what registries should I add? how does it help me with my cluster safety?

• (1) registry vs workload scanning in connection my cluster safety - two types of workflows?
  give it same priority on sbomscanner readme? workload scanning seems like second hand feature
  UI tells me to add registry, does not mention worklow

• (2) registry without catalog - should this be default? (ghcr.io, docker, google, amazon)
  can I assume "catalogType" from repositories value being set? how do I know registry has catalog?
  in UI I keep trying to create registry but it won't scan

• (3) "define a Registry custom resource for SBOMscanner to fetch images"
  use simpler words - why "custom resource"? what images is sbomscanner fetching?

• At some point scans were in error state with You have reached your unauthenticated pull rate limit:

2026-03-01T16:23:09.321064Z ERROR request{method=POST uri=/audit/clusterwide-test-image-cve version=HTTP/1.1}:audit{host="policy-server-default-7c8dd48856-q82p4" policy_id="clusterwide-test-image-cve" kind="StatefulSet" kind_group="apps" kind_version="v1" name="rancher-sbomscanner-nats" namespace="cattle-sbomscanner-system" operation="CREATE" request_uid="46683d0f-c2e9-4618-b1bd-907d56ed6913" resource="StatefulSet" resource_group="apps" resource_version="v1" subresource=""}:validate{self=PolicyEvaluator { runtime: "wapc" } settings=PolicySettings({"ignoreMissingVulnerabilityReport": Bool(true), "maxSeverity": Object {"critical": Object {"total": Number(0)}, "high": Object {"total": Number(5)}, "low": Object {"total": Number(20)}, "medium": Object {"total": Number(10)}}, "vulnerabilityReportNamespace": String("cattle-sbomscanner-system")})}: policy_evaluator::runtimes::callback: callback evaluation failed policy_id="clusterwide-test-image-cve" binding="kubewarden" operation="v1/oci_manifest" error=Fail to interact with OCI registry: Registry error: url https://index.docker.io/v2/natsio/nats-server-config-reloader/manifests/0.21.1, envelope: OCI API errors: [OCI API error: You have reached your unauthenticated pull rate limit. https://www.docker.com/increase-rate-limit]
Caused by:
    Registry error: url https://index.docker.io/v2/natsio/nats-server-config-reloader/manifests/0.21.1, envelope: OCI API errors: [OCI API error: You have reached your unauthenticated pull rate limit. https://www.docker.com/increase-rate-limit]
2026-03-01T16:23:09.321370Z  INFO request{method=POST uri=/audit/clusterwide-test-image-cve version=HTTP/1.1}:audit{host="policy-server-default-7c8dd48856-q82p4" policy_id="clusterwide-test-image-cve" kind="StatefulSet" kind_group="apps" kind_version="v1" name="rancher-sbomscanner-nats" namespace="cattle-sbomscanner-system" operation="CREATE" request_uid="46683d0f-c2e9-4618-b1bd-907d56ed6913" resource="StatefulSet" resource_group="apps" resource_version="v1" subresource=""}:validate{self=PolicyEvaluator { runtime: "wapc" } settings=PolicySettings({"ignoreMissingVulnerabilityReport": Bool(true), "maxSeverity": Object {"critical": Object {"total": Number(0)}, "high": Object {"total": Number(5)}, "low": Object {"total": Number(20)}, "medium": Object {"total": Number(10)}}, "vulnerabilityReportNamespace": String("cattle-sbomscanner-system")})}:policy_log{self=EvaluationContext { policy_id: "clusterwide-test-image-cve", callback_channel: Some(...), allowed_kubernetes_resources: {ContextAwareResource { api_version: "storage.sbomscanner.kubewarden.io/v1alpha1", kind: "VulnerabilityReport" }} }}: policy_log: ignoring error while attempting to fetch the image manifest because ignoreMissingVulnerabilityReport is enabled data={"column":17,"error":"ManifestFetchError(\"error invoking wapc oci.manifest_digest: Error(HostError([67, 97, 108, 108, 98, 97, 99, 107, 32, 101, 118, 97, 108, 117, 97, 116, 105, 111, 110, 32, 102, 97, 105, 108, 117, 114, 101, 58, 32, 70, 97, 105, 108, 32, 116, 111, 32, 105, 110, 116, 101, 114, 97, 99, 116, 32, 119, 105, 116, 104, 32, 79, 67, 73, 32, 114, 101, 103, 105, 115, 116, 114, 121, 58, 32, 82, 101, 103, 105, 115, 116, 114, 121, 32, 101, 114, 114, 111, 114, 58, 32, 117, 114, 108, 32, 104, 116, 116, 112, 115, 58, 47, 47, 105, 110, 100, 101, 120, 46, 100, 111, 99, 107, 101, 114, 46, 105, 111, 47, 118, 50, 47, 110, 97, 116, 115, 105, 111, 47, 110, 97, 116, 115, 45, 115, 101, 114, 118, 101, 114, 45, 99, 111, 110, 102, 105, 103, 45, 114, 101, 108, 111, 97, 100, 101, 114, 47, 109, 97, 110, 105, 102, 101, 115, 116, 115, 47, 48, 46, 50, 49, 46, 49, 44, 32, 101, 110, 118, 101, 108, 111, 112, 101, 58, 32, 79, 67, 73, 32, 65, 80, 73, 32, 101, 114, 114, 111, 114, 115, 58, 32, 91, 79, 67, 73, 32, 65, 80, 73, 32, 101, 114, 114, 111, 114, 58, 32, 89, 111, 117, 32, 104, 97, 118, 101, 32, 114, 101, 97, 99, 104, 101, 100, 32, 121, 111, 117, 114, 32, 117, 110, 97, 117, 116, 104, 101, 110, 116, 105, 99, 97, 116, 101, 100, 32, 112, 117, 108, 108, 32, 114, 97, 116, 101, 32, 108, 105, 109, 105, 116, 46, 32, 104, 116, 116, 112, 115, 58, 47, 47, 119, 119, 119, 46, 100, 111, 99, 107, 101, 114, 46, 99, 111, 109, 47, 105, 110, 99, 114, 101, 97, 115, 101, 45, 114, 97, 116, 101, 45, 108, 105, 109, 105, 116, 93, 10, 10, 67, 97, 117, 115, 101, 100, 32, 98, 121, 58, 10, 32, 32, 32, 32, 82, 101, 103, 105, 115, 116, 114, 121, 32, 101, 114, 114, 111, 114, 58, 32, 117, 114, 108, 32, 104, 116, 116, 112, 115, 58, 47, 47, 105, 110, 100, 101, 120, 46, 100, 111, 99, 107, 101, 114, 46, 105, 111, 47, 118, 50, 47, 110, 97, 116, 115, 105, 111, 47, 110, 97, 116, 115, 45, 115, 101, 114, 118, 101, 114, 45, 99, 111, 110, 102, 105, 103, 45, 114, 101, 108, 111, 97, 100, 101, 114, 47, 109, 97, 110, 105, 102, 101, 115, 116, 115, 47, 48, 46, 50, 49, 46, 49, 44, 32, 101, 110, 118, 101, 108, 111, 112, 101, 58, 32, 79, 67, 73, 32, 65, 80, 73, 32, 101, 114, 114, 111, 114, 115, 58, 32, 91, 79, 67, 73, 32, 65, 80, 73, 32, 101, 114, 114, 111, 114, 58, 32, 89, 111, 117, 32, 104, 97, 118, 101, 32, 114, 101, 97, 99, 104, 101, 100, 32, 121, 111, 117, 114, 32, 117, 110, 97, 117, 116, 104, 101, 110, 116, 105, 99, 97, 116, 101, 100, 32, 112, 117, 108, 108, 32, 114, 97, 116, 101, 32, 108, 105, 109, 105, 116, 46, 32, 104, 116, 116, 112, 115, 58, 47, 47, 119, 119, 119, 46, 100, 111, 99, 107, 101, 114, 46, 99, 111, 109, 47, 105, 110, 99, 114, 101, 97, 115, 101, 45, 114, 97, 116, 101, 45, 108, 105, 109, 105, 116, 93]))\")","file":"image-cve-policy/src/lib.rs","image":"natsio/nats-server-config-reloader:0.21.1","line":214,"policy":"image-cve"}

[fabriziosestito]

Proposals

Problem

(1) I need to read a lot of sbomscanner docs just to do hello world from UI!
(1) Explain concept of registry scanning, why would I want to scan registry?
what registries should I add? how does it help me with my cluster safety?

Solution

• Add workloadscan to the quickstart guide as well and explain the differences between workload and registry scanning.
• Add an Introduction, explain the major features.

---

Problem

(2) registry without catalog - should this be default? (ghcr.io, docker, google, amazon)
can I assume "catalogType" from repositories value being set? how do I know registry has catalog?
in UI I keep trying to create registry but it won't scan

Solution

• Document and validate (with a webhook) public registries that do not expose _catalog Api: https://github.com/kubewarden/sbomscanner/blob/main/docs/user-guide/scanning-registries.md#3-configuring-registry-without-catalog
• Helm chart installation takes a while: document this.

---

Problem

At some point scans were in error state with You have reached your unauthenticated pull rate limit:

Solution

• Add a troubleshooting documentation section with the common errors a user can encounter. Specifically, point the user to the rate-limit documentation of docker.io.