From 8028e03b9a665d3341e9d4ac0a51f5d24d93eb76 Mon Sep 17 00:00:00 2001
From: Jonada Hoxha <jonada.hoxha@icinga.com>
Date: Mon, 4 Nov 2024 09:27:59 +0100
Subject: [PATCH] Docs: Add 04-Security.md

---
 doc/04-Security.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 doc/04-Security.md

diff --git a/doc/04-Security.md b/doc/04-Security.md
new file mode 100644
index 00000000..801db5c2
--- /dev/null
+++ b/doc/04-Security.md
@@ -0,0 +1,77 @@
+# Security
+
+Icinga for Kubernetes allows users to show different Kubernetes resources. Users may be restricted to a specific set of
+resources, by use of **permissions** and **restrictions**.
+
+## Permissions
+
+> If a role [limits users](#filters) to a specific set of results, the
+> permissions or refusals of the very same role only apply to these results.
+ 
+If a user has permission to show one resource but lacks permissions for another resource that is dependent on or related
+to the first, the dependent resource will not appear in the detail view of the accessible resource.
+
+This ensures that users can only see the specific resources they are authorized for, maintaining a strict boundary of
+visibility and data access.
+
+### Examples
+
+If a user has permission to show **Deployments** but does not have permission to show **ReplicaSets**, the
+**Deployment** detail view will omit any associated **ReplicaSets**.
+
+Similarly, if a user can view **DaemonSets** but lacks permissions for **Pods** within the same namespace, the Pods will
+be excluded from the DaemonSet's detail view.
+
+Also, if a user lacks permission to show **ReplicaSets**, any **Events** related to **ReplicaSets** will not be shown at
+all in the **ListController**.
+
+| Name                                     | Allow...                         |
+|------------------------------------------|----------------------------------|
+| kubernetes/config-maps/show              | to show config maps              |
+| kubernetes/cron-jobs/show                | to show cron jobs                |
+| kubernetes/daemon-sets/show              | to show daemon sets              |
+| kubernetes/deployments/show              | to show deployments              |
+| kubernetes/events/show                   | to show events                   |
+| kubernetes/ingresses/show                | to show ingresses                |
+| kubernetes/jobs/show                     | to show jobs                     |
+| kubernetes/nodes/show                    | to show nodes                    |
+| kubernetes/persistent-volume-claims/show | to show persistent volume claims |
+| kubernetes/persistent-volumes/show       | to show persistent volumes       |
+| kubernetes/pods/show                     | to show pods                     |
+| kubernetes/replica-sets/show             | to show replica sets             |
+| kubernetes/secrets/show                  | to show secrets                  |
+| kubernetes/services/show                 | to show services                 |
+| kubernetes/stateful-sets/show            | to show stateful sets            |
+| kubernetes/yaml/show                     | to show yaml                     |
+
+## Restrictions
+
+### Filters
+
+Filters limit users to a specific set of results.
+
+> **Note:**
+>
+> Filters from multiple roles will widen available access.
+
+| Name                        | Description                                                       |
+|-----------------------------|-------------------------------------------------------------------|
+| kubernetes/filter/resources | Restrict access to the Kubernetes resources that match the filter |
+
+`kubernetes/filter/resources` will only allow users to access matching Kubernetes resources. This applies to all
+resources.
+
+Allowed columns are namespace and name.
+
+> **Note:**
+>
+> Nodes, namespaces and persistent volumes do not belong to a namespace, therefore only the name is available for
+> filtering.
+
+## Restricted Permissions:
+
+Restricted permissions is the combination of permission(s) and restriction(s), i.e. if I have two roles where role a
+allows to list pods and has defined a certain restriction and role b allows to list deployments and has specified a
+certain restriction, I see pods that are restricted by role a and I see deployments that are restricted by role b. We
+have introduced something similar in Icinga DB. Previously, with the functionality as it exists in the monitoring module
+for example, I would see pods and deployments that match both role a and role b restrictions.