Reporting System

Reports are Kubernetes Custom Resources, generated and managed automatically by Cloud Control Point, which contain the results of applying matching ValidatingPolicy or ImageVerificationPolicy to existing resource. They are created on a fixed interval as defined globally or on every AWSAccountConfig. If the resource matches multiple rules, there will be multiple results in the report. When resources are deleted, the corresponding policy report also gets deleted. Reports, therefore, always represent the current state of the cluster and do not record historical information. Cloud Control Point uses a standard and open format published by the Kubernetes Policy working group which proposes a common policy report format across Kubernetes tools.

Below is a sample ClusterPolicyReport generated by Cloud Control Point for a given ECS TaskDefinition:

apiVersion: wgpolicyk8s.io/v1alpha2
kind: ClusterPolicyReport
metadata:
  creationTimestamp: "2024-11-04T07:04:25Z"
  generation: 1
  labels:
    app.kubernetes.io/managed-by: cloud-control-point
    cloud.policies.nirmata.io/account-id: "123456789101"
    cloud.policies.nirmata.io/account-name: accountname
    cloud.policies.nirmata.io/last-modified: "1730703865"
    cloud.policies.nirmata.io/provider: AWS
    cloud.policies.nirmata.io/region: us-east-1
    cloud.policies.nirmata.io/resource-id: cf987d912031e51752ad73a2067a1c5f9ee06d8872575166c0739ffedfc0766
    cloud.policies.nirmata.io/resource-name: good-task
    cloud.policies.nirmata.io/resource-type: TaskDefinition
    cloud.policies.nirmata.io/service: ecs
    cloud.policies.nirmata.io/ttl: 20m0s
  name: cf987d912031e51752ad73a2067a1c5f9ee06d8872575166c0739ffedfc0766
  resourceVersion: "690"
  uid: 3c9da537-d4b1-40c1-9284-bea79f51853a
results:
- message: Validation rule 'check-task-definition-tags' passed.
  policy: check-task-definition-tags
  result: pass
  rule: check-task-definition-tags
  scored: true
  source: cloud-control
  timestamp:
    nanos: 0
    seconds: 1730703865
scope:
  apiVersion: nirmata.io/v1alpha1
  kind: ECSTaskDefinition
  name: good-task-2
summary:
  error: 0
  fail: 0
  pass: 1
  skip: 0
  warn: 0

The report consists of multiple components:

1. General information about the owner resources in metadata.labels
2. List of results for the rules that match the resource
3. Scope contains the kind and name of the owner resource
4. Summary contains count of results for each result type

Report result logic

Entries in a policy report contain a result field which can be either pass, skip, error, or fail.

Viewing policy report summaries

You can view a summary of the policy reports using the following command:

kubectl get clusterpolicyreports

For example, below are the policy reports in a small test cluster created with kind.

$ kubectl get cpolr
1c4a23fad560fe66ee7d139b456451d8aaf7c75a9aaa12007a37f1d6f3056b9   ECSCluster          bad-cluster      0      1      0      0       0      78s
42652e303978721aa052cce4c5b33b5c3db1e7c3eb8fb39ca2681c422a5d325   ECSCluster          bad-cluster-4    0      1      0      0       0      78s
71ed4b96c24e21830b15ea11f19abb16b947707ea7f8343aa48a5b25228d559   ECSCluster          bad-cluster-2    0      1      0      0       0      78s
91696bc8dbb327de99c4d34c579de8bd71e2ef45ad325d10d39d690ad14776c   ECSTaskDefinition   bad-task__2      0      1      0      0       0      78s
9bf1d560308032c3ca5987cc7a9b2db756d86fe035a7b59732f1ba3e48deda2   ECSCluster          bad-cluster-11   0      1      0      0       0      78s
cf987d912032e51712ad73a2067a1c5ffee16d8872575166c0739ffedfc0766   ECSTaskDefinition   good-task__2     1      0      0      0       0      78s
d1b1118f087d2e756a437727f8a1e4147c86dd4729381a4451ea944a0701968   ECSCluster          bad-test         0      1      0      0       0      78s

Viewing policy violations

Since the report provides information on all rule and resource execution, returning only select entries requires a filter expression.

Policy reports can be inspected using either kubectl describe or kubectl get. For example, here is a command, requiring yq, to view only failures for the policy report 1c4a23fad560fe66ee7d139b456451d8aaf7c75a9aaa12007a37f1d6f3056b9:

$ kubectl get cpolr 1c4a23fad560fe66ee7d139b456451d8aaf7c75a9aaa12007a37f1d6f3056b9 -o jsonpath='{.results[?(@.result=="fail")]}' | yq -p json -

Output:

message: |-
  -> A 'group' tag is required
   -> all[0].check.payload.(tags[?key=='group'] || `[]`).(length(@) > `0`): Invalid value: false: Expected value: true  
policy: check-ecs-cluster-tags
result: fail
rule: check-tags
scored: true
source: cloud-control
timestamp:
  nanos: 0
  seconds: 1731055159

Policy reports deletion

Cloud control point uses a TTL based approach to deleting reports. If a policy report has not been updated for sometime, the policy report is then marked as stale and deleted. The TTL duration for a report is the scanInterval for the resource. If a report has not been updated for 1 scan interval for any reason (such as the resource has been deleted, the configuration has been updated, cloud control point cannot access the resource anymore), the report gets deleted.

Report internals

The ClusterPolicyReport is the final resources composed of results for policies matching a resource as determined by Cloud Control Point. However these reports are built from intermediary resources. For results of scanning, ClusterEphemeralReport are created which has the same basic contents as a policy report and are used internally by Cloud Control Point to build the final policy report. Cloud Control Point will merge these results automatically into the appropriate policy report and there is no manual interaction required.