Skip to content

Commit

Permalink
docs(tutorial): manage access to security reports (aquasecurity#776)
Browse files Browse the repository at this point in the history
Signed-off-by: Daniel Pacak <pacak.daniel@gmail.com>
  • Loading branch information
danielpacak authored Oct 27, 2021
1 parent c09c535 commit e37c02e
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 86 deletions.
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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 \
Expand All @@ -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
Expand All @@ -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 \
Expand Down Expand Up @@ -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 \
Expand All @@ -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
Expand All @@ -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/
[CRD]: ../crds/index.md
[RBAC]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/
[who-can]: https://github.com/aquasecurity/kubectl-who-can
2 changes: 2 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit e37c02e

Please sign in to comment.