Skip to content

Commit 1021649

Browse files
BernieWhiteBernieWhite
authored
Updates to repo and rule documentation (#26)
1 parent 7fc7048 commit 1021649

15 files changed

Lines changed: 281 additions & 53 deletions

‎.markdownlint.json‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
{
2+
"default": true,
3+
"header-increment": true,
4+
"first-header-h1": {
5+
"level": 1
6+
},
7+
"header-style": {
8+
"style": "atx"
9+
},
10+
"ul-style": {
11+
"style": "dash"
12+
},
13+
"list-indent": true,
14+
"ul-start-left": true,
15+
"ul-indent": {
16+
"indent": 2
17+
},
18+
"no-trailing-spaces": true,
19+
"no-hard-tabs": true,
20+
"no-reversed-links": true,
21+
"no-multiple-blanks": true,
22+
"line-length": {
23+
"line_length": 100,
24+
"code_blocks": false,
25+
"tables": false,
26+
"headers": true
27+
},
28+
"commands-show-output": true,
29+
"no-missing-space-atx": true,
30+
"no-multiple-space-atx": true,
31+
"no-missing-space-closed-atx": true,
32+
"no-multiple-space-closed-atx": true,
33+
"blanks-around-headers": true,
34+
"header-start-left": true,
35+
"no-duplicate-header": true,
36+
"single-h1": true,
37+
"no-trailing-punctuation": {
38+
"punctuation": ".,;:!"
39+
},
40+
"no-multiple-space-blockquote": true,
41+
"no-blanks-blockquote": true,
42+
"ol-prefix": {
43+
"style": "one_or_ordered"
44+
},
45+
"list-marker-space": true,
46+
"blanks-around-fences": true,
47+
"blanks-around-lists": true,
48+
"no-bare-urls": true,
49+
"hr-style": {
50+
"style": "---"
51+
},
52+
"no-emphasis-as-header": true,
53+
"no-space-in-emphasis": true,
54+
"no-space-in-code": true,
55+
"no-space-in-links": true,
56+
"fenced-code-language": false,
57+
"first-line-h1": false,
58+
"no-empty-links": true,
59+
"proper-names": {
60+
"names": [
61+
"PowerShell",
62+
"JavaScript"
63+
],
64+
"code_blocks": false
65+
},
66+
"no-alt-text": true
67+
}

‎.vscode/settings.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@
1818
"**/.azure-pipelines/*.yaml": "azure-pipelines"
1919
},
2020
"cSpell.words": [
21-
"Kubernetes"
21+
"Kubernetes",
22+
"setuid"
2223
],
2324
"cSpell.enabledLanguageIds": [
2425
"csharp",

‎README.md‎

Lines changed: 106 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,11 @@ This project is to be considered a **proof-of-concept** and **not a supported pr
1010

1111
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.
1212

13-
If you have any problems with the [PSRule][project] engine, please check the project GitHub [issues](https://github.com/BernieWhite/PSRule/issues) page instead.
13+
If you have any problems with the [PSRule][project] engine, please check the project GitHub [issues](https://github.com/Microsoft/PSRule/issues) page instead.
1414

1515
## Getting the modules
1616

17-
This project requires the PowerShell module PSRule.
17+
This project requires the `PSRule` PowerShell module.
1818

1919
You can download and install these modules from the PowerShell Gallery.
2020

@@ -24,25 +24,123 @@ PSRule.Rules.Kubernetes | Validate Kubernetes resources | [latest][module] / [in
2424

2525
## Getting started
2626

27+
PSRule for Kubernetes provides two methods for analyzing Kubernetes resources:
28+
29+
- _Pre-flight_ - Before resources are deployed from a YAML manifest file.
30+
- _In-flight_ - After resources are deployed to a Kubernetes cluster.
31+
2732
### Offline with a manifest
2833

29-
Kubernetes resources can be evaluated within a YAML manifest file.
34+
Kubernetes resources can be validated within a YAML manifest file.
35+
To validate Kubernetes resources use the `Invoke-PSRule` cmdlet. PSRule natively supports reading objects from YAML files using the `-InputPath` parameter.
36+
The `-InputPath` parameter can be abbreviated to `-f`.
37+
38+
For example:
39+
40+
```powershell
41+
Invoke-PSRule -f service.yaml -Module PSRule.Rules.Kubernetes;
42+
```
43+
44+
The input path can be also be a URL to a YAML file. For example:
3045

3146
```powershell
32-
Invoke-PSRule -Module PSRule.Rules.Kubernetes -InputPath .\service.yaml;
47+
$sourceUrl = 'https://raw.githubusercontent.com/Azure-Samples/azure-voting-app-redis/master/azure-vote-all-in-one-redis.yaml';
48+
Invoke-PSRule -f $sourceUrl -Module PSRule.Rules.Kubernetes;
49+
```
50+
51+
The output of this example is:
52+
53+
```text
54+
TargetName: azure-vote-back
55+
56+
RuleName Outcome Recommendation
57+
-------- ------- --------------
58+
Kubernetes.API.Removal Fail Consider updating resource deployments to use newer API endpoints prior…
59+
Kubernetes.Metadata Fail Consider applying recommended labels defined by Kubernetes.…
60+
Kubernetes.Pod.PrivilegeEscalation Fail Containers should deny privilege escalation.
61+
Kubernetes.Pod.Latest Fail Deployments or pods should identify a specific tag to use for container…
62+
Kubernetes.Pod.Resources Fail Resource requirements are set for each container.
63+
Kubernetes.Pod.Secrets Pass Use Kubernetes secrets to store information such as passwords or connec…
64+
Kubernetes.Pod.Health Fail Containers should use liveness and readiness probes.
65+
Kubernetes.Pod.Replicas Fail Consider increasing replicas to two or more to provide high availabilit…
66+
Kubernetes.AKS.PublicLB Pass Consider creating services with an internal load balancer instead of a …
67+
Kubernetes.Metadata Fail Consider applying recommended labels defined by Kubernetes.…
68+
69+
TargetName: azure-vote-front
70+
71+
RuleName Outcome Recommendation
72+
-------- ------- --------------
73+
Kubernetes.API.Removal Fail Consider updating resource deployments to use newer API endpoints prior…
74+
Kubernetes.Metadata Fail Consider applying recommended labels defined by Kubernetes.…
75+
Kubernetes.Pod.PrivilegeEscalation Fail Containers should deny privilege escalation.
76+
Kubernetes.Pod.Latest Pass Deployments or pods should identify a specific tag to use for container…
77+
Kubernetes.Pod.Resources Fail Resource requirements are set for each container.
78+
Kubernetes.Pod.Secrets Pass Use Kubernetes secrets to store information such as passwords or connec…
79+
Kubernetes.Pod.Health Fail Containers should use liveness and readiness probes.
80+
Kubernetes.Pod.Replicas Fail Consider increasing replicas to two or more to provide high availabilit…
81+
Kubernetes.AKS.PublicLB Fail Consider creating services with an internal load balancer instead of a …
82+
Kubernetes.Metadata Fail Consider applying recommended labels defined by Kubernetes.…
3383
```
3484

3585
### Online with kubectl
3686

87+
Kubernetes resources can be validated directly from a cluster using the output from `kubectl`.
88+
To validate resources using `kubectl`, return the output as YAML with the `-o yaml` parameter.
89+
90+
For example:
91+
92+
```powershell
93+
kubectl get services -o yaml | Out-String | Invoke-PSRule -Format Yaml -ObjectPath items -Module PSRule.Rules.Kubernetes;
94+
```
95+
96+
In the example above:
97+
98+
- `Out-String` - is used to concatenate the output into a single string object.
99+
- `-Format Yaml` - indicates that the input is YAML.
100+
- `-ObjectPath items` - indicates that the input nests objects to evaluate under the `items` property.
101+
102+
### Additional options
103+
104+
To filter results to only failed rules, use `Invoke-PSRule -Outcome Fail`.
105+
Passed, failed and error results are shown by default.
106+
107+
For example:
108+
37109
```powershell
38-
Invoke-PSRule -Module PSRule.Rules.Kubernetes -InputObject (kubectl get services -o yaml | Out-String) -Format Yaml -ObjectPath items;
110+
# Only show failed results
111+
Invoke-PSRule -f $sourceUrl -Module 'PSRule.Rules.Kubernetes' -Outcome Fail;
112+
```
113+
114+
A summary of results can be displayed by using `Invoke-PSRule -As Summary`.
115+
116+
For example:
117+
118+
```powershell
119+
# Display as summary results
120+
Invoke-PSRule -f $sourceUrl -Module 'PSRule.Rules.Kubernetes' -As Summary;
121+
```
122+
123+
The output of this example is:
124+
125+
```text
126+
RuleName Pass Fail Outcome
127+
-------- ---- ---- -------
128+
Kubernetes.AKS.PublicLB 1 1 Fail
129+
Kubernetes.API.Removal 0 2 Fail
130+
Kubernetes.Metadata 0 4 Fail
131+
Kubernetes.Pod.PrivilegeEscalation 0 2 Fail
132+
Kubernetes.Pod.Latest 1 1 Fail
133+
Kubernetes.Pod.Resources 0 2 Fail
134+
Kubernetes.Pod.Secrets 2 0 Pass
135+
Kubernetes.Pod.Health 0 2 Fail
136+
Kubernetes.Pod.Replicas 0 2 Fail
39137
```
40138

41139
## Rule reference
42140

43-
The following rules are included in the `PSRule.Rules.Kubernetes` module:
141+
For a list of rules included in the `PSRule.Rules.Kubernetes` module see:
44142

45-
- [PSRule.Rules.Kubernetes](docs/rules/en-US/module.md)
143+
- [Module rule reference](docs/rules/en-US/module.md)
46144

47145
## Changes and versioning
48146

@@ -61,4 +159,4 @@ This project is [licensed under the MIT License](LICENSE).
61159
[install]: docs/scenarios/install-instructions.md
62160
[ci-badge]: https://dev.azure.com/bewhite/PSRule.Rules.Kubernetes/_apis/build/status/PSRule.Rules.Kubernetes-CI?branchName=master
63161
[module]: https://www.powershellgallery.com/packages/PSRule.Rules.Kubernetes
64-
[project]: https://github.com/BernieWhite/PSRule
162+
[project]: https://github.com/Microsoft/PSRule

‎RuleToc.Doc.ps1‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,31 @@
11

22
Document 'module' {
3-
Title 'Module rules'
3+
Title 'Module rule reference'
44

55
Import-Module .\out\modules\PSRule.Rules.Kubernetes
6-
$rules = Get-PSRule -Module PSRule.Rules.Kubernetes -WarningAction SilentlyContinue
6+
$rules = Get-PSRule -Module PSRule.Rules.Kubernetes -WarningAction SilentlyContinue |
7+
Add-Member -MemberType ScriptProperty -Name Category -Value { $this.Info.Annotations.category } -PassThru |
8+
Sort-Object -Property Category;
79

810
Section 'Baselines' {
9-
# 'The following baselines are included in `PSRule.Rules.Kubernetes`.'
11+
# 'The following baselines are included within `PSRule.Rules.Kubernetes`.'
1012
}
1113

1214
Section 'Rules' {
13-
'The following rules are included in `PSRule.Rules.Kubernetes`.'
15+
'The following rules are included within `PSRule.Rules.Kubernetes`.'
1416

15-
$rules | Table -Property @{ Name = 'RuleName'; Expression = {
16-
"[$($_.RuleName)]($($_.RuleName).md)"
17-
}}, Description, @{ Name = 'Category'; Expression = {
18-
$_.Tag.category
19-
}}
17+
$categories = $rules | Group-Object -Property Category;
18+
19+
foreach ($category in $categories) {
20+
Section "$($category.Name)" {
21+
$category.Group |
22+
Sort-Object -Property RuleName |
23+
Table -Property @{ Name = 'Name'; Expression = {
24+
"[$($_.RuleName)]($($_.RuleName).md)"
25+
}}, Synopsis, @{ Name = 'Severity'; Expression = {
26+
$_.Info.Annotations.severity
27+
}}
28+
}
29+
}
2030
}
2131
}

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
severity: Critical
3-
category: Service exposure
3+
category: Security
44
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.AKS.PublicLB.md
55
---
66

@@ -21,3 +21,7 @@ When this annotation is used on a load balanced service, the Azure load balancer
2121
## RECOMMENDATION
2222

2323
Consider creating services with an internal load balancer instead of a public load balancer.
24+
25+
## LINKS
26+
27+
- [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‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
severity: Important
3-
category: Resource APIs
3+
category: API
44
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.API.Removal.md
55
---
66

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

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
severity: Important
3-
category: Resource management
2+
severity: Awareness
3+
category: Management
44
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Metadata.md
55
---
66

@@ -19,4 +19,6 @@ These labels should be used to consistently apply standard metadata.
1919

2020
Consider applying recommended labels defined by Kubernetes.
2121

22-
For more information see [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/).
22+
## LINKS
23+
24+
- [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/)

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
severity: Important
3+
category: Reliability
34
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Health.md
45
---
56

@@ -17,7 +18,7 @@ This is accomplished through liveness and readiness probes.
1718

1819
## RECOMMENDATION
1920

20-
Containers should use liveness and readiness probes.
21+
Consider configuring liveness and readiness probes for pod containers.
2122

2223
## LINKS
2324

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
severity: Critical
3-
category: Pod security
2+
severity: Important
3+
category: Security
44
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Latest.md
55
---
66

@@ -19,6 +19,6 @@ Containers should use specific tags instead of latest.
1919
Deployments or pods should identify a specific tag to use for container images instead of latest.
2020
When latest is used it may be hard to determine which version of the image is running.
2121

22-
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.
22+
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.
2323

24-
The latest tag automatically uses imagePullPolicy: Always instead of the default imagePullPolicy: IfNotPresent.
24+
The latest tag automatically uses `imagePullPolicy: Always` instead of the default `imagePullPolicy: IfNotPresent`.

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

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
severity: Critical
3-
category: Pod security
3+
category: Security
44
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.PriviledgeEscalation.md
55
---
66

@@ -12,8 +12,16 @@ Containers should deny privilege escalation.
1212

1313
## DESCRIPTION
1414

15-
Containers should deny privilege escalation.
15+
In the default configuration, container processes are permitted to change the effective user ID through the _setuid_ binary.
16+
Changing the effective user ID could allow a malicious or vulnerable process to gain a higher level of permission then intended.
17+
To prevent this, explicitly set the `securityContext.allowPrivilegeEscalation` option to `false` on pod containers.
1618

1719
## RECOMMENDATION
1820

19-
Containers should deny privilege escalation.
21+
Consider explicitly setting the `securityContext.allowPrivilegeEscalation` option to `false` on pod containers.
22+
23+
## LINKS
24+
25+
- [Secure container access to resources](https://docs.microsoft.com/en-us/azure/aks/operator-best-practices-cluster-security#secure-container-access-to-resources)
26+
- [Set the security context for a Container](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container)
27+
- [Privilege Escalation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#privilege-escalation)

0 commit comments

Comments
 (0)