Update text of linting rules descriptions and remediations (#172)

docs/generated/checks.md

@@ -6,9 +6,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on services that don't have any matching deployments
+**Description**: Indicates when services do not have any associated deployments.
 
-**Remediation**: Make sure your service's selector correctly matches the labels on one of your deployments.
+**Remediation**: Confirm that your service's selector correctly matches the labels on one of your deployments.
 
 **Template**: [dangling-service](generated/templates.md#dangling-services)
 
@@ -22,9 +22,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: No
 
-**Description**: Alert on pods that use the default service account
+**Description**: Indicates when pods use the default service account.
 
-**Remediation**: Create a dedicated service account for your pod. See https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ for more details.
+**Remediation**: Create a dedicated service account for your pod. Refer to https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ for details.
 
 **Template**: [service-account](generated/templates.md#service-account)
 
@@ -38,9 +38,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on deployments that use the deprecated serviceAccount field
+**Description**: Indicates when deployments use the deprecated serviceAccount field.
 
-**Remediation**: Use the serviceAccountName field instead of the serviceAccount field.
+**Remediation**: Use the serviceAccountName field instead.
 
 **Template**: [deprecated-service-account-field](generated/templates.md#deprecated-service-account-field)
 
@@ -54,9 +54,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on containers not dropping NET_RAW capability
+**Description**: Indicates when containers do not drop NET_RAW capability
 
-**Remediation**: NET_RAW grants an application within the container the ability to craft raw packets, use raw sockets, and it also allows an application to bind to any address. Please specify to drop this capability in the containers under containers security contexts.
+**Remediation**: NET_RAW makes it so that an application within the container is able to craft raw packets, use raw sockets, and bind to any address. Remove this capability in the containers under containers security contexts.
 
 **Template**: [verify-container-capabilities](generated/templates.md#verify-container-capabilities)
 
@@ -70,9 +70,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on objects using a secret in an environment variable
+**Description**: Indicates when objects use a secret in an environment variable.
 
-**Remediation**: Don't use raw secrets in an environment variable. Instead, either mount the secret as a file or use a secretKeyRef. See https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets for more details.
+**Remediation**: Do not use raw secrets in environment variables. Instead, either mount the secret as a file or use a secretKeyRef. Refer to https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets for details.
 
 **Template**: [env-var](generated/templates.md#environment-variables)
 
@@ -86,9 +86,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on deployments where the selector doesn't match the pod template labels
+**Description**: Indicates when deployment selectors fail to match the pod template labels.
 
-**Remediation**: Make sure your deployment's selector correctly matches the labels in its pod template.
+**Remediation**: Confirm that your deployment selector correctly matches the labels in its pod template.
 
 **Template**: [mismatching-selector](generated/templates.md#mismatching-selector)
 
@@ -102,9 +102,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on deployments with multiple replicas that don't specify inter pod anti-affinity to ensure that the orchestrator attempts to schedule replicas on different nodes
+**Description**: Indicates when deployments with multiple replicas fail to specify inter-pod anti-affinity, to ensure that the orchestrator attempts to schedule replicas on different nodes.
 
-**Remediation**: Specify anti-affinity in your pod spec to ensure that the orchestrator attempts to schedule replicas on different nodes. You can do this by using podAntiAffinity, specifying a labelSelector that matches pods of this deployment, and setting the topologyKey to kubernetes.io/hostname. See https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity for more details.
+**Remediation**: Specify anti-affinity in your pod specification to ensure that the orchestrator attempts to schedule replicas on different nodes. Using podAntiAffinity, specify a labelSelector that matches pods for the deployment, and set the topologyKey to kubernetes.io/hostname. Refer to https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity for details.
 
 **Template**: [anti-affinity](generated/templates.md#anti-affinity-not-specified)
 
@@ -118,9 +118,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on objects using deprecated API versions under extensions v1beta
+**Description**: Indicates when objects use deprecated API versions under extensions/v1beta.
 
-**Remediation**: Migrate to using the apps/v1 API versions for these objects. See https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/ for more details.
+**Remediation**: Migrate using the apps/v1 API versions for the objects. Refer to https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/ for details.
 
 **Template**: [disallowed-api-obj](generated/templates.md#disallowed-api-objects)
 
@@ -134,9 +134,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: No
 
-**Description**: Alert on containers which don't specify a liveness probe
+**Description**: Indicates when containers fail to specify a liveness probe.
 
-**Remediation**: Specify a liveness probe in your container. See https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ for more details.
+**Remediation**: Specify a liveness probe in your container. Refer to https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ for details.
 
 **Template**: [liveness-probe](generated/templates.md#liveness-probe-not-specified)
 
@@ -150,9 +150,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on containers not running with a read-only root filesystem
+**Description**: Indicates when containers are running without a read-only root filesystem.
 
-**Remediation**: Set readOnlyRootFilesystem to true in your container's securityContext.
+**Remediation**: Set readOnlyRootFilesystem to true in the container securityContext.
 
 **Template**: [read-only-root-fs](generated/templates.md#read-only-root-filesystems)
 
@@ -166,9 +166,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: No
 
-**Description**: Alert on containers which don't specify a readiness probe
+**Description**: Indicates when containers fail to specify a readiness probe.
 
-**Remediation**: Specify a readiness probe in your container. See https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ for more details.
+**Remediation**: Specify a readiness probe in your container. Refer to https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ for details.
 
 **Template**: [readiness-probe](generated/templates.md#readiness-probe-not-specified)
 
@@ -182,9 +182,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on pods referencing a service account that isn't found
+**Description**: Indicates when pods reference a service account that is not found.
 
-**Remediation**: Make sure to create the service account, or to refer to an existing service account.
+**Remediation**: Create the missing service account, or refer to an existing service account.
 
 **Template**: [non-existent-service-account](generated/templates.md#non-existent-service-account)
 
@@ -198,9 +198,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on deployments with containers running in privileged mode
+**Description**: Indicates when deployments have containers running in privileged mode.
 
-**Remediation**: Don't run your container as privileged unless required.
+**Remediation**: Do not run your container as privileged unless it is required.
 
 **Template**: [privileged](generated/templates.md#privileged-containers)
 
@@ -214,9 +214,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: No
 
-**Description**: Alert on objects without an 'email' annotation with a valid email
+**Description**: Indicates when objects do not have an email annotation with a valid email address.
 
-**Remediation**: Add an email annotation to your object with the contact information of the object's owner.
+**Remediation**: Add an email annotation to your object with the email address of the object's owner.
 
 **Template**: [required-annotation](generated/templates.md#required-annotation)
 
@@ -230,9 +230,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: No
 
-**Description**: Alert on objects without the 'owner' label
+**Description**: Indicates when objects do not have an email annotation with an owner label.
 
-**Remediation**: Add an email annotation to your object with information about the object's owner.
+**Remediation**: Add an email annotation to your object with the name of the object's owner.
 
 **Template**: [required-label](generated/templates.md#required-label)
 
@@ -246,9 +246,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on containers not set to runAsNonRoot
+**Description**: Indicates when containers are not set to runAsNonRoot.
 
-**Remediation**: Set runAsUser to a non-zero number, and runAsNonRoot to true, in your pod or container securityContext. See https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ for more details.
+**Remediation**: Set runAsUser to a non-zero number and runAsNonRoot to true in your pod or container securityContext. Refer to https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ for details.
 
 **Template**: [run-as-non-root](generated/templates.md#run-as-non-root-user)
 
@@ -262,9 +262,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on deployments exposing port 22, commonly reserved for SSH access
+**Description**: Indicates when deployments expose port 22, which is commonly reserved for SSH access.
 
-**Remediation**: Ensure that non-SSH services are not using port 22. Ensure that any actual SSH servers have been vetted.
+**Remediation**: Ensure that non-SSH services are not using port 22. Confirm that any actual SSH servers have been vetted.
 
 **Template**: [ports](generated/templates.md#ports)
 
@@ -278,9 +278,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on containers without CPU requests and limits set
+**Description**: Indicates when containers do not have CPU requests and limits set.
 
-**Remediation**: Set your container's CPU requests and limits depending on its requirements. See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits for more details.
+**Remediation**: Set CPU requests and limits for your container based on its requirements. Refer to https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits for details.
 
 **Template**: [cpu-requirements](generated/templates.md#cpu-requirements)
 
@@ -294,9 +294,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: Yes
 
-**Description**: Alert on containers without memory requests and limits set
+**Description**: Indicates when containers do not have memory requests and limits set.
 
-**Remediation**: Set your container's memory requests and limits depending on its requirements. See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits for more details.
+**Remediation**: Set memory requests and limits for your container based on its requirements. Refer to https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits for details.
 
 **Template**: [memory-requirements](generated/templates.md#memory-requirements)
 
@@ -310,9 +310,9 @@ KubeLinter includes the following built-in checks:
 
 **Enabled by default**: No
 
-**Description**: Alert on containers that mount a host path as writable
+**Description**: Indicates when containers mount a host path as writable.
 
-**Remediation**: If you need to access files on the host, mount them as readOnly.
+**Remediation**: Set containers to mount host paths as readOnly, if you need to access files on the host.
 
 **Template**: [writable-host-mount](generated/templates.md#writable-host-mounts)
 

pkg/builtinchecks/yamls/dangling-service.yaml

@@ -1,6 +1,6 @@
 name: "dangling-service"
-description: "Alert on services that don't have any matching deployments"
-remediation: "Make sure your service's selector correctly matches the labels on one of your deployments."
+description: "Indicates when services do not have any associated deployments."
+remediation: "Confirm that your service's selector correctly matches the labels on one of your deployments."
 scope:
   objectKinds:
     - Service

pkg/builtinchecks/yamls/default-service-account.yaml

@@ -1,8 +1,8 @@
 name: "default-service-account"
-description: "Alert on pods that use the default service account"
+description: "Indicates when pods use the default service account."
 remediation: >-
   Create a dedicated service account for your pod.
-  See https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ for more details.
+  Refer to https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ for details.
 scope:
   objectKinds:
     - DeploymentLike

pkg/builtinchecks/yamls/deprecated-service-account.yaml

@@ -1,6 +1,6 @@
 name: "deprecated-service-account-field"
-description: "Alert on deployments that use the deprecated serviceAccount field"
-remediation: "Use the serviceAccountName field instead of the serviceAccount field."
+description: "Indicates when deployments use the deprecated serviceAccount field."
+remediation: "Use the serviceAccountName field instead."
 scope:
   objectKinds:
     - DeploymentLike

pkg/builtinchecks/yamls/drop-net-raw-capability.yaml

@@ -1,8 +1,8 @@
 name: "drop-net-raw-capability"
-description: "Alert on containers not dropping NET_RAW capability"
+description: "Indicates when containers do not drop NET_RAW capability"
 remediation: >-
-  NET_RAW grants an application within the container the ability to craft raw packets, use raw sockets, and it also
-  allows an application to bind to any address. Please specify to drop this capability in the containers under
+  NET_RAW makes it so that an application within the container is able to craft raw packets,
+  use raw sockets, and bind to any address. Remove this capability in the containers under
   containers security contexts.
 scope:
   objectKinds:

pkg/builtinchecks/yamls/env-var-secret.yaml

@@ -1,8 +1,8 @@
 name: "env-var-secret"
-description: "Alert on objects using a secret in an environment variable"
+description: "Indicates when objects use a secret in an environment variable."
 remediation: >-
-  Don't use raw secrets in an environment variable. Instead, either mount the secret as a file or use a secretKeyRef.
-  See https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets for more details.
+  Do not use raw secrets in environment variables. Instead, either mount the secret as a file or use a secretKeyRef.
+  Refer to https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets for details.
 scope:
   objectKinds:
     - DeploymentLike

pkg/builtinchecks/yamls/mismatching-selector.yaml

@@ -1,6 +1,6 @@
 name: "mismatching-selector"
-description: "Alert on deployments where the selector doesn't match the pod template labels"
-remediation: "Make sure your deployment's selector correctly matches the labels in its pod template."
+description: "Indicates when deployment selectors fail to match the pod template labels."
+remediation: "Confirm that your deployment selector correctly matches the labels in its pod template."
 scope:
   objectKinds:
     - DeploymentLike

pkg/builtinchecks/yamls/no-anti-affinity.yaml

@@ -1,10 +1,10 @@
 name: "no-anti-affinity"
-description: "Alert on deployments with multiple replicas that don't specify inter pod anti-affinity to ensure that the orchestrator attempts to schedule replicas on different nodes"
+description: "Indicates when deployments with multiple replicas fail to specify inter-pod anti-affinity, to ensure that the orchestrator attempts to schedule replicas on different nodes."
 remediation: >-
-  Specify anti-affinity in your pod spec to ensure that the orchestrator attempts to schedule replicas on different nodes.
-  You can do this by using podAntiAffinity, specifying a labelSelector that matches pods of this deployment,
-  and setting the topologyKey to kubernetes.io/hostname.
-  See https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity for more details.
+  Specify anti-affinity in your pod specification to ensure that the orchestrator attempts to schedule replicas on different nodes.
+  Using podAntiAffinity, specify a labelSelector that matches pods for the deployment,
+  and set the topologyKey to kubernetes.io/hostname.
+  Refer to https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity for details.
 scope:
   objectKinds:
     - DeploymentLike

pkg/builtinchecks/yamls/no-extensions-v1beta.yaml

@@ -1,8 +1,8 @@
 name: "no-extensions-v1beta"
-description: "Alert on objects using deprecated API versions under extensions v1beta"
+description: "Indicates when objects use deprecated API versions under extensions/v1beta."
 remediation: >-
-  Migrate to using the apps/v1 API versions for these objects.
-  See https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/ for more details.
+  Migrate using the apps/v1 API versions for the objects.
+  Refer to https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/ for details.
 scope:
   objectKinds:
     - Any

pkg/builtinchecks/yamls/no-liveness-probe.yaml

@@ -1,8 +1,8 @@
 name: "no-liveness-probe"
-description: "Alert on containers which don't specify a liveness probe"
+description: "Indicates when containers fail to specify a liveness probe."
 remediation: >-
   Specify a liveness probe in your container.
-  See https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ for more details.
+  Refer to https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ for details.
 scope:
   objectKinds:
     - DeploymentLike

pkg/builtinchecks/yamls/no-readiness-probe.yaml

@@ -1,8 +1,8 @@
 name: "no-readiness-probe"
-description: "Alert on containers which don't specify a readiness probe"
+description: "Indicates when containers fail to specify a readiness probe."
 remediation: >-
   Specify a readiness probe in your container.
-  See https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ for more details.
+  Refer to https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ for details.
 scope:
   objectKinds:
     - DeploymentLike

pkg/builtinchecks/yamls/non-existent-service-account.yaml

@@ -1,6 +1,6 @@
 name: "non-existent-service-account"
-description: "Alert on pods referencing a service account that isn't found"
-remediation: "Make sure to create the service account, or to refer to an existing service account."
+description: "Indicates when pods reference a service account that is not found."
+remediation: "Create the missing service account, or refer to an existing service account."
 scope:
   objectKinds:
     - DeploymentLike