Audit Scanner - Policy Reports
When using the Kubewarden Audit Scanner, the results of the policy scans are stored using the PolicyReport Custom Resource.
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.
As shown below, it also provides a tab for PolicyReports, and a tab for ClusterPolicyReports, with expanded information.
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.