document security implications of populate_* functions

1 files changed, 7 insertions, 0 deletions

diff --git a/linuxnamespaces/__init__.py b/linuxnamespaces/__init__.py
index c12a13c..2b92462 100644
--- a/linuxnamespaces/__init__.py
+++ b/linuxnamespaces/__init__.py
@@ -359,6 +359,10 @@ def populate_dev(
     """Mount a tmpfs to the dev directory beneath newroot and populate it with
     basic devices by bind mounting them from the dev directory beneath
     origroot. Also mount a new pts instance.
+
+    Even though a CAP_SYS_ADMIN-enabled process can umount components of the
+    /dev hierarchy, they they cannot gain privileges in doing so as no
+    hierarchies are restricted via tmpfs mounts or read-only bind mounts.
     """
     origdev = AtLocation(origroot) / "dev"
     newdev = AtLocation(newroot) / "dev"
@@ -430,6 +434,9 @@ def populate_sys(
 ) -> None:
     """Create a /sys hierarchy below newroot. Bind the cgroup hierarchy. The
     cgroup hierarchy will be mounted read-only if mounting the root group.
+
+    A process with CAP_SYS_ADMIN can remount the created bind mounts read-write
+    or umount hiding mounts and thus elevate their privileges.
     """
     newsys = AtLocation(newroot) / "sys"
     mflags = MountFlags.NOSUID | MountFlags.NOEXEC | MountFlags.NODEV