This is unreleased documentation for Admission Controller 1.31-dev.

Audit Scanner - Policy Reports

When using the SUSE Security Admission Controller Audit Scanner, you store the results of policy scans using the OpenReports Custom Resources.

Since Kubewarden 1.30, PolicyReport Custom Resources ship as defaults but are marked as deprecated.

This page explains the usage of the new Reports and ClusterReports from OpenReports, which are functionally equal.

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

You store audit scanner policy scan results using Report and ClusterReport. The audit scanner creates a Report or a ClusterReport for each resource scanned, depending on the scope of the resource. Report objects are available in the resource’s namespace, while ClusterReport 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 OpenReports 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 report -o wide
NAME                                   KIND   NAME            PASS   FAIL   WARN   ERROR   SKIP   AGE
44da974b-6057-4745-a92c-9dd8a1b01cc4   Pod    nginx-secrets   6      1      0      0       0      33m

List the cluster-wide reports:

$ kubectl get clusterreport -o wide
NAME                                   KIND        NAME                 PASS   FAIL   WARN   ERROR   SKIP   AGE
6c66175f-e15f-47e8-8c33-2c63d5ecde3e   Namespace   namespace1           3      1     0       0       0      1h
d0ffbf4f-7348-4350-af7b-fdbfc079cc49   Namespace   namespace2           0      4     0       0       0      1h
e48d9bbc-a9c4-4c36-8519-bc7390d9ec64   Namespace   namespace3           4      0     0       0       0      15h

Get the details of a specific Report:

kubectl get report 44da974b-6057-4745-a92c-9dd8a1b01cc4 -o yaml

Get the details of a specific ClusterReport:

kubectl get clusterreport e48d9bbc-a9c4-4c36-8519-bc7390d9ec64 -o yaml

Report example

The following example shows a Report 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

ClusterReport example

The following example shows a ClusterReport 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 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:

Admission Controller ships the Policy Reporter UI with a preconfigured filter that only shows Admission Controller 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.