feat(kubescape): add vulnerability drill-down tools and bound CVE output

[slashben]

What's wrong

The obvious question — "what are the worst vulnerabilities in my cluster?" — can't be answered with the current tools without blowing the context window.

• kubescape_list_vulnerabilities returns 200,793 B (~50k tokens) for a single image.
• kubescape_get_vulnerability_details needs a cve_id, and the only tool that emits CVE IDs is that 200 KB call.
• Nothing aggregates across images, so a cluster-wide question means one 200 KB call per image.

This PR adds two cheap tools that answer cluster- and workload-level questions, and bounds the expensive one.

Every number below was measured by running the built binary over MCP stdio against a live cluster.

Results

Call	Before	After
vulnerability_overview (whole cluster)	no such tool	1,114 B
vulnerability_overview (one namespace)	no such tool	1,116 B
list_vulnerable_workloads (all namespaces)	no such tool	3,807 B
list_vulnerable_workloads (namespace, limit 2)	no such tool	2,057 B
list_vulnerabilities (nginx:1.14.0, default)	200,793 B	3,013 B — 67× smaller
list_vulnerabilities (limit=0, all 293 CVEs)	200,793 B	38,707 B
get_vulnerability_details	5,104 B	5,104 B — unchanged

A full drill-down — cluster → worst workloads → that image's CVEs → one CVE in detail — now costs ~11 KB.

Background: where the cheap data comes from

Kubescape's scanner writes three levels of object, which this provider only ever read the most expensive of:

Level	What it holds	Size
per-namespace summary	severity totals for a namespace	~1 KB for the cluster
per-workload summary	severity totals + the name of the object holding that image's CVEs	~1.9 KB each
per-image CVE list	every CVE, full detail	2.7 MB each

The top two levels are just integers plus a reference. The provider went straight to the bottom level for everything, which is why every question cost 200 KB.

The two new tools

kubescape_vulnerability_overview — severity totals per namespace, worst first, in one call. Answers "where is the risk concentrated?", which has no tool today.

kubescape_list_vulnerable_workloads — workloads ranked by severity, in one call, where each row carries the manifest_name that list_vulnerabilities takes as input. The agent is handed its next call rather than guessing an object name.

Real output (verified against kubectl):

{"workload": "deployment/vuln-nginx", "container": "nginx",
 "image": "docker.io/library/nginx:1.14.0",
 "severities": {"Critical": {"all": 76, "relevant": 30}, "High": {"all": 133, "relevant": 34}},
 "manifest_name": "docker.io-library-nginx-1.14.0-e34030",
 "manifest_namespace": "kubescape"}

relevant is a Kubescape feature nothing surfaced before: it counts CVEs whose code was actually observed loaded at runtime. "76 critical, 30 reachable" is a far better triage signal than a raw count. (See the caveat at the bottom — it's reported carefully.)

⚠️ The one thing I'd ask you to look at

Reading those summary objects requires a non-standard query parameter, and getting it wrong fails silently in the worst possible direction.

Kubescape's API server strips object contents from every LIST response by default and only returns them if you pass resourceVersion=fullSpec. Without it, severity counts come back as zeros — not an error, and indistinguishable from a clean cluster.

Measured on the same objects, same moment:

Objects	default LIST	with resourceVersion=fullSpec
per-namespace summaries	903 B — all zeros	996 B — correct (99 critical)
per-workload summaries	12,908 B — all zeros	7,648 B — correct (76 critical for nginx)
per-image CVE lists	14,054 B — contents omitted	3,635,500 B ⚠️ never do this

So nginx:1.14.0 has 76 critical CVEs, and a default LIST of its summary reports 0. This is the same failure shape as the bug in #76, one level up — writing these tools the obvious way would report a vulnerable cluster as clean.

Two things follow, and both are deliberate:

1. The parameter is verified, not assumed. I wrote a throwaway Go program that logs the outgoing HTTP request, to confirm the Kubernetes client actually transmits this non-standard value rather than validating it away:

List(ctx, ListOptions{})                            → GET .../vulnerabilitymanifestsummaries?
List(ctx, ListOptions{ResourceVersion:"fullSpec"})  → GET .../vulnerabilitymanifestsummaries?resourceVersion=fullSpec

It's passed through verbatim, no error or warning, and the returned counts match what a single-object GET reports. A RESTClient() fallback also works if that ever changes. (Verified for List() only — Watch() treats resourceVersion differently and isn't used here.)

2. overview will not report an all-zero cluster as clean. If every namespace reports zero it says the result could not be confirmed and points at a per-manifest check, because "no vulnerabilities" is the most expensive wrong answer this provider can give and it should never be produced by a silent mechanism failure. Happy to drop this if you find it too defensive — it's the one piece of opinion in the PR.

list_vulnerabilities reshaped

• The severity breakdown always covers the whole image, even when the CVE array is filtered or truncated — so a bounded response still carries the real totals.
• The array is capped by limit (default 20), worst severity first, with total_count / returned_count / truncated so the agent knows it has partial data.
• Each entry carries id, severity, fix_state, affected_artifacts. Removed: description (56% of the old payload, and truncated at 200 chars mid-word — "...to prevent command inje..." — so it was lossy prose inviting reasoning from a fragment), data_source (19.5%), fix_versions (7.9%). All three are still available in full from get_vulnerability_details.
• New severity and fixable_only filters.

Also fixes a miscount: the severity breakdown had no Negligible bucket, so nginx's 102 Negligible CVEs were reported as "Unknown": 102. Visible in the live output before this change.

Two bugs the live run caught

Duplicate CVE rows (mine). The scanner emits one row per affected package, so the same CVE recurs. Once I trimmed the package fields, those rows became byte-identical and duplicates ate the limit budget — the first 20 records held two CVEs twice each. Now collapsed by CVE id with an affected_artifacts count, and a CVE unfixed in any package is never reported as fixed. 466 rows → 293 distinct CVEs.

A reference in Kubescape's own data is wrong. The per-workload summary points at its CVE object with a namespace that doesn't contain it:

$ kubectl get vulnerabilitymanifestsummary -n verify-targets deployment-vuln-nginx-nginx \
    -o jsonpath='{.spec.vulnerabilitiesRef.all}'
{"name":"docker.io-library-nginx-1.14.0-e34030","namespace":"verify-targets"}

$ kubectl get vulnerabilitymanifest -n verify-targets docker.io-library-nginx-1.14.0-e34030
Error from server (NotFound)
$ kubectl get vulnerabilitymanifest -n kubescape docker.io-library-nginx-1.14.0-e34030
docker.io-library-nginx-1.14.0-e34030   2026-09-02T07:51:06Z

So only the name is taken from that reference; the namespace comes from the operator's namespace (overridable via a kubescape_namespace argument). Passing it through verbatim would hand the agent a pointer that 404s. Looks like an upstream Kubescape bug — I'll report it there separately.

Risk / compatibility

• list_vulnerabilities output shape changes — fields removed from each entry, array now bounded by default. This is the breaking part and the reason this is a separate PR from fix(kubescape): report health correctly and make the level filter work #75/fix(kubescape): stop reporting vulnerability_count 0 for every image #76. If you'd rather the array default to unbounded, that's a one-line change.
• Two new tools; the provider goes 10 → 12. If that's too much surface, they could merge behind a scope argument, at some cost in clarity for the calling model.
• No new dependencies. Confined to pkg/kubescape.

Testing

go test ./pkg/kubescape/... — 68 pass, no cluster needed. go build, go vet, golangci-lint, go test -tags=test ./pkg/... ./internal/... (747 pass) all clean. The pre-existing test/e2e suite needs a live kind cluster and was not run.

All tests written first and observed failing. One note: the fake clientset silently drops resourceVersion from the actions it records, so a test reactor can't check that the parameter was sent. The tests instead wrap the client to record the options each handler actually passes — otherwise the single most important invariant here would be untested, and losing it would reintroduce the #76 bug at cluster scale.

Open questions

1. Does kubescape_list_vulnerability_manifests still earn its place? Once list_vulnerable_workloads exists it's strictly weaker — same index, no counts, no pointers. Left untouched here.
2. Is the all-zero warning in overview right, or noise?
3. 10 → 12 tools — acceptable, or merge the two new ones?

Relationship to the other PRs

Independent of #75 (health checks) and #76 (vulnerability_count: 0); all three branch from main. #76 and this one touch nearby code, so whichever lands second needs a trivial rebase.

Not included, and worth separate PRs: the provider's client is built once and never retried, so if it starts before the API is reachable all its tools stay dead until the pod restarts; and internal/errors marks unrecoverable errors Retryable: Yes — visible in this PR's own validation error, where invalid severity "Nope" reports Retryable: Yes and suggests checking your kubeconfig.

Ticket

None.