Updates to repo and rule documentation (#26)

.markdownlint.json

@@ -0,0 +1,67 @@
+{
+    "default": true,
+    "header-increment": true,
+    "first-header-h1": {
+        "level": 1
+    },
+    "header-style": {
+        "style": "atx"
+    },
+    "ul-style": {
+        "style": "dash"
+    },
+    "list-indent": true,
+    "ul-start-left": true,
+    "ul-indent": {
+        "indent": 2
+    },
+    "no-trailing-spaces": true,
+    "no-hard-tabs": true,
+    "no-reversed-links": true,
+    "no-multiple-blanks": true,
+    "line-length": {
+        "line_length": 100,
+        "code_blocks": false,
+        "tables": false,
+        "headers": true
+    },
+    "commands-show-output": true,
+    "no-missing-space-atx": true,
+    "no-multiple-space-atx": true,
+    "no-missing-space-closed-atx": true,
+    "no-multiple-space-closed-atx": true,
+    "blanks-around-headers": true,
+    "header-start-left": true,
+    "no-duplicate-header": true,
+    "single-h1": true,
+    "no-trailing-punctuation": {
+        "punctuation": ".,;:!"
+    },
+    "no-multiple-space-blockquote": true,
+    "no-blanks-blockquote": true,
+    "ol-prefix": {
+        "style": "one_or_ordered"
+    },
+    "list-marker-space": true,
+    "blanks-around-fences": true,
+    "blanks-around-lists": true,
+    "no-bare-urls": true,
+    "hr-style": {
+        "style": "---"
+    },
+    "no-emphasis-as-header": true,
+    "no-space-in-emphasis": true,
+    "no-space-in-code": true,
+    "no-space-in-links": true,
+    "fenced-code-language": false,
+    "first-line-h1": false,
+    "no-empty-links": true,
+    "proper-names": {
+        "names": [
+            "PowerShell",
+            "JavaScript"
+        ],
+        "code_blocks": false
+    },
+    "no-alt-text": true
+}

.vscode/settings.json

@@ -18,7 +18,8 @@
         "**/.azure-pipelines/*.yaml": "azure-pipelines"
     },
     "cSpell.words": [
-        "Kubernetes"
+        "Kubernetes",
+        "setuid"
     ],
     "cSpell.enabledLanguageIds": [
         "csharp",

README.md

@@ -10,11 +10,11 @@ This project is to be considered a **proof-of-concept** and **not a supported pr
 
 For issues with rules and documentation please check our GitHub [issues](https://github.com/BernieWhite/PSRule.Rules.Kubernetes/issues) page. If you do not see your problem captured, please file a new issue and follow the provided template.
 
-If you have any problems with the [PSRule][project] engine, please check the project GitHub [issues](https://github.com/BernieWhite/PSRule/issues) page instead.
+If you have any problems with the [PSRule][project] engine, please check the project GitHub [issues](https://github.com/Microsoft/PSRule/issues) page instead.
 
 ## Getting the modules
 
-This project requires the PowerShell module PSRule.
+This project requires the `PSRule` PowerShell module.
 
 You can download and install these modules from the PowerShell Gallery.
 
@@ -24,25 +24,123 @@ PSRule.Rules.Kubernetes | Validate Kubernetes resources | [latest][module] / [in
 
 ## Getting started
 
+PSRule for Kubernetes provides two methods for analyzing Kubernetes resources:
+
+- _Pre-flight_ - Before resources are deployed from a YAML manifest file.
+- _In-flight_ - After resources are deployed to a Kubernetes cluster.
+
 ### Offline with a manifest
 
-Kubernetes resources can be evaluated within a YAML manifest file.
+Kubernetes resources can be validated within a YAML manifest file.
+To validate Kubernetes resources use the `Invoke-PSRule` cmdlet. PSRule natively supports reading objects from YAML files using the `-InputPath` parameter.
+The `-InputPath` parameter can be abbreviated to `-f`.
+
+For example:
 
 ```powershell
-Invoke-PSRule -Module PSRule.Rules.Kubernetes -InputPath .\service.yaml;
+Invoke-PSRule -f service.yaml -Module PSRule.Rules.Kubernetes;
+```
+
+The input path can be also be a URL to a YAML file. For example:
+
+```powershell
+$sourceUrl = 'https://raw.githubusercontent.com/Azure-Samples/azure-voting-app-redis/master/azure-vote-all-in-one-redis.yaml';
+Invoke-PSRule -f $sourceUrl -Module PSRule.Rules.Kubernetes;
+```
+
+The output of this example is:
+
+```text
+   TargetName: azure-vote-back
+
+RuleName                            Outcome    Recommendation
+--------                            -------    --------------
+Kubernetes.API.Removal              Fail       Consider updating resource deployments to use newer API endpoints prior…
+Kubernetes.Metadata                 Fail       Consider applying recommended labels defined by Kubernetes.…
+Kubernetes.Pod.PrivilegeEscalation  Fail       Containers should deny privilege escalation.
+Kubernetes.Pod.Latest               Fail       Deployments or pods should identify a specific tag to use for container…
+Kubernetes.Pod.Resources            Fail       Resource requirements are set for each container.
+Kubernetes.Pod.Secrets              Pass       Use Kubernetes secrets to store information such as passwords or connec…
+Kubernetes.Pod.Health               Fail       Containers should use liveness and readiness probes.
+Kubernetes.Pod.Replicas             Fail       Consider increasing replicas to two or more to provide high availabilit…
+Kubernetes.AKS.PublicLB             Pass       Consider creating services with an internal load balancer instead of a …
+Kubernetes.Metadata                 Fail       Consider applying recommended labels defined by Kubernetes.…
+
+   TargetName: azure-vote-front
+
+RuleName                            Outcome    Recommendation
+--------                            -------    --------------
+Kubernetes.API.Removal              Fail       Consider updating resource deployments to use newer API endpoints prior…
+Kubernetes.Metadata                 Fail       Consider applying recommended labels defined by Kubernetes.…
+Kubernetes.Pod.PrivilegeEscalation  Fail       Containers should deny privilege escalation.
+Kubernetes.Pod.Latest               Pass       Deployments or pods should identify a specific tag to use for container…
+Kubernetes.Pod.Resources            Fail       Resource requirements are set for each container.
+Kubernetes.Pod.Secrets              Pass       Use Kubernetes secrets to store information such as passwords or connec…
+Kubernetes.Pod.Health               Fail       Containers should use liveness and readiness probes.
+Kubernetes.Pod.Replicas             Fail       Consider increasing replicas to two or more to provide high availabilit…
+Kubernetes.AKS.PublicLB             Fail       Consider creating services with an internal load balancer instead of a …
+Kubernetes.Metadata                 Fail       Consider applying recommended labels defined by Kubernetes.…
 ```
 
 ### Online with kubectl
 
+Kubernetes resources can be validated directly from a cluster using the output from `kubectl`.
+To validate resources using `kubectl`, return the output as YAML with the `-o yaml` parameter.
+
+For example:
+
 ```powershell
-Invoke-PSRule -Module PSRule.Rules.Kubernetes -InputObject (kubectl get services -o yaml | Out-String) -Format Yaml -ObjectPath items;
+kubectl get services -o yaml | Out-String | Invoke-PSRule -Format Yaml -ObjectPath items -Module PSRule.Rules.Kubernetes;
+```
+
+In the example above:
+
+- `Out-String` - is used to concatenate the output into a single string object.
+- `-Format Yaml` - indicates that the input is YAML.
+- `-ObjectPath items` - indicates that the input nests objects to evaluate under the `items` property.
+
+### Additional options
+
+To filter results to only failed rules, use `Invoke-PSRule -Outcome Fail`.
+Passed, failed and error results are shown by default.
+
+For example:
+
+```powershell
+# Only show failed results
+Invoke-PSRule -f $sourceUrl -Module 'PSRule.Rules.Kubernetes' -Outcome Fail;
+```
+
+A summary of results can be displayed by using `Invoke-PSRule -As Summary`.
+
+For example:
+
+```powershell
+# Display as summary results
+Invoke-PSRule -f $sourceUrl -Module 'PSRule.Rules.Kubernetes' -As Summary;
+```
+
+The output of this example is:
+
+```text
+RuleName                            Pass  Fail  Outcome
+--------                            ----  ----  -------
+Kubernetes.AKS.PublicLB             1     1     Fail
+Kubernetes.API.Removal              0     2     Fail
+Kubernetes.Metadata                 0     4     Fail
+Kubernetes.Pod.PrivilegeEscalation  0     2     Fail
+Kubernetes.Pod.Latest               1     1     Fail
+Kubernetes.Pod.Resources            0     2     Fail
+Kubernetes.Pod.Secrets              2     0     Pass
+Kubernetes.Pod.Health               0     2     Fail
+Kubernetes.Pod.Replicas             0     2     Fail
 ```
 
 ## Rule reference
 
-The following rules are included in the `PSRule.Rules.Kubernetes` module:
+For a list of rules included in the `PSRule.Rules.Kubernetes` module see:
 
-- [PSRule.Rules.Kubernetes](docs/rules/en-US/module.md)
+- [Module rule reference](docs/rules/en-US/module.md)
 
 ## Changes and versioning
 
@@ -61,4 +159,4 @@ This project is [licensed under the MIT License](LICENSE).
 [install]: docs/scenarios/install-instructions.md
 [ci-badge]: https://dev.azure.com/bewhite/PSRule.Rules.Kubernetes/_apis/build/status/PSRule.Rules.Kubernetes-CI?branchName=master
 [module]: https://www.powershellgallery.com/packages/PSRule.Rules.Kubernetes
-[project]: https://github.com/BernieWhite/PSRule
+[project]: https://github.com/Microsoft/PSRule

RuleToc.Doc.ps1

@@ -1,21 +1,31 @@
 
 Document 'module' {
-    Title 'Module rules'
+    Title 'Module rule reference'
 
     Import-Module .\out\modules\PSRule.Rules.Kubernetes
-    $rules = Get-PSRule -Module PSRule.Rules.Kubernetes -WarningAction SilentlyContinue
+    $rules = Get-PSRule -Module PSRule.Rules.Kubernetes -WarningAction SilentlyContinue |
+        Add-Member -MemberType ScriptProperty -Name Category -Value { $this.Info.Annotations.category } -PassThru |
+        Sort-Object -Property Category;
 
     Section 'Baselines' {
-        # 'The following baselines are included in `PSRule.Rules.Kubernetes`.'
+        # 'The following baselines are included within `PSRule.Rules.Kubernetes`.'
     }
 
     Section 'Rules' {
-        'The following rules are included in `PSRule.Rules.Kubernetes`.'
+        'The following rules are included within `PSRule.Rules.Kubernetes`.'
 
-        $rules | Table -Property @{ Name = 'RuleName'; Expression = {
+        $categories = $rules | Group-Object -Property Category;
-            "[$($_.RuleName)]($($_.RuleName).md)"
+
-        }}, Description, @{ Name = 'Category'; Expression = {
+        foreach ($category in $categories) {
-            $_.Tag.category
+            Section "$($category.Name)" {
-        }}
+                $category.Group |
+                    Sort-Object -Property RuleName |
+                    Table -Property @{ Name = 'Name'; Expression = {
+                        "[$($_.RuleName)]($($_.RuleName).md)"
+                    }}, Synopsis, @{ Name = 'Severity'; Expression = {
+                        $_.Info.Annotations.severity
+                    }}
+            }
+        }
     }
 }

docs/rules/en-US/Kubernetes.AKS.PublicLB.md

@@ -1,6 +1,6 @@
 ---
 severity: Critical
-category: Service exposure
+category: Security
 online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.AKS.PublicLB.md
 ---
 
@@ -21,3 +21,7 @@ When this annotation is used on a load balanced service, the Azure load balancer
 ## RECOMMENDATION
 
 Consider creating services with an internal load balancer instead of a public load balancer.
+
+## LINKS
+
+- [Use an internal load balancer with Azure Kubernetes Service (AKS)](https://docs.microsoft.com/en-us/azure/aks/internal-lb#create-an-internal-load-balancer)

docs/rules/en-US/Kubernetes.API.Removal.md

@@ -1,6 +1,6 @@
 ---
 severity: Important
-category: Resource APIs
+category: API
 online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.API.Removal.md
 ---
 

docs/rules/en-US/Kubernetes.Metadata.md

@@ -1,6 +1,6 @@
 ---
-severity: Important
+severity: Awareness
-category: Resource management
+category: Management
 online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Metadata.md
 ---
 
@@ -19,4 +19,6 @@ These labels should be used to consistently apply standard metadata.
 
 Consider applying recommended labels defined by Kubernetes.
 
-For more information see [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/).
+## LINKS
+
+- [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/)

docs/rules/en-US/Kubernetes.Pod.Health.md

@@ -1,5 +1,6 @@
 ---
 severity: Important
+category: Reliability
 online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Health.md
 ---
 
@@ -17,7 +18,7 @@ This is accomplished through liveness and readiness probes.
 
 ## RECOMMENDATION
 
-Containers should use liveness and readiness probes.
+Consider configuring liveness and readiness probes for pod containers.
 
 ## LINKS
 

docs/rules/en-US/Kubernetes.Pod.Latest.md

@@ -1,6 +1,6 @@
 ---
-severity: Critical
+severity: Important
-category: Pod security
+category: Security
 online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Latest.md
 ---
 
@@ -19,6 +19,6 @@ Containers should use specific tags instead of latest.
 Deployments or pods should identify a specific tag to use for container images instead of latest.
 When latest is used it may be hard to determine which version of the image is running.
 
-When using variable tags such as v1.0 (which may refer to v1.0.0 or v1.0.1) consider using imagePullPolicy: Always to ensure that the an out-of-date cached image is not used.
+When using variable tags such as v1.0 (which may refer to v1.0.0 or v1.0.1) consider using `imagePullPolicy: Always` to ensure that the an out-of-date cached image is not used.
 
-The latest tag automatically uses imagePullPolicy: Always instead of the default imagePullPolicy: IfNotPresent.
+The latest tag automatically uses `imagePullPolicy: Always` instead of the default `imagePullPolicy: IfNotPresent`.

docs/rules/en-US/Kubernetes.Pod.PrivilegeEscalation.md

@@ -1,6 +1,6 @@
 ---
 severity: Critical
-category: Pod security
+category: Security
 online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.PriviledgeEscalation.md
 ---
 
@@ -12,8 +12,16 @@ Containers should deny privilege escalation.
 
 ## DESCRIPTION
 
-Containers should deny privilege escalation.
+In the default configuration, container processes are permitted to change the effective user ID through the _setuid_ binary.
+Changing the effective user ID could allow a malicious or vulnerable process to gain a higher level of permission then intended.
+To prevent this, explicitly set the `securityContext.allowPrivilegeEscalation` option to `false` on pod containers.
 
 ## RECOMMENDATION
 
-Containers should deny privilege escalation.
+Consider explicitly setting the `securityContext.allowPrivilegeEscalation` option to `false` on pod containers.
+
+## LINKS
+
+- [Secure container access to resources](https://docs.microsoft.com/en-us/azure/aks/operator-best-practices-cluster-security#secure-container-access-to-resources)
+- [Set the security context for a Container](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container)
+- [Privilege Escalation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#privilege-escalation)

docs/rules/en-US/Kubernetes.Pod.Replicas.md

@@ -1,5 +1,6 @@
 ---
 severity: Important
+category: Reliability
 online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Replicas.md
 ---
 

docs/rules/en-US/Kubernetes.Pod.Resources.md

@@ -1,19 +1,32 @@
 ---
 severity: Important
-category: Resource management
+category: Performance
 online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Resources.md
 ---
 
-# Set requirements for resources
+# Set compute resource requirements
 
 ## SYNOPSIS
 
-Resource requirements are set for each container.
+Set CPU and memory requirements for each container.
 
 ## DESCRIPTION
 
-Resource requirements are set for each container.
+The default scheduler uses container compute resource configuration to select a node for scheduling the pod.
+If compute resources values are not provided, Kubernetes can't take these into account when making scheduling decisions.
+
+Compute resources is not the only factor to determine pod placement.
+However, if the scheduler places a pod on a host with insufficient resources, pod performance may be impacted.
+
+If the Kubernetes cluster uses resource quotas, pods that don't specify compute resources may be rejected.
+
+Compute resources for a container are set within the pod specification by defining `requests` and `limits`.
 
 ## RECOMMENDATION
 
-Resource requirements are set for each container.
+Consider configuring CPU and memory resource requirements for each container.
+
+## LINKS
+
+- [Define pod resource requests and limits](https://docs.microsoft.com/en-us/azure/aks/developer-best-practices-resource-management#define-pod-resource-requests-and-limits)
+- [Managing Compute Resources for Containers](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-types)

docs/rules/en-US/Kubernetes.Pod.Secrets.md

@@ -1,6 +1,6 @@
 ---
 severity: Critical
-category: Pod security
+category: Security
 online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Secrets.md
 ---
 

docs/rules/en-US/module.md

@@ -1,17 +1,39 @@
-# Module rules
+# Module rule reference
 
 ## Rules
 
-The following rules are included in `PSRule.Rules.Kubernetes`.
+The following rules are included within `PSRule.Rules.Kubernetes`.
 
-RuleName | Description | Category
+### API
--------- | ----------- | --------
+
-[Kubernetes.AKS.PublicLB](Kubernetes.AKS.PublicLB.md) | Use internal Azure load balancers. | Pod security
+Name | Synopsis | Severity
-[Kubernetes.API.Removal](Kubernetes.API.Removal.md) | Avoid using legacy API endpoints. | API
+---- | -------- | --------
-[Kubernetes.Metadata](Kubernetes.Metadata.md) | Use Kubernetes common labels. | Resource management
+[Kubernetes.API.Removal](Kubernetes.API.Removal.md) | Avoid using legacy API endpoints. | Important
-[Kubernetes.Pod.PrivilegeEscalation](Kubernetes.Pod.PrivilegeEscalation.md) | Containers should deny privilege escalation. | Pod security
+
-[Kubernetes.Pod.Latest](Kubernetes.Pod.Latest.md) | Containers should use specific tags instead of latest. | Pod security
+### Management
-[Kubernetes.Pod.Resources](Kubernetes.Pod.Resources.md) | Resource requirements are set for each container. | Resource management
+
-[Kubernetes.Pod.Secrets](Kubernetes.Pod.Secrets.md) | Sensitive environment variables should be referenced as a secret. | Pod security
+Name | Synopsis | Severity
-[Kubernetes.Pod.Health](Kubernetes.Pod.Health.md) | Containers should use liveness and readiness probes. | Reliability
+---- | -------- | --------
-[Kubernetes.Pod.Replicas](Kubernetes.Pod.Replicas.md) | Use two or more replicas. | Reliability
+[Kubernetes.Metadata](Kubernetes.Metadata.md) | Use Kubernetes common labels. | Awareness
+
+### Performance
+
+Name | Synopsis | Severity
+---- | -------- | --------
+[Kubernetes.Pod.Resources](Kubernetes.Pod.Resources.md) | Set CPU and memory requirements for each container. | Important
+
+### Reliability
+
+Name | Synopsis | Severity
+---- | -------- | --------
+[Kubernetes.Pod.Health](Kubernetes.Pod.Health.md) | Containers should use liveness and readiness probes. | Important
+[Kubernetes.Pod.Replicas](Kubernetes.Pod.Replicas.md) | Use two or more replicas. | Important
+
+### Security
+
+Name | Synopsis | Severity
+---- | -------- | --------
+[Kubernetes.AKS.PublicLB](Kubernetes.AKS.PublicLB.md) | Use internal Azure load balancers. | Critical
+[Kubernetes.Pod.Latest](Kubernetes.Pod.Latest.md) | Containers should use specific tags instead of latest. | Important
+[Kubernetes.Pod.PrivilegeEscalation](Kubernetes.Pod.PrivilegeEscalation.md) | Containers should deny privilege escalation. | Critical
+[Kubernetes.Pod.Secrets](Kubernetes.Pod.Secrets.md) | Sensitive environment variables should be referenced as a secret. | Critical

docs/scenarios/install-instructions.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - Windows PowerShell 5.1 with .NET Framework 4.7.2+ or
-- PowerShell Core 6.0 or greater on Windows, macOS and Linux
+- PowerShell Core 6.2 or greater on Windows, MacOS and Linux
 
 For a list of platforms that PowerShell Core is supported on [see](https://github.com/PowerShell/PowerShell#get-powershell).
 
@@ -38,7 +38,8 @@ Save-Module -Name 'PSRule', 'PSRule.Rules.Kubernetes' -Path '.\modules';
 
 > For pre-release versions the `-AllowPrerelease` switch must be added when calling `Install-Module` or `Save-Module`.
 >
-> To install pre-release module versions, upgrading to the latest version of _PowerShellGet_ may be required. To do this use:
+> To install pre-release module versions, upgrading to the latest version of _PowerShellGet_ may be required.
+To do this use:
 >
 > `Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force`