[BUG] Kubescape health check treats aggregated API resources as missing CRDs

pkg/kubescape/kubescape.go、特に KubescapeTool と handleCheckHealth から始め、既存の apiExtClient のチェックと spdxClient のデータ取得パスを比較します。集約された Kubescape API のインストールに対して kubescape_check_health を実行します。CRD オブジェクトなしで利用可能な集約リソースをヘルスチェックが認識し、リソース不足に関する矛盾したエラーや推奨事項を報告しなくなれば完了です。

🎯 Affected Component(s)

pkg/kubescape (kagent-tools MCP server) — kubescape_check_health

🐛 Bug Description

Note: I think the Kubescape tool is still in an early/beta stage and not yet listed among the GA tools. I'm filing this in case the feedback is useful for hardening it before GA — please feel free to deprioritize if this tool is out of active scope.

The Kubescape tool's health check verifies the existence of Kubescape custom resources by checking for CRDs via the apiextensions client (apiExtClient).
However, the resources checked here—ApplicationProfile,
VulnerabilityManifest, and NetworkNeighborhood in the
spdx.softwarecomposition.kubescape.io/v1beta1 API—are served by
Kubescape Storage through the Kubernetes API aggregation layer rather
than being defined by CustomResourceDefinition objects.

Because these resources do not appear in the apiextensions (CRD) API, the CRD-existence check fails and reports them as "not installed", even though the resources exist and are fully queryable through the aggregated API.

This is a self-contradicting result: within the same check_health output, the tool reports VulnerabilityManifests CRD not installed (error) while simultaneously reporting 80 vulnerability manifests found (ok) — the latter succeeds precisely because that path uses the aggregated-API client (spdxClient), not the CRD client.

Note: Kubescape Storage has long utilized the Aggregated API, and with the release of 4.0, it has reached GA.
The Aggregated API is the officially recommended architecture for these security metadata resources.
Therefore, the health check function must support this architecture rather than assuming that the resources are backed by CRDs.

🔄 Steps To Reproduce

1. Install the Kubescape operator via Helm (v4.0.x line).
   The following capabilities are relevant and enabled by default in this chart line: storage/aggregated API, vulnerabilityScan, relevancy, runtimeObservability.

   # Shorten the learning period so profiles finalize quickly (default is 24h).
   helm repo add kubescape https://kubescape.github.io/helm-charts/ ; helm repo update ; \
   helm upgrade --install kubescape kubescape/kubescape-operator -n kubescape --create-namespace \
     --set clusterName=`kubectl config current-context` \
     --set nodeAgent.config.maxLearningPeriod=10m 
   

2. Wait for scans to populate (vulnerability manifests, application profiles).

3. Invoke the kubescape_check_health tool through a kagent agent (or the MCP server directly).

🤔 Expected Behavior

The health check should recognize the spdx.softwarecomposition.kubescape.io/v1beta1
resources as installed whenever they are served by the aggregated API server,
regardless of whether a CustomResourceDefinition object exists. The presence
check should therefore be based on API availability, not CRD existence.

Concretely, either of the following is appropriate:

• Perform a lightweight discovery/list against the aggregated group-version
  (the data-fetching path already does this successfully via spdxClient)
• Check the APIService v1beta1.spdx.softwarecomposition.kubescape.io and its
  Available=True condition.

For reference, the official Kubescape MCP server accesses these resources through an
spdxv1beta1 client created by CreateKsObjectConnection — i.e. via the aggregated-API
client, without any CRD lookup.

📱 Actual Behavior

kubescape_check_health uses apiExtClient to check for
CustomResourceDefinition objects corresponding to ApplicationProfiles,
VulnerabilityManifests, and NetworkNeighborhoods, and reports them as not installed. Representative output (trimmed):

{
  "healthy": false,
  "checks": {
    "application_profiles_crd": {
      "status": "warning",
      "message": "ApplicationProfiles CRD not installed - runtime observability may not be enabled"
    },
    "network_neighborhoods_crd": {
      "status": "warning",
      "message": "NetworkNeighborhoods CRD not installed - runtime observability may not be enabled"
    },
    "vulnerability_crd": {
      "status": "error",
      "message": "VulnerabilityManifests CRD not installed - vulnerability scanning may not be enabled"
    },
    "vulnerability_scan_data": {
      "status": "ok",
      "message": "80 vulnerability manifests found"
    },
    "operator_pods": {
      "status": "ok",
      "message": "9/9 pods running"
    }
  },
  "summary": "Kubescape has issues that need attention",
  "recommendations": [
    "Enable vulnerability scanning in Kubescape Helm chart: ... --set capabilities.vulnerabilityScan=enable",
    "Enable runtime observability for workload behavior analysis: ... --set capabilities.runtimeObservability=enable"
  ]
}

Note the contradiction: vulnerability_crd = error ("not installed") vs. vulnerability_scan_data = ok ("80 vulnerability manifests found").

Manual confirmation that the resources are served via aggregated API (not CRD):

# Served by the aggregated API server (Available=True):
$ kubectl get apiservices | grep spdx.softwarecomposition.kubescape.io
v1beta1.spdx.softwarecomposition.kubescape.io   kubescape/storage   True

# NOT present as a CRD:
$ kubectl get crds | grep -E "applicationprofiles|vulnerabilitymanifests|networkneighborhoods"
# (no output)

# Yet fully queryable:
$ kubectl get applicationprofiles -A
(rows are returned)
$ kubectl get vulnerabilitymanifests -A
(rows are returned)

Note also that the two recommendations ("enable vulnerabilityScan", "enable runtimeObservability") point to capabilities that are enabled by default in the operator Helm chart. This is a direct consequence of the CRD-based availability check producing false negatives.

💻 Environment

• OS version: Rocky Linux 8.10 (x86_64) bastion; nodes on Amazon Linux
• Kubernetes: v1.35.6 (EKS)
• Kubernetes Provider: AWS (EKS)
• kagent-tools / MCP server version: v0.2.1
• Kubescape operator: v4.0.5 (Helm chart 1.40.2)
• Namespace: kubescape

🔍 Additional Context

Root cause (from source): In pkg/kubescape/kubescape.go, KubescapeTool holds a dedicated apiExtClient "for verifying CRD existence", and handleCheckHealth uses it to check these resources. Since they are aggregated-API resources (not CRDs), this client is the wrong mechanism — hence the false negative described above.

Suggested fix: Replace the CRD-existence check with an API-availability check,
as described in Expected Behavior — a lightweight request through the existing
spdxClient (preferred), optionally corroborated by the APIService
Available=True condition. CRD existence should not be used as the availability
criterion for these resources.

References:

• Kubescape Storage (aggregated API server, based on sample-apiserver): https://github.com/kubescape/storage
• Kubescape 4.0 GA announcement (Storage / Aggregated API): https://www.cncf.io/blog/2026/03/26/announcing-kubescape-4-0-enterprise-stability-meets-the-ai-era/
• Official Kubescape MCP server (uses spdxv1beta1 client, no CRD check): https://pkg.go.dev/github.com/kubescape/kubescape/v3/cmd/mcpserver