cilium · pchaigno · Feb 21, 2023 · Feb 15, 2023 · Feb 15, 2023 · Feb 17, 2023
diff --git a/Documentation/index.rst b/Documentation/index.rst
@@ -33,6 +33,8 @@ The documentation is divided into the following sections:
 * :ref:`dev_guide` : Gives background to those looking to develop and contribute
   modifications to the Cilium code or documentation.
 
+* :ref:`security_root` : Provides a one-page resource of best practices for securing Cilium.
+
 A `hands-on tutorial <https://cilium.io/enterprise/#trainings>`_
 in a live environment is also available for users looking for a way to quickly
 get started and experiment with Cilium.
@@ -88,9 +90,10 @@ get started and experiment with Cilium.
    :maxdepth: 2
    :caption: Security
 
+   security/index
    security/network/index
    security/policy/index
-   security/tutorial-toc
+   security/restrict-pod-access
 
 .. toctree::
    :maxdepth: 2

diff --git a/Documentation/security/cassandra.rst b/Documentation/security/cassandra.rst
@@ -4,8 +4,6 @@
     Please use the official rendered version released here:
     https://docs.cilium.io
 
-.. _gs_cassandra:
-
 *****************************
 Securing a Cassandra Database
 *****************************

diff --git a/Documentation/security/tutorial-toc.rst → Documentation/security/index.rst b/Documentation/security/tutorial-toc.rst → Documentation/security/index.rst
@@ -4,10 +4,10 @@
     Please use the official rendered version released here:
     https://docs.cilium.io
 
-.. _security_tutorial_root:
+.. _security_root:
 
-Network Policy Security Tutorials
----------------------------------
+Securing Networks with Cilium
+-----------------------------
 
 .. toctree::
    :maxdepth: 2
@@ -24,3 +24,4 @@ Network Policy Security Tutorials
    aws
    policy-creation
    host-firewall
+   restrict-pod-access
diff --git a/Documentation/security/network/index.rst b/Documentation/security/network/index.rst
@@ -5,10 +5,9 @@
     https://docs.cilium.io
 
 .. _concepts_security:
-.. _security_root:
 
-Network Security
-----------------
+Overview of Network Security
+----------------------------
 
 .. toctree::
    :maxdepth: 2

diff --git a/Documentation/security/policy/index.rst b/Documentation/security/policy/index.rst
@@ -8,10 +8,10 @@
 .. _Network Policies:
 .. _Network Policy:
 
-Network Policy
---------------
+Overview of Network Policy
+--------------------------
 
-This chapter documents the policy language used to configure network policies
+This page documents the policy language used to configure network policies
 in Cilium. Security policies can be specified and imported via the following
 mechanisms:
 

diff --git a/Documentation/security/restrict-pod-access.rst b/Documentation/security/restrict-pod-access.rst
@@ -0,0 +1,53 @@
+.. only:: not (epub or latex or html)
+
+    WARNING: You are looking at unreleased Cilium documentation.
+    Please use the official rendered version released here:
+    https://docs.cilium.io
+
+.. _security_restrict_pod_access:
+
+========================================
+Restricting privileged Cilium pod access
+========================================
+
+This page shows you how to restrict privileged access to Cilium pods by limiting access from the Kubernetes API, specifically from `kubernetes exec pod`_.
+
+.. include:: gsg_requirements.rst
+
+Background
+----------
+
+The Cilium agent needs some specific Linux capabilities to perform essential system and network operations.
+
+Cilium relies on Kubernetes and containers to set up the environment and mount the corresponding volumes. Cilium doesn't perform any extra operations that could result in an unsafe volume mount. 
+
+Cilium needs kernel interfaces to properly configure the environment. Some kernel interfaces are part of the ``/proc`` filesystem, which includes host and machine configurations that can't be virtualized or namespaced.
+
+If ``pod exec`` operations aren't restricted, then remote `exec into pods`_ and containers defeats Linux namespace restrictions.
+
+The Linux kernel restricts joining other namespaces by default. To enter the Cilium container, the ``CAP_SYS_ADMIN`` capability is required in both the current user namespace and in the Cilium user namespace (the initial namespace). If both namespaces have the ``CAP_SYS_ADMIN`` capability, then this is already a privileged access.
+
+To prevent privileged access to Cilium pods, restrict access to the Kubernetes API and arbitrary ``pod exec`` operations.
+
+Restrict authorization for ``kubernetes exec pod``
+--------------------------------------------------
+
+To restrict access to Cilium pods through ``kubernetes exec pod``:
+
+1. Configure `RBAC authorization`_ in Kubernetes.
+
+2. Limit `access to the proxy subresource of Nodes`_.
+
+References
+----------
+
+For more information about namespace security, visit:
+
+- https://man7.org/linux/man-pages/man7/user_namespaces.7.html
+- https://man7.org/linux/man-pages/man1/nsenter.1.html
+- https://man7.org/linux/man-pages/man2/setns.2.html
+
+.. _kubernetes exec pod: https://kubernetes.io/docs/tasks/debug/debug-application/get-shell-running-container/
+.. _exec into pods: https://kubernetes.io/docs/tasks/debug/debug-application/get-shell-running-container/
+.. _RBAC authorization: https://kubernetes.io/docs/reference/access-authn-authz/rbac/
+.. _access to the proxy subresource of Nodes: https://kubernetes.io/docs/concepts/security/rbac-good-practices/#access-to-proxy-subresource-of-nodes
diff --git a/Documentation/spelling_wordlist.txt b/Documentation/spelling_wordlist.txt
@@ -1060,6 +1060,7 @@ virtIO
 virtio
 virtualbox
 virtualization
+virtualized
 vlan
 vlanBypass
 vmlinux