Skip to main content
Version: Next 🚧

Audit Scanner - Policy Reports

When using the Kubewarden Audit Scanner, the results of the policy scans are stored using the PolicyReport Custom Resource.

caution

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

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.

PolicyReport and ClusterPolicyReport are used to store the results of the policy scans performed by the audit scanner. The audit scanner will create a PolicyReport or a ClusterPolicyReport for each resource scanned, depending on the scope of the resource. PolicyReport objects are available in the namespace where the resource is located, while ClusterPolicyReport objects are available in the cluster scope.

The audit results generated by the scanner include:

  • the policy that was evaluated
  • the resource being 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 command line tool, it is 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: 0

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: 0

Policy Reporter UI​

The Policy Reporter is shipped 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 from PolicyReports and the ClusterPolicyReport. This is shown below.

Policy Reporter dashboard example

As shown below, it also provides a tab for PolicyReports, and a tab for ClusterPolicyReports, with expanded information.

Policy Reporter PolicyReports example

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