This is unreleased documentation for Policy Manager 1.24-next.

Audit Scanner - Policy Reports

When using the Kubewarden Audit Scanner, you store the results of policy scans using the PolicyReport Custom Resource.

The PolicyReport CRDs are under development in the wg-policy Kubernetes group. Therefore, this documentation becomes out of date if a new version release of the CRDs.

Check the wg-policy group repository for more information about the CRDs.

These CRDs offer a structured way to store and manage the audit results.

You store audit scanner policy scan results using PolicyReport and ClusterPolicyReport. The audit scanner creates a PolicyReport or a ClusterPolicyReport for each resource scanned, depending on the scope of the resource. PolicyReport objects are available in the resource’s namespace, while ClusterPolicyReport objects are available in the cluster scope.

The audit results generated by the scanner include:

the policy evaluated
the resource scanned
the result of the evaluation (pass, fail, or skip)
a timestamp indicating when the evaluation took place.

You can also define severity and category annotations for your policies.

Operators can query the reports by using kubectl. They can also use the optional UI provided by the policy-reporter open-source project for monitoring and observability of the PolicyReport CRDs.

Querying the reports

Using the kubectl CLI, it’s possible to query the results of the scan:

List the reports in the default namespace:

$ kubectl get polr -o wide

NAME                                   KIND         NAME                        PASS   FAIL   WARN   ERROR   SKIP   AGE
009805e4-6e16-4b70-80c9-cb33b6734c82   Deployment   deployment1                 5      1      0      0       0      1h
011e8ca7-40d5-4e76-8c89-6f820e24f895   Deployment   deployment2                 2      4      0      0       0      1h
02c28ab7-e332-47a2-9cc2-fe0fad5cd9ad   Pod          pod1                        10     0      0      0       0      1h
04937b2b-e68b-47d5-909d-d0ae75527f07   Pod          pod2                        9      1      0      0       0      1h
…

List the cluster-wide reports:

$ kubectl get cpolr -o wide

NAME                                   KIND        NAME                 PASS   FAIL   WARN   ERROR   SKIP   AGE
261c9492-deec-4a09-8aa9-cd464bb4b8d1   Namespace   namespace1           3      1     0       0       0      1h
35ca342f-685b-4162-a342-8d7a52a61749   Namespace   namespace2           0      4     0       0       0      1h
3a8f8a88-338b-4905-b9e4-f13397a0d7b5   Namespace   namespace3           4      0     0       0       0      15h

Get the details of a specific PolicyReport:

kubectl get polr 009805e4-6e16-4b70-80c9-cb33b6734c82 -o yaml

Get the details of a specific ClusterPolicyReport:

kubectl get cpolr 261c9492-deec-4a09-8aa9-cd464bb4b8d1 -o yaml

PolicyReport example

The following example shows a PolicyReport for the Deployment resource deployment1 in the default namespace. The report indicates that the Pod failed the safe-labels AdmissionPolicy.

apiVersion: wgpolicyk8s.io/v1beta1
kind: PolicyReport
metadata:
  creationTimestamp: “2024-02-29T06:55:37Z”
  generation: 6
  labels:
    app.kubernetes.io/managed-by: kubewarden
    kubewarden.io/policyreport-version: v2
  name: 009805e4-6e16-4b70-80c9-cb33b6734c82
  namespace: default
  ownerReferences:
    - apiVersion: apps/v1
      kind: Deployment
      name: deployment1
      uid: 009805e4-6e16-4b70-80c9-cb33b6734c82
  resourceVersion: “2685996”
  uid: c5a88847-d678-4733-8120-1b83fd6330cb
results:
  - category: Resource validation
    message: “The following mandatory labels are missing: cost-center”
    policy: namespaced-default-safe-labels
    properties:
      policy-resource-version: “2684810”
      policy-uid: 826dd4ef-9db5-408e-9482-455f278bf9bf
      policy-name: “safe-labels”
      policy-namespace: “default”
      validating: “true”
    resourceSelector: {}
    result: fail
    scored: true
    severity: low
    source: kubewarden
    timestamp:
      nanos: 0
      seconds: 1709294251
scope:
  apiVersion: apps/v1
  kind: Deployment
  name: deployment1
  namespace: default
  resourceVersion: “3”
  uid: 009805e4-6e16-4b70-80c9-cb33b6734c82
summary:
  error: 0
  fail: 1
  pass: 0
  skip: 0
  warn: 0yaml

ClusterPolicyReport example

The following example shows a ClusterPolicyReport for the Namespace resource default. The report indicates that the resource has failed the safe-annotations ClusterAdmissionPolicy validation.

apiVersion: wgpolicyk8s.io/v1beta1
kind: ClusterPolicyReport
metadata:
  creationTimestamp: “2024-02-28T14:44:37Z”
  generation: 3
  labels:
    app.kubernetes.io/managed-by: kubewarden
    kubewarden.io/policyreport-version: v2
  name: 261c9492-deec-4a09-8aa9-cd464bb4b8d1
  ownerReferences:
    - apiVersion: v1
      kind: Namespace
      name: default
      uid: 261c9492-deec-4a09-8aa9-cd464bb4b8d1
  resourceVersion: “2403034”
  uid: 20a3d00e-e955-4f21-a887-317d40f3f052
results:
  - category: Resource validation
    message: “The following mandatory annotations are not allowed: owner”
    policy: clusterwide-safe-annotations
    properties:
      policy-resource-version: “2396437”
      policy-uid: 46780d6e-e51a-4d65-8572-a6af01380aa7
      policy-name: “safe-annotations”
      validating: “true”
    resourceSelector: {}
    result: fail
    scored: true
    severity: low
    source: kubewarden
    timestamp:
      nanos: 0
      seconds: 1709294251
scope:
  apiVersion: v1
  kind: Namespace
  name: default
  resourceVersion: “37”
  uid: 261c9492-deec-4a09-8aa9-cd464bb4b8d1
summary:
  error: 0
  fail: 1
  pass: 0
  skip: 0
  warn: 0yaml

Policy Reporter UI

The Policy Reporter ships as a subchart of kubewarden-controller. Refer to the Audit Scanner Installation page for more information.

The Policy Reporter UI provides a dashboard showing all violations. See the screenshot below:

Kubewarden ships the Policy Reporter UI with a preconfigured filter that only shows Kubewarden policies, along with expanded information:

Other features of Policy Reporter include forwarding of results to different clients (like Grafana Loki, Elasticsearch, chat applications), metrics endpoints, and more. See the policy-reporter’s community docs for more information.