From e37c02e8e41e6a792c472c2b4e46f34e3a5028e2 Mon Sep 17 00:00:00 2001 From: Daniel Pacak Date: Wed, 27 Oct 2021 11:25:50 +0200 Subject: [PATCH] docs(tutorial): manage access to security reports (#776) Signed-off-by: Daniel Pacak --- .../manage_access_to_security_reports.md} | 170 +++++++++--------- mkdocs.yml | 2 + 2 files changed, 86 insertions(+), 86 deletions(-) rename docs/{design/managing_access_to_security_reports.md => tutorials/manage_access_to_security_reports.md} (62%) diff --git a/docs/design/managing_access_to_security_reports.md b/docs/tutorials/manage_access_to_security_reports.md similarity index 62% rename from docs/design/managing_access_to_security_reports.md rename to docs/tutorials/manage_access_to_security_reports.md index 977ba08ad..4f54ca483 100644 --- a/docs/design/managing_access_to_security_reports.md +++ b/docs/tutorials/manage_access_to_security_reports.md @@ -1,41 +1,50 @@ -# Managing Access to Security Reports +# Manage Access to Security Reports -## TL;DR; +In Starboard security reports are stored as [CRD] instances (e.g. VulnerabilityReport and ConfigAuditReport objects). -In Starboard security reports are stored as [CRD] instances -(e.g. VulnerabilityReport and ConfigAuditReport objects). +With Kubernetes [RBAC], a cluster administrator can choose the following levels of granularity to manage access to +security reports: -With Kubernetes [RBAC], a cluster administrator can choose the following levels -of granularity to manage access to security reports: +1. Grant **administrative** access to view **any** report in **any** namespace. +2. Grant **coarse-grained** access to view **any** report in a **specified** namespace. +3. Grant **fine-grained** access to view a **specified** report in a **specified** namespace. -1. Grant **administrative** access to view **any** VulnerabilityReport in **any** - namespace. -2. Grant **coarse-grained** access to view **any** VulnerabilityReport in a - **specified** namespace. -3. Grant **fine-grained** access to view a **specified** VulnerabilityReport in - a **specified** namespace. +Even though you can achieve fine-grained access control with Kubernetes RBAC configuration, it is very impractical to do +so with security reports. Mainly because security reports are associated with ephemeral Kubernetes objects such as Pods +and ReplicaSets. -Even though you can achieve **fine-grained** access control with Kubernetes RBAC -configuration, it is very impractical to do so with security reports. Mainly -because VulnerabilityReport instances are associated with **ephemeral** Kubernetes -objects such as Pods and ReplicaSets. +To sum up, we only recommend using administrative and coarse-grained levels to manage access to security reports. -To sum up, we only recommend using **administrative** and **coarse-grained** -levels to manage access to security reports. +Continue reading to see examples of managing access to VulnerabilityReport objects at different levels of granularity. -Continue reading to see examples of managing access to VulnerabilityReport objects -at different levels of granularity. +## Create Namespaces and Deployments -## Overview +Let's consider a multitenant cluster with two `nginx` Deployments in `foo` and `bar` namespaces. There's also the +`redis` Deployment in the `foo` namespace. -Let's consider a multitenant cluster with two `nginx` Deployments in `foo` and -`bar` namespaces. When we scan them Starboard will create VulnerabilityReports -which are named by revision kind (`replicaset`) concatenated with revision name -(`nginx-7967dc8bfd`) and container name (`nginx`). +``` +kubectl create namespace foo +kubectl create deploy nginx --image nginx:1.16 --namespace foo +kubectl create deploy redis --image redis:5 --namespace foo +``` + +``` +kubectl create namespace bar +kubectl create deploy nginx --image nginx:1.16 --namespace bar +``` -> **TIP** For workloads with multiple containers we'll have multiple instances -> of VulnerabilityReports with the same prefix (`replicaset-nginx-7967dc8bfd-`) -> but different suffixes that correspond to container names. +When we scan them Starboard will create VulnerabilityReports which are named by revision kind (`replicaset`) +concatenated with revision name (`nginx-7967dc8bfd`) and container name (`nginx`). + +``` +starboard scan vulnerabilityreports deploy/nginx --namespace foo +starboard scan vulnerabilityreports deploy/redis --namespace foo +starboard scan vulnerabilityreports deploy/nginx --namespace bar +``` + +!!! tip + For workloads with multiple containers we'll have multiple instances of VulnerabilityReports with the same prefix + (`replicaset-nginx-7967dc8bfd-`) but different suffixes that correspond to container names. ```console $ kubectl tree deploy nginx --namespace foo @@ -55,7 +64,7 @@ bar ├─Pod/nginx-f4cc56f6b-9cd45 True bar └─VulnerabilityReport/replicaset-nginx-f4cc56f6b-nginx - 2m12s ``` -There's also the `redis` Deployment in the `foo` namespace. + ```console $ kubectl tree deploy redis --namespace foo @@ -66,19 +75,19 @@ foo ├─Pod/redis-79c5cc7cf8-fz99f True foo └─VulnerabilityReport/replicaset-redis-79c5cc7cf8-redis - 74m ``` -To manage access to VulnerabilityReport instances a cluster administrator will -typically create Role or ClusterRole objects and bind them to subjects (users, -groups, or service accounts) by creating RoleBinding or ClusterRoleBinding +## Choose Access Level + +To manage access to VulnerabilityReport instances a cluster administrator will typically create Role or ClusterRole +objects and bind them to subjects (users, groups, or service accounts) by creating RoleBinding or ClusterRoleBinding objects. -With Kubernetes RBAC there are three different granularity levels at which you can -grant access to VulnerabilityReports: +With Kubernetes RBAC there are three different granularity levels at which you can grant access to VulnerabilityReports: -- [Cluster - a subject can view **any** report in **any** namespace](#grant-access-to-view-any-vulnerabilityreport-in-any-namespace) -- [Namespace - a subject can view **any** report in a **specified** namespace](#grant-access-to-view-any-vulnerabilityreport-in-the-foo-namespace) -- [Security Report - a subject can view a **specified** report in a **specified** namespace](#grant-access-to-view-the-replicaset-nginx-7967dc8bfd-nginx-vulnerabilityreport-in-the-foo-namespace) +1. [Cluster - a subject can view **any** report in **any** namespace](#grant-access-to-view-any-vulnerabilityreport-in-any-namespace) +2. [Namespace - a subject can view **any** report in a **specified** namespace](#grant-access-to-view-any-vulnerabilityreport-in-the-foo-namespace) +3. [Security Report - a subject can view a **specified** report in a **specified** namespace](#grant-access-to-view-the-replicaset-nginx-7967dc8bfd-nginx-vulnerabilityreport-in-the-foo-namespace) -## Grant access to view any VulnerabilityReport in any namespace +## Grant Access to View any VulnerabilityReport in any Namespace ``` kubectl create clusterrole view-vulnerabilityreports \ @@ -92,17 +101,6 @@ kubectl create clusterrolebinding dpacak-can-view-vulnerabilityreports \ --user dpacak ``` -```console -$ kubectl who-can get vulnerabilityreports -A -No subjects found with permissions to get vulns assigned through RoleBindings - -CLUSTERROLEBINDING SUBJECT TYPE SA-NAMESPACE -cluster-admin system:masters Group -dpacak-can-view-vulnerabilityreports dpacak User -system:controller:generic-garbage-collector generic-garbage-collector ServiceAccount kube-system -system:controller:namespace-controller namespace-controller ServiceAccount kube-system -``` - ```console $ kubectl get vulnerabilityreports -A --as dpacak NAMESPACE NAME REPOSITORY TAG SCANNER AGE @@ -117,7 +115,22 @@ orbidden: User "zpacak" cannot list resource "vulnerabilityreports" in API grou p "aquasecurity.github.io" at the cluster scope ``` -## Grant access to view any VulnerabilityReport in the foo namespace +```console +$ kubectl who-can get vulnerabilityreports -A +No subjects found with permissions to get vulns assigned through RoleBindings + +CLUSTERROLEBINDING SUBJECT TYPE SA-NAMESPACE +cluster-admin system:masters Group +dpacak-can-view-vulnerabilityreports dpacak User +system:controller:generic-garbage-collector generic-garbage-collector ServiceAccount kube-system +system:controller:namespace-controller namespace-controller ServiceAccount kube-system +``` + +!!! note + The [who-can] command is a kubectl plugin that shows who has RBAC permissions to perform actions on different + resources in Kubernetes. + +## Grant Access to View any VulnerabilityReport in the foo Namespace ``` kubectl create clusterrole view-vulnerabilityreports \ @@ -145,21 +158,18 @@ orbidden: User "dpacak" cannot list resource "vulnerabilityreports" in API grou p "aquasecurity.github.io" in the namespace "bar" ``` -## Grant access to view the replicaset-nginx-7967dc8bfd-nginx VulnerabilityReport in the foo namespace +## Grant Access to View the replicaset-nginx-7967dc8bfd-nginx VulnerabilityReport in the foo Namespace -Even though you can grant access to a single VulnerabilityReport by specifying -its name when you create Role or ClusterRole objects, in practice it's not -manageable for these reasons: +Even though you can grant access to a single VulnerabilityReport by specifying its name when you create Role or +ClusterRole objects, in practice it's not manageable for these reasons: -* The name of a ReplicaSet (e.g. `nginx-7967dc8bfd`) and hence the name of the - corresponding VulnerabilityReport (e.g. `replicaset-nginx-7967dc8bfd-nginx`) - change over time. This requires that Role or ClusterObject will be updated - respectively. -* We create a VulnerabilityReport for each container of a Kubernetes workload. - Therefore, managing such fine-grained permissions is even more cumbersome. -* Last but not least, the naming convention is an implementation details that's - likely to change when we add support for mutable tags or implement caching of - scan results. +1. The name of a ReplicaSet (e.g. `nginx-7967dc8bfd`) and hence the name of the corresponding VulnerabilityReport (e.g. + `replicaset-nginx-7967dc8bfd-nginx`) change over time. This requires that Role or ClusterObject will be updated + respectively. +2. We create a VulnerabilityReport for each container of a Kubernetes workload. Therefore, managing such fine-grained + permissions is even more cumbersome. +3. Last but not least, the naming convention is an implementation details that's likely to change when we add support + for mutable tags or implement caching of scan results. ``` kubectl create role view-replicaset-nginx-7967dc8bfd-nginx \ @@ -176,17 +186,6 @@ kubectl create rolebinding dpacak-can-view-replicaset-nginx-7967dc8bfd-nginx \ --user dpacak ``` -```console -$ kubectl who-can get vuln/replicaset-nginx-7967dc8bfd-nginx -n foo -ROLEBINDING NAMESPACE SUBJECT TYPE SA-NAMESPACE -dpacak-can-view-replicaset-nginx-7967dc8bfd-nginx foo dpacak User - -CLUSTERROLEBINDING SUBJECT TYPE SA-NAMESPACE -cluster-admin system:masters Group -system:controller:generic-garbage-collector generic-garbage-collector ServiceAccount kube-system -system:controller:namespace-controller namespace-controller ServiceAccount kube-system -``` - ```console $ kubectl get vuln -n foo replicaset-nginx-7967dc8bfd-nginx --as dpacak NAME REPOSITORY TAG SCANNER AGE @@ -201,18 +200,17 @@ licaset-redis-79c5cc7cf8-redis" is forbidden: User "dpacak" cannot get resource foo" ``` -## Appendix A - -``` -kubectl create namespace foo -kubectl create deploy nginx --image nginx:1.16 --namespace foo -kubectl create deploy redis --image redis:5 --namespace foo -``` +```console +$ kubectl who-can get vuln/replicaset-nginx-7967dc8bfd-nginx -n foo +ROLEBINDING NAMESPACE SUBJECT TYPE SA-NAMESPACE +dpacak-can-view-replicaset-nginx-7967dc8bfd-nginx foo dpacak User -``` -kubectl create ns bar -kubectl create deploy nginx --image nginx:1.16 --namespace bar +CLUSTERROLEBINDING SUBJECT TYPE SA-NAMESPACE +cluster-admin system:masters Group +system:controller:generic-garbage-collector generic-garbage-collector ServiceAccount kube-system +system:controller:namespace-controller namespace-controller ServiceAccount kube-system ``` -[CRD]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ -[RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ \ No newline at end of file +[CRD]: ../crds/index.md +[RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/ +[who-can]: https://github.com/aquasecurity/kubectl-who-can diff --git a/mkdocs.yml b/mkdocs.yml index a7659cd26..a70f97e39 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,6 +42,8 @@ nav: - Managed Registries: integrations/managed-registries.md - Octant Plugin: integrations/octant.md - Lens Extension: integrations/lens.md + - Tutorials: + - Manage Access to Security Reports: tutorials/manage_access_to_security_reports.md - Custom Resource Definitions: - Overview: crds/index.md - VulnerabilityReport: crds/vulnerability-report.md