feat: Add host-capabilities whitelist

[viccuad]

Description

This PR:

• policy-evaluator, kwctl, policy-server: accept the host-capabilities allow list.
  • Add new crates/policy-evaluator/src/host_capabilities_allow_list.rs with new HostCapabilitiesAllowList{}
  • HostCapabilitiesAllowList::default() provides an empty list, no capabilities allowed. We provide a new HostCapabilitiesAllowList::allow_all() to use as "default" constructor.
• controller:
  • implement PolicyServer.spec.namespacedPoliciesCapabilities
  • Support hostCapabilities field in policies.yml
• kubewarden-defaults Helm chart:
  • Provide new .Values.policyServer.namespacedPoliciesCapabilities
  • Extend json schema.
• kwctl: Enhance kwctl annotate and kwctl run to understand the new policy metadata hostCapabilities list. kwctl annotate now has a new heuristics on the Wasm module to discover declared host capabilities.

All changes are backwards-compatible with the default settings.

Test

CI. Added unit tests and integration tests where needed.
Pre-validated while under embargo.

Additional Information

For manual testing, use tilt up to create the environment, then define the following policies:

apiVersion: policies.kubewarden.io/v1
kind: AdmissionPolicy
metadata:
  name: privileged-pods
  namespace: default
spec:
  module: registry://ghcr.io/kubewarden/policies/pod-privileged:v0.2.2
  rules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      resources: ["pods"]
      operations:
        - CREATE
        - UPDATE
  mutating: false
---
apiVersion: policies.kubewarden.io/v1
kind: ClusterAdmissionPolicy
metadata:
  name: psp-capabilities
spec:
  policyServer: default
  module: registry://ghcr.io/kubewarden/policies/capabilities-psp:v1.0.10
  rules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      resources: ["pods"]
      operations:
        - CREATE
        - UPDATE
  mutating: true
  settings:
    allowed_capabilities:
      - CHOWN
    required_drop_capabilities:
      - NET_ADMIN
---
apiVersion: policies.kubewarden.io/v1
kind: AdmissionPolicyGroup
metadata:
  name: privileged-pods
  namespace: default
spec:
  rules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      resources: ["pods"]
      operations:
        - CREATE
        - UPDATE
  policies:
    policy:
      module: registry://ghcr.io/kubewarden/policies/pod-privileged:v0.2.2
  expression: "policy() && true"
  message: "privileged-pods policy group rejected the request"
---
apiVersion: policies.kubewarden.io/v1
kind: ClusterAdmissionPolicyGroup
metadata:
  name: psp-capabilities
spec:
  policyServer: default
  rules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      resources: ["pods"]
      operations:
        - CREATE
        - UPDATE
  policies:
    policy:
      module: registry://ghcr.io/kubewarden/policies/capabilities-psp:v1.0.10
      settings:
        allowed_capabilities:
          - CHOWN
        required_drop_capabilities:
          - NET_ADMIN
  expression: "policy() && true"
  message: "psp-capabilities policy group rejected the request"

Edit the default PolicyServer and change this attribute from:

  namespacedPoliciesCapabilities:
  - "*"

To something different like:

  namespacedPoliciesCapabilities:
  - net/*
  - oci/*

Changing this attribute will lead to a restart of the PolicyServer
Then look at the contents of the ConfigMap of the policy server, more specifically to the policies.yml atribute:

kubectl get configmaps -n kubewarden policy-server-default -o json | yq '.data["policies.yml"]' | yq -P

The output will be quite long (4 policies!), what you have to look for:

• cluster wide policies must have hostCapabilities set to ['*']
• namespaced policies must have hostCapabilities set according to the value you put inside of the default PolicyServer definition

By default, our helm chart will configure the default PolicyServer to give * to all the namespaced policies. That's fine and intended to avoid breaking users

Test

To test this pull request, you can run the following commands:

Additional Information

Tradeoff

Potential improvement

Checklist

• I have read and understood the Kubewarden AI Policy

[codecov]

Codecov Report

❌ Patch coverage is 95.63164% with 37 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.04%. Comparing base (5eacbd8) to head (92f2322).
⚠️ Report is 57 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/policy-evaluator/src/runtimes/callback.rs	91.96%	20 Missing ⚠️
crates/policy-evaluator/src/host_capabilities.rs	96.34%	9 Missing ⚠️
...cy-server/src/evaluation/evaluation_environment.rs	80.48%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1693      +/-   ##
==========================================
- Coverage   80.44%   77.04%   -3.41%     
==========================================
  Files         127      172      +45     
  Lines       16413    21499    +5086     
==========================================
+ Hits        13204    16564    +3360     
- Misses       3209     4722    +1513     
- Partials        0      213     +213     

Flag	Coverage Δ
go-tests	57.97% <100.00%> (?)
rust-tests	82.14% <95.28%> (+1.69%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds end-to-end support for host-capabilities allow-listing (policy metadata, controller → policy-server config propagation, kwctl UX, and validation), enabling policies to be restricted to specific host capability API calls.

Changes:

• Controller: propagates PolicyServer.spec.namespacedPoliciesCapabilities into generated policies.yml as per-policy/per-member hostCapabilities.
• Policy execution: introduces host-capability pattern parsing/enforcement in policy-evaluator and wires it through policy-server evaluation contexts.
• kwctl: adds --allowed-host-capabilities, adds Wasm scanning heuristics for declared capabilities, and extends tests/docs.

Reviewed changes

Copilot reviewed 53 out of 54 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
internal/controller/utils_test.go	Adds shared Gomega matchers to assert hostCapabilities in generated configmap policies.yml.
internal/controller/policyserver_controller_test.go	Extends controller tests to validate hostCapabilities propagation for policies and group members.
internal/controller/policyserver_controller_configmap.go	Adds hostCapabilities to configmap policy entries and derives namespaced vs cluster-wide capability defaults.
docs/crds/CRD-docs-for-docs-repo.md	Documents namespacedPoliciesCapabilities in PolicyServer CRD docs (markdown).
docs/crds/CRD-docs-for-docs-repo.adoc	Documents namespacedPoliciesCapabilities in PolicyServer CRD docs (asciidoc).
crates/policy-server/tests/sigstore.rs	Updates test config to include host_capabilities field.
crates/policy-server/tests/integration_test.rs	Adds integration tests covering allow/deny behavior for host capability gating.
crates/policy-server/tests/data/deployment_admission_review.json	Adds an admission review fixture for host-capabilities/context-aware tests.
crates/policy-server/tests/common/mod.rs	Extends test config builders to support host capabilities and context-aware test policies/groups.
crates/policy-server/src/evaluation/evaluation_environment.rs	Threads HostCapabilities into EvaluationContext creation and rehydration paths.
crates/policy-server/src/config.rs	Adds host_capabilities fields to policy and group-member config structures (+ example docs).
crates/policy-evaluator/tests/k8s_mock/mod.rs	Adds a no-op k8s mock scenario for cases where callbacks must not occur (capability denied).
crates/policy-evaluator/tests/integration_test.rs	Adds integration coverage for host capability allow/deny behavior.
crates/policy-evaluator/src/runtimes/wapc/runtime.rs	Makes validate_settings take &self and updates tests for new eval context fields.
crates/policy-evaluator/src/runtimes/rego/runtime.rs	Makes validate_settings take &self (parity with wapc runtime).
crates/policy-evaluator/src/runtimes/callback.rs	Enforces host-capability checks before dispatching callbacks (except tracing).
crates/policy-evaluator/src/policy_metadata.rs	Adds optional host_capabilities to policy metadata.
crates/policy-evaluator/src/policy_group_evaluator/evaluator.rs	Propagates host capabilities into group member evaluation contexts.
crates/policy-evaluator/src/policy_group_evaluator.rs	Extends group member settings to carry host capabilities.
crates/policy-evaluator/src/policy_artifacthub.rs	Updates tests/fixtures for new metadata field.
crates/policy-evaluator/src/lib.rs	Exposes new host_capabilities module.
crates/policy-evaluator/src/host_capabilities.rs	Introduces capability pattern parsing/validation and operation enumeration.
crates/policy-evaluator/src/evaluation_context.rs	Adds host capabilities to evaluation context + access-check helper.
crates/policy-evaluator/src/errors.rs	Adds HostCapabilitiesPatternError for pattern validation failures.
crates/policy-evaluator/Cargo.toml	Bumps policy-evaluator crate version.
crates/kwctl/tests/e2e.rs	Adds e2e coverage for host-capability gating and annotate warnings.
crates/kwctl/tests/data/context-aware-annotate/metadata-wrong.yml	Adds metadata fixture with intentionally wrong host capabilities list.
crates/kwctl/tests/data/context-aware-annotate/metadata-correct.yml	Adds metadata fixture with correct host capabilities list.
crates/kwctl/tests/common/mod.rs	Minor import consolidation for test helpers.
crates/kwctl/src/wasm_scanner.rs	Adds Wasm data-segment scanner to detect used host capabilities.
crates/kwctl/src/scaffold/manifest.rs	Updates scaffold manifest tests for new metadata field.
crates/kwctl/src/main.rs	Registers new wasm_scanner module.
crates/kwctl/src/config/pull_and_run.rs	Passes CLI --allowed-host-capabilities into YAML policy parsing.
crates/kwctl/src/config/policy_definition.rs	Stores allowed host caps on policy definitions and applies CLI allow list for YAML-defined policies/groups.
crates/kwctl/src/command/run/evaluator.rs	Wires allowed host caps into EvaluationContext; boxes evaluator for enum size.
crates/kwctl/src/cli.rs	Adds --allowed-host-capabilities option (default *) to run-related commands.
crates/kwctl/src/annotate.rs	Scans Wasm for used capabilities and warns on mismatch vs metadata hostCapabilities.
crates/kwctl/cli-docs.md	Documents new CLI flag in generated CLI docs.
crates/kwctl/Cargo.toml	Adds memchr (scanner) and wasm-encoder (scanner tests) deps.
crates/context-aware-test-policy/metadata.yml	Declares hostCapabilities for the context-aware test policy.
crates/burrego/src/evaluator.rs	Import reformatting/organization.
config/crd/bases/policies.kubewarden.io_policyservers.yaml	Adds CRD schema for namespacedPoliciesCapabilities.
charts/kubewarden-defaults/values.yaml	Adds .Values.policyServer.namespacedPoliciesCapabilities defaulting to ["*"].
charts/kubewarden-defaults/values.schema.json	Adds JSON schema validation for namespacedPoliciesCapabilities.
charts/kubewarden-defaults/tests/namespacedPoliciesCapabilities_test.yaml	Adds Helm schema validation tests for the new value.
charts/kubewarden-defaults/templates/policyserver-default.yaml	Renders namespacedPoliciesCapabilities into the default PolicyServer manifest.
charts/kubewarden-crds/templates/policies.kubewarden.io_policyservers.yaml	Updates CRD chart template with namespacedPoliciesCapabilities schema/docs.
api/policies/v1/zz_generated.deepcopy.go	Updates deepcopy generation for new slice field(s).
api/policies/v1/policyserver_webhook_test.go	Adds webhook validation tests for namespacedPoliciesCapabilities patterns.
api/policies/v1/policyserver_webhook.go	Adds capability-tree-based validation for PolicyServer.spec.namespacedPoliciesCapabilities.
api/policies/v1/policyserver_types.go	Adds NamespacedPoliciesCapabilities to the PolicyServerSpec API type.
api/policies/v1/factories.go	Extends PolicyServer test factory/builder to set capabilities list.
Cargo.lock	Updates lockfile for new deps and version bumps.
.github/workflows/build-kwctl.yml	Adds contents: read permissions to workflow jobs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.