Merge pull request #379 from nirmata/337_policy_description

337 policy description

pkg/webhooks/annotations.go

@@ -10,7 +10,7 @@ import (
 )
 
 const (
-	policyAnnotation = "policies.kyverno.io"
+	policyAnnotation = "policies.kyverno.io/patches"
 )
 
 type policyPatch struct {

pkg/webhooks/annotations_test.go

@@ -35,7 +35,7 @@ func Test_empty_annotation(t *testing.T) {
 	engineResponse := newEngineResponse("mutate-container", "default-imagepullpolicy", []string{patchStr}, true)
 
 	annPatches := generateAnnotationPatches(nil, []engine.EngineResponse{engineResponse})
-	expectedPatches := `{"op":"add","path":"/metadata/annotations","value":{"policies.kyverno.io":"[{\"policyname\":\"mutate-container\",\"patches\":[{\"rulename\":\"default-imagepullpolicy\",\"op\":\"replace\",\"path\":\"/spec/containers/0/imagePullPolicy\"}]}]"}}`
+	expectedPatches := `{"op":"add","path":"/metadata/annotations","value":{"policies.kyverno.io/patches":"[{\"policyname\":\"mutate-container\",\"patches\":[{\"rulename\":\"default-imagepullpolicy\",\"op\":\"replace\",\"path\":\"/spec/containers/0/imagePullPolicy\"}]}]"}}`
 	assert.Assert(t, string(annPatches) == expectedPatches)
 }
 
@@ -48,26 +48,26 @@ func Test_exist_annotation(t *testing.T) {
 	engineResponse := newEngineResponse("mutate-container", "default-imagepullpolicy", []string{patchStr}, true)
 	annPatches := generateAnnotationPatches(annotation, []engine.EngineResponse{engineResponse})
 
-	expectedPatches := `{"op":"add","path":"/metadata/annotations","value":{"policies.kyverno.io":"[{\"policyname\":\"mutate-container\",\"patches\":[{\"rulename\":\"default-imagepullpolicy\",\"op\":\"replace\",\"path\":\"/spec/containers/0/imagePullPolicy\"}]}]","test":"annotation"}}`
+	expectedPatches := `{"op":"add","path":"/metadata/annotations","value":{"policies.kyverno.io/patches":"[{\"policyname\":\"mutate-container\",\"patches\":[{\"rulename\":\"default-imagepullpolicy\",\"op\":\"replace\",\"path\":\"/spec/containers/0/imagePullPolicy\"}]}]","test":"annotation"}}`
 	assert.Assert(t, string(annPatches) == expectedPatches)
 }
 
 func Test_exist_kyverno_annotation(t *testing.T) {
 	annotation := map[string]string{
-		"policies.kyverno.io": "old-annotation",
+		"policies.kyverno.io/patches": "old-annotation",
 	}
 
 	patchStr := `{ "op": "replace", "path": "/spec/containers/0/imagePullPolicy", "value": "IfNotPresent" }`
 	engineResponse := newEngineResponse("mutate-container", "default-imagepullpolicy", []string{patchStr}, true)
 	annPatches := generateAnnotationPatches(annotation, []engine.EngineResponse{engineResponse})
 
-	expectedPatches := `{"op":"replace","path":"/metadata/annotations/policies.kyverno.io","value":"[{\"policyname\":\"mutate-container\",\"patches\":[{\"rulename\":\"default-imagepullpolicy\",\"op\":\"replace\",\"path\":\"/spec/containers/0/imagePullPolicy\"}]}]"}`
+	expectedPatches := `{"op":"replace","path":"/metadata/annotations/policies.kyverno.io/patches","value":"[{\"policyname\":\"mutate-container\",\"patches\":[{\"rulename\":\"default-imagepullpolicy\",\"op\":\"replace\",\"path\":\"/spec/containers/0/imagePullPolicy\"}]}]"}`
 	assert.Assert(t, string(annPatches) == expectedPatches)
 }
 
 func Test_annotation_nil_patch(t *testing.T) {
 	annotation := map[string]string{
-		"policies.kyverno.io": "old-annotation",
+		"policies.kyverno.io/patches": "old-annotation",
 	}
 
 	engineResponse := newEngineResponse("mutate-container", "default-imagepullpolicy", nil, true)
@@ -82,7 +82,7 @@ func Test_annotation_nil_patch(t *testing.T) {
 
 func Test_annotation_failed_Patch(t *testing.T) {
 	annotation := map[string]string{
-		"policies.kyverno.io": "old-annotation",
+		"policies.kyverno.io/patches": "old-annotation",
 	}
 
 	engineResponse := newEngineResponse("mutate-container", "default-imagepullpolicy", nil, false)

samples/README.md

@@ -27,7 +27,7 @@ Kubernetes automounts default service account credentials in each pod. To restri
 
 ## Disallow use of default namespace
 
-Namespaces are a way to segment and isolate cluster resources across multiple users. When multiple users or teams are sharing a single cluster, it is recommended to isolate different workloads and restrict use of the default namespace.
+With many users spread across multiple teams, restricting use of the default namespace and subdividing the cluster by namesoace isolates workloads.
 
 ***Policy YAML***: [disallow_default_namespace.yaml](best_practices/disallow_default_namespace.yaml) 
 
@@ -141,9 +141,17 @@ All processes inside the pod can be made to run with specific user and groupID b
 
 
 ## Configure kernel parameters inside pod
+
 The Sysctl interface allows to modify kernel parameters at runtime and in the pod can be specified under `securityContext.sysctls`. If kernel parameters in the pod are to be modified, should be handled cautiously, and policy with rules restricting these options will be helpful. We can control minimum and maximum port that a network connection can use as its source(local) port by checking net.ipv4.ip_local_port_range
 
 ***Policy YAML***: [policy_validate_sysctl_configs.yaml](more/policy_validate_sysctl_configs.yaml)
 
 **Additional Information**
 * [List of supported namespaced sysctl interfaces](https://kubernetes.io/docs/tasks/administer-cluster/sysctl-cluster/) 
+
+
+## Check userID, groupIP & fsgroup used inside a Pod
+
+All processes inside the pod can be made to run with specific user and groupID by setting `runAsUser` and `runAsGroup` respectively. `fsGroup` can be specified to make sure any file created in the volume with have the specified groupID. These options can be used to validate the IDs used for user and group.
+
+***Policy YAML***: [policy_validate_user_group_fsgroup_id.yaml](more/policy_validate_user_group_fsgroup_id.yaml)

samples/best_practices/deny_runasrootuser.yaml

@@ -2,6 +2,12 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-deny-runasrootuser
+  annotations:
+    policies.kyverno.io/category: Security Context
+    policies.kyverno.io/description: By default, processes in a container run as a 
+      root user (uid 0). To prevent potential compromise of container hosts, specify a 
+      least privileged user ID when building the container image and require that 
+      application containers run as non root users.
 spec:
   rules:
   - name: deny-runasrootuser

samples/best_practices/disallow_automountingapicred.yaml

@@ -2,6 +2,10 @@ apiVersion : kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-disallow-automoutingapicred
+  annotations:
+    policies.kyverno.io/category: API Server Access Control
+    policies.kyverno.io/description: Kubernetes automounts default service account credentials in each pod. 
+      To restrict access, opt out of automounting credentials by setting 'automountServiceAccountToken' to 'false'.
 spec:
   rules:
   - name: disallow-automoutingapicred

samples/best_practices/disallow_default_namespace.yaml

@@ -2,6 +2,10 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-namespace
+  annotations:
+    policies.kyverno.io/category: Workload Isolation
+    policies.kyverno.io/description: With many users spread across multiple teams, restricting 
+      use of the default namespace and subdividing the cluster by namesoace isolates workloads.
 spec:
   rules:
   - name: check-default-namespace

samples/best_practices/disallow_host_filesystem.yaml

@@ -2,6 +2,11 @@ apiVersion: "kyverno.io/v1alpha1"
 kind: "ClusterPolicy"
 metadata: 
   name: "deny-use-of-host-fs"
+  annotations:
+    policies.kyverno.io/category: Data Protection
+    policies.kyverno.io/description: The volume of type 'hostpath' binds pods to a specific host, 
+      and data persisted in the volume is dependent on the life of the node. In a shared cluster, 
+      it is recommeded that applications are independent of hosts.
 spec: 
   rules: 
   - name: "deny-use-of-host-fs"

samples/best_practices/disallow_host_network_hostport.yaml

@@ -2,6 +2,10 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-host-network-hostport
+  annotations:
+    policies.kyverno.io/category: Security
+    policies.kyverno.io/description: Using 'hostPort' and 'hostNetwork' allows pods to share 
+      the host network stack, allowing potential snooping of network traffic from an application pod.
 spec:
   rules:
   - name: validate-host-network-hostport

samples/best_practices/disallow_hostpid_hostipc.yaml

@@ -2,6 +2,12 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-hostpid-hostipc
+  annotations:
+    policies.kyverno.io/category: Security
+    policies.kyverno.io/description: Sharing the host's PID namespace allows visibility of process 
+      on the host, potentially exposing process information. Sharing the host's IPC namespace allows 
+      the container process to communicate with processes on the host. To avoid pod container from 
+      having visibility to host process space, validate that 'hostPID' and 'hostIPC' are set to 'false'.
 spec:
   rules:
   - name: validate-hostpid-hostipc

samples/best_practices/disallow_node_port.yaml

@@ -2,6 +2,12 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: disallow-node-port
+  annotations:
+    policies.kyverno.io/category: Security
+    policies.kyverno.io/description: A Kubernetes service of type NodePort uses a 
+      host port to receive traffic from any source. A 'NetworkPolicy' resource cannot be used 
+      to control traffic to host ports. Although 'NodePort' services can be useful, their use 
+      must be limited to services with additional upstream security checks.
 spec:
   rules:
   - name: disallow-node-port

samples/best_practices/disallow_priviledged_priviligedescalation.yaml

@@ -2,6 +2,14 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-deny-privileged-priviligedescalation
+  annotations:
+    policies.kyverno.io/category: Security Context
+    policies.kyverno.io/description: Privileged containers are defined as any container 
+      where the container uid 0 is mapped to the host’s uid 0. A process within privileged 
+      containers can get unrestricted host access. With 'securityContext.allowPrivilegeEscalation' 
+      enabled a process can gain privileges from its parent. To disallow privileged containers 
+      and the escalation of privileges it is recommended to run pod containers with 
+      'securityContext.priveleged' as 'false' and 'allowPrivilegeEscalation' as 'false'.
 spec:
   rules:
   - name: deny-privileged-priviligedescalation

samples/best_practices/require_default_network_policy.yaml

@@ -2,6 +2,12 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: default-deny-ingress-networkpolicy
+  annotations:
+    policies.kyverno.io/category: NetworkPolicy
+    policies.kyverno.io/description: By default, Kubernetes allows all ingress and egress traffic 
+      to and from pods within a cluster. A "default" NetworkPolicy resource for a namespace should 
+      be used to deny all ingress traffic to the pods in that namespace. Additional NetworkPolicy 
+      resources can then be configured to allow desired traffic to application pods.
 spec:
   rules:
   - name: "default-deny-ingress"

samples/best_practices/require_image_tag_not_latest.yaml

@@ -2,6 +2,11 @@ apiVersion : kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-image-tag
+  annotations:
+    policies.kyverno.io/category: Image
+    policies.kyverno.io/description: The ':latest' tag is mutable and can lead to 
+      unexpected errors if the image changes. A best practice is to use an immutable 
+      tag that maps to a specific version of an application pod.
 spec:
   rules:
   - name: image-tag-notspecified

samples/best_practices/require_namespace_quota.yaml

@@ -2,6 +2,11 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-namespace-quota
+  annotations:
+    policies.kyverno.io/category: Resource Quota
+    policies.kyverno.io/description: To limit the number of objects, as well as the 
+      total amount of compute that may be consumed by an application, it is important 
+      to create resource limits and quotas for each namespace.
 spec:
   rules:
   - name: validate-namespace-quota

samples/best_practices/require_pod_requests_limits.yaml

@@ -2,6 +2,12 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: check-resource
+  annotations:
+    policies.kyverno.io/category: Resource Quota
+    policies.kyverno.io/description: As application workloads share cluster resources, it is important 
+      to limit resources requested and consumed by each pod. It is recommended to require 
+      'resources.requests' and 'resources.limits' per pod. If a namespace level request or limit is 
+      specified, defaults will automatically be applied to each pod based on the 'LimitRange' configuration.
 spec:
   validationFailureAction: "audit"
   rules:

samples/best_practices/require_probes.yaml

@@ -2,6 +2,12 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-probes
+  annotations:
+    policies.kyverno.io/category: Health Check
+    policies.kyverno.io/description: For each pod, a 'livenessProbe' is carried out by the kubelet to 
+      determine when to restart a container. A 'readinessProbe' is used by services and deployments to 
+      determine if the pod is ready to recieve network traffic. Both liveness and readiness probes 
+      need to be configured to manage the pod lifecycle during restarts and upgrades.
 spec:
   rules:
   - name: check-probes

samples/best_practices/require_readonly_rootfilesystem.yaml

@@ -2,6 +2,12 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-readonly-rootfilesystem
+  annotations:
+    policies.kyverno.io/category: Security Context
+    policies.kyverno.io/description: A read-only root file system helps to enforce an immutable 
+      infrastructure strategy; the container only needs to write on the mounted volume that p
+      ersists the state. An immutable root filesystem can also prevent malicious binaries from 
+      writing to the host system.
 spec:
   rules:
   - name: validate-readonly-rootfilesystem

samples/best_practices/trusted_image_registries.yaml

@@ -2,6 +2,11 @@ apiVersion : kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: trusted-registries
+  annotations:
+    policies.kyverno.io/category: Image
+    policies.kyverno.io/description: Images from unknown registries may not be scanned and secured. 
+      Requiring use of known registries helps reduce threat exposure. You can customize this policy 
+      to allow image registries that you trust.
 spec:
   rules:
   - name: trusted-registries

samples/more/policy_validate_container_capabilities.yaml

@@ -2,6 +2,11 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-container-capablities
+  annotations:
+    policies.kyverno.io/category: Security Context
+    policies.kyverno.io/description: Linux divides the privileges traditionally associated with 
+      superuser into distinct units, known as capabilities, which can be independently enabled 
+      or disabled by listing them in 'securityContext.capabilites'.
 spec:
   rules:
   - name: validate-container-capablities

samples/more/policy_validate_sysctl_configs.yaml

@@ -2,6 +2,13 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-allow-portrange-with-sysctl
+  annotations:
+    policies.kyverno.io/category: Security Context
+    policies.kyverno.io/description: The Sysctl interface allows to modify kernel parameters at 
+      runtime and in the pod can be specified under 'securityContext.sysctls'. If kernel parameters  
+      in the pod are to be modified, should be handled cautiously, and policy with rules restricting 
+      these options will be helpful. We can control minimum and maximum port that a network connection 
+      can use as its source(local) port by checking 'net.ipv4.ip_local_port_range'.
 spec:
   rules:
   - name: allow-portrange-with-sysctl

samples/more/policy_validate_user_group_fsgroup_id.yaml

@@ -2,6 +2,12 @@ apiVersion: kyverno.io/v1alpha1
 kind: ClusterPolicy
 metadata:
   name: validate-userid-groupid-fsgroup
+  annotations:
+    policies.kyverno.io/category: Security Context
+    policies.kyverno.io/description: All processes inside the pod can be made to run with specific user 
+      and groupID by setting 'runAsUser' and 'runAsGroup' respectively. 'fsGroup' can be specified 
+      to make sure any file created in the volume with have the specified groupID. These options can be 
+      used to validate the IDs used for user and group.
 spec:
   rules:
   - name: validate-userid