Merge pull request aws-samples#3 from aws-samples/update-docs

Update docs

README.md

@@ -16,7 +16,7 @@ pip install hardeneks
 hardeneks
 ```
 
-![alt text](https://github.com/dorukozturk/hardeneks/blob/e9168a857a57a13cee8fae870e33d585d8bd3be1/docs/hardeneks.png)
+![alt text](https://github.com/dorukozturk/hardeneks/blob/e9168a857a57a13cee8fae870e33d585d8bd3be1/docs/hardeneks.gif)
 
 **Usage**:
 
@@ -133,7 +133,78 @@ rules:
         - run_multiple_replicas
         - avoid_running_singleton_pods
 ```
-
+
+**RBAC**:
+
+In order to run hardeneks we need to have some permissions both on AWS side and k8s side.
+
+Minimal IAM role policy:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": "eks:ListClusters",
+            "Resource": "*"
+        },
+        {
+            "Effect": "Allow",
+            "Action": "eks:DescribeCluster",
+            "Resource": "*"
+        },
+        {
+            "Effect": "Allow",
+            "Action": "ecr:DescribeRepositories",
+            "Resource": "*"
+        },
+        {
+            "Effect": "Allow",
+            "Action": "inspector2:BatchGetAccountStatus",
+            "Resource": "*"
+        },
+        {
+            "Effect": "Allow",
+            "Action": "ec2:DescribeFlowLogs",
+            "Resource": "*"
+        },
+        {
+            "Effect": "Allow",
+            "Action": "ec2:DescribeInstances",
+            "Resource": "*"
+        }
+    ]
+}
+```
+
+Minimal ClusterRole:
+
+```yaml
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: hardeneks-runner
+rules:
+- apiGroups: [""]
+  resources: ["namespaces", "resourcequotas", "persistentvolumes", "pods", "services"]
+  verbs: ["list"]
+- apiGroups: ["rbac.authorization.k8s.io"]
+  resources: ["clusterroles", "clusterrolebindings", "roles", "rolebindings"]
+  verbs: ["list"]
+- apiGroups: ["networking.k8s.io"]
+  resources: ["networkpolicies"]
+  verbs: ["list"]
+- apiGroups: ["storage.k8s.io"]
+  resources: ["storageclasses"]
+  verbs: ["list"]
+- apiGroups: ["apps"]
+  resources: ["deployments", "daemonsets", "statefulsets"]
+  verbs: ["list", "get"]
+- apiGroups: ["autoscaling"]
+  resources: ["horizontalpodautoscalers"]
+  verbs: ["list"]
+```
 
 ## For Developers
 

docs/cluster_wide/reliability/applications.html

@@ -45,7 +45,12 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.reliability.applications</
     if &#34;metrics-server&#34; in services:
         return True
     else:
-        print(Panel(&#34;[red]Deploy metrics server.&#34;))
+        print(
+            Panel(
+                &#34;[red]Deploy metrics server.&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/reliability/docs/application/#run-kubernetes-metrics-server&#34;,
+            )
+        )
         console.print()
         return False
 
@@ -61,7 +66,12 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.reliability.applications</
     if &#34;vpa-recommender&#34; in deployments:
         return True
     else:
-        print(Panel(&#34;[red]Deploy vertical pod autoscaler.&#34;))
+        print(
+            Panel(
+                &#34;[red]Deploy vertical pod autoscaler if needed.&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/reliability/docs/application/#vertical-pod-autoscaler-vpa&#34;,
+            )
+        )
         console.print()
         return False</code></pre>
 </details>
@@ -93,7 +103,12 @@ <h2 class="section-title" id="header-functions">Functions</h2>
     if &#34;metrics-server&#34; in services:
         return True
     else:
-        print(Panel(&#34;[red]Deploy metrics server.&#34;))
+        print(
+            Panel(
+                &#34;[red]Deploy metrics server.&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/reliability/docs/application/#run-kubernetes-metrics-server&#34;,
+            )
+        )
         console.print()
         return False</code></pre>
 </details>
@@ -118,7 +133,12 @@ <h2 class="section-title" id="header-functions">Functions</h2>
     if &#34;vpa-recommender&#34; in deployments:
         return True
     else:
-        print(Panel(&#34;[red]Deploy vertical pod autoscaler.&#34;))
+        print(
+            Panel(
+                &#34;[red]Deploy vertical pod autoscaler if needed.&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/reliability/docs/application/#vertical-pod-autoscaler-vpa&#34;,
+            )
+        )
         console.print()
         return False</code></pre>
 </details>

docs/cluster_wide/security/detective_controls.html

@@ -44,7 +44,12 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.detective_control
         &#34;enabled&#34;
     ]
     if not logs:
-        print(Panel(&#34;[red]Enable control plane logs for auditing&#34;))
+        print(
+            Panel(
+                &#34;[red]Enable control plane logs for auditing&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/detective/#enable-audit-logs&#34;,
+            )
+        )
         console.print()
 
     return logs</code></pre>
@@ -73,7 +78,12 @@ <h2 class="section-title" id="header-functions">Functions</h2>
         &#34;enabled&#34;
     ]
     if not logs:
-        print(Panel(&#34;[red]Enable control plane logs for auditing&#34;))
+        print(
+            Panel(
+                &#34;[red]Enable control plane logs for auditing&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/detective/#enable-audit-logs&#34;,
+            )
+        )
         console.print()
 
     return logs</code></pre>

docs/cluster_wide/security/encryption_secrets.html

@@ -45,6 +45,7 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.encryption_secret
         print_storage_class_table(
             offenders,
             &#34;[red]EBS Storage Classes should have encryption parameter&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/data/#encryption-at-rest&#34;,
         )
     return offenders
 
@@ -53,7 +54,8 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.encryption_secret
     offenders = []
 
     for persistent_volume in resources.persistent_volumes:
-        if persistent_volume.spec.csi.driver == &#34;efs.csi.aws.com&#34;:
+        csi = persistent_volume.spec.csi
+        if csi and csi.driver == &#34;efs.csi.aws.com&#34;:
             mount_options = persistent_volume.spec.mount_options
             if not mount_options:
                 offenders.append(persistent_volume)
@@ -65,6 +67,7 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.encryption_secret
         print_persistent_volume_table(
             offenders,
             &#34;[red]EFS Persistent volumes should have tls mount option&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/data/#encryption-at-rest&#34;,
         )
     return offenders
 
@@ -73,14 +76,16 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.encryption_secret
     offenders = []
 
     for persistent_volume in resources.persistent_volumes:
-        if persistent_volume.spec.csi.driver == &#34;efs.csi.aws.com&#34;:
-            if &#34;::&#34; not in persistent_volume.spec.csi.volume_handle:
+        csi = persistent_volume.spec.csi
+        if csi and csi.driver == &#34;efs.csi.aws.com&#34;:
+            if &#34;::&#34; not in csi.volume_handle:
                 offenders.append(persistent_volume)
 
     if offenders:
         print_persistent_volume_table(
             offenders,
             &#34;[red]EFS Persistent volumes should leverage access points&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/data/#use-efs-access-points-to-simplify-access-to-shared-datasets&#34;,
         )
     return offenders</code></pre>
 </details>
@@ -105,14 +110,16 @@ <h2 class="section-title" id="header-functions">Functions</h2>
     offenders = []
 
     for persistent_volume in resources.persistent_volumes:
-        if persistent_volume.spec.csi.driver == &#34;efs.csi.aws.com&#34;:
-            if &#34;::&#34; not in persistent_volume.spec.csi.volume_handle:
+        csi = persistent_volume.spec.csi
+        if csi and csi.driver == &#34;efs.csi.aws.com&#34;:
+            if &#34;::&#34; not in csi.volume_handle:
                 offenders.append(persistent_volume)
 
     if offenders:
         print_persistent_volume_table(
             offenders,
             &#34;[red]EFS Persistent volumes should leverage access points&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/data/#use-efs-access-points-to-simplify-access-to-shared-datasets&#34;,
         )
     return offenders</code></pre>
 </details>
@@ -141,6 +148,7 @@ <h2 class="section-title" id="header-functions">Functions</h2>
         print_storage_class_table(
             offenders,
             &#34;[red]EBS Storage Classes should have encryption parameter&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/data/#encryption-at-rest&#34;,
         )
     return offenders</code></pre>
 </details>
@@ -158,7 +166,8 @@ <h2 class="section-title" id="header-functions">Functions</h2>
     offenders = []
 
     for persistent_volume in resources.persistent_volumes:
-        if persistent_volume.spec.csi.driver == &#34;efs.csi.aws.com&#34;:
+        csi = persistent_volume.spec.csi
+        if csi and csi.driver == &#34;efs.csi.aws.com&#34;:
             mount_options = persistent_volume.spec.mount_options
             if not mount_options:
                 offenders.append(persistent_volume)
@@ -170,6 +179,7 @@ <h2 class="section-title" id="header-functions">Functions</h2>
         print_persistent_volume_table(
             offenders,
             &#34;[red]EFS Persistent volumes should have tls mount option&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/data/#encryption-at-rest&#34;,
         )
     return offenders</code></pre>
 </details>

docs/cluster_wide/security/iam.html

@@ -52,6 +52,7 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.iam</code></h1>
         print_role_table(
             offenders,
             &#34;[red]ClusterRoles should not have &#39;*&#39; in Verbs or Resources&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#employ-least-privileged-access-when-creating-rolebindings-and-clusterrolebindings&#34;,
             &#34;ClusterRole&#34;,
         )
     return offenders
@@ -64,7 +65,12 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.iam</code></h1>
         &#34;endpointPublicAccess&#34;
     ]
     if endpoint_access:
-        print(Panel(&#34;[red]EKS Cluster Endpoint is not Private&#34;))
+        print(
+            Panel(
+                &#34;[red]EKS Cluster Endpoint is not Private&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#make-the-eks-cluster-endpoint-private&#34;,
+            )
+        )
         console.print()
         return False
 
@@ -77,7 +83,12 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.iam</code></h1>
     )
 
     if daemonset.spec.template.spec.service_account_name == &#34;aws-node&#34;:
-        print(Panel(&#34;[red]Update the aws-node daemonset to use IRSA&#34;))
+        print(
+            Panel(
+                &#34;[red]Update the aws-node daemonset to use IRSA&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#update-the-aws-node-daemonset-to-use-irsa&#34;,
+            )
+        )
         console.print()
         return False
 
@@ -112,6 +123,7 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.iam</code></h1>
         print_instance_metadata_table(
             offenders,
             &#34;[red]Restrict access to the instance profile assigned to nodes&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#when-your-application-needs-access-to-imds-use-imdsv2-and-increase-the-hop-limit-on-ec2-instances-to-2&#34;,
         )
     return offenders
 
@@ -132,6 +144,7 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.iam</code></h1>
         print_role_table(
             offenders,
             &#34;[red]Don&#39;t bind clusterroles to anonymous/unauthenticated groups&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#review-and-revoke-unnecessary-anonymous-access&#34;,
             &#34;ClusterRoleBinding&#34;,
         )
 
@@ -182,6 +195,7 @@ <h2 class="section-title" id="header-functions">Functions</h2>
         print_instance_metadata_table(
             offenders,
             &#34;[red]Restrict access to the instance profile assigned to nodes&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#when-your-application-needs-access-to-imds-use-imdsv2-and-increase-the-hop-limit-on-ec2-instances-to-2&#34;,
         )
     return offenders</code></pre>
 </details>
@@ -201,7 +215,12 @@ <h2 class="section-title" id="header-functions">Functions</h2>
     )
 
     if daemonset.spec.template.spec.service_account_name == &#34;aws-node&#34;:
-        print(Panel(&#34;[red]Update the aws-node daemonset to use IRSA&#34;))
+        print(
+            Panel(
+                &#34;[red]Update the aws-node daemonset to use IRSA&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#update-the-aws-node-daemonset-to-use-irsa&#34;,
+            )
+        )
         console.print()
         return False
 
@@ -224,7 +243,12 @@ <h2 class="section-title" id="header-functions">Functions</h2>
         &#34;endpointPublicAccess&#34;
     ]
     if endpoint_access:
-        print(Panel(&#34;[red]EKS Cluster Endpoint is not Private&#34;))
+        print(
+            Panel(
+                &#34;[red]EKS Cluster Endpoint is not Private&#34;,
+                subtitle=&#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#make-the-eks-cluster-endpoint-private&#34;,
+            )
+        )
         console.print()
         return False
 
@@ -256,6 +280,7 @@ <h2 class="section-title" id="header-functions">Functions</h2>
         print_role_table(
             offenders,
             &#34;[red]Don&#39;t bind clusterroles to anonymous/unauthenticated groups&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#review-and-revoke-unnecessary-anonymous-access&#34;,
             &#34;ClusterRoleBinding&#34;,
         )
 
@@ -285,6 +310,7 @@ <h2 class="section-title" id="header-functions">Functions</h2>
         print_role_table(
             offenders,
             &#34;[red]ClusterRoles should not have &#39;*&#39; in Verbs or Resources&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/iam/#employ-least-privileged-access-when-creating-rolebindings-and-clusterrolebindings&#34;,
             &#34;ClusterRole&#34;,
         )
     return offenders</code></pre>

docs/cluster_wide/security/image_security.html

@@ -46,6 +46,7 @@ <h1 class="title">Module <code>hardeneks.cluster_wide.security.image_security</c
             offenders,
             &#34;imageTagMutability&#34;,
             &#34;[red]Make image tags immutable.&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/image/#use-immutable-tags-with-ecr&#34;,
         )
 
     return offenders</code></pre>
@@ -81,6 +82,7 @@ <h2 class="section-title" id="header-functions">Functions</h2>
             offenders,
             &#34;imageTagMutability&#34;,
             &#34;[red]Make image tags immutable.&#34;,
+            &#34;Link: https://aws.github.io/aws-eks-best-practices/security/docs/image/#use-immutable-tags-with-ecr&#34;,
         )
 
     return offenders</code></pre>