From 14a41e28251e75295b13d36ceb3726af19b665aa Mon Sep 17 00:00:00 2001
From: Alban Crequy <alban@kinvolk.io>
Date: Thu, 19 Nov 2020 19:36:08 +0100
Subject: [PATCH] docs: add use cases

Signed-off-by: Alban Crequy <alban@kinvolk.io>
---
 README.md        |  5 ++--
 docs/usecases.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 3 deletions(-)
 create mode 100644 docs/usecases.md

diff --git a/README.md b/README.md
index eeb9cdc3..575ddd7f 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,8 @@
 # Kinvolk Seccomp Agent
 
 The Kinvolk Seccomp Agent is receiving seccomp file descriptors from container runtimes and handling system calls on behalf of the containers.
-Its goal is to support different use cases:
-- unprivileged container builds (procfs mounts with masked entries)
-- support of safe mknod (e.g. /dev/null)
+
+See the [different use cases](docs/usecases.md)
 
 It is possible to write your own seccomp agent with a different behaviour by reusing the packages in the `pkg/` directory.
 The Kinvolk Seccomp Agent is only about 100 lines of code. It relies on different packages:
diff --git a/docs/usecases.md b/docs/usecases.md
new file mode 100644
index 00000000..81552e68
--- /dev/null
+++ b/docs/usecases.md
@@ -0,0 +1,66 @@
+---
+title: Use cases
+weight: 10
+description: >
+  Use cases for the Seccomp Agent.
+---
+
+There are several use cases for using a Seccomp Agent.
+
+## Mounting procfs in unprivileged containers
+
+An unprivileged Kubernetes pod might want to use
+[RootlessKit](https://github.com/rootless-containers/rootlesskit). There is one
+step that is difficult in this setup: [mounting procfs in a unprivileged user
+namespace](https://kinvolk.io/blog/2018/04/towards-unprivileged-container-builds/#the-exception-of-procfs-and-sysfs).
+This is because Kubernetes pods are normally running with a masked procfs (see
+[AllowedProcMountTypes](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#allowedprocmounttypes)
+in the Pod Security Policy documentation).
+
+To avoid running a pod with `ProcMountType=UnmaskedProcMount` (which could be a
+security issue), users can run a seccomp agent to capture the `mount` system
+call and perform the procfs mount in the inner container in the seccomp agent
+on behalf of the container.  This allows users to use RootlessKit and still
+keep the security of masked procfs mount.
+
+## Support for a subset of device mknod
+
+A VPN container might need `/dev/net/tun` but cannot create the device without
+`CAP_MKNOD`. Giving this capability to the container could be risky: the
+container would be able to abuse the mknod call to get access to disks such as
+`/dev/sda`.
+
+The alternative could be to keep the container without `CAP_MKNOD` and add a
+seccomp filter on `mknod` to let the Seccomp Agent run `mknod()` on behalf of
+the container,
+
+## Rootless Containers without /etc/subuid (`subuidless`)
+
+The goal of subuidless is to allow running containers without /etc/subuid,
+which isn't good fit for shared environments.
+
+See:
+https://github.com/rootless-containers/subuidless
+
+## Accelerator for slirp4netns (`bypass4netns`)
+
+When using slirp4netns as a networking solution for rootless containers, the
+performance impact can be big. However, by capturing the `connect` call and
+handling it in the seccomp agent, we avoid the performance impact: the network
+traffic is no longer routed through a userspace process.
+
+See:
+https://github.com/rootless-containers/bypass4netns
+
+## Emulating privileged sysctl
+
+TODO
+
+## Detection and reporting of unusual behavior with system calls
+
+TODO
+
+## Error injections (Chaos Engineering)
+
+The Seccomp policy could include a scenario defining which system calls to make
+fail.