kore-doc

commit 4f7773ea2b92853b1f028462eca78e9b5eb325db
parent 6b3b25e27efeff11d8442efa017f175ad54946ba
Author: Joris Vink <joris@coders.se>
Date:   Thu,  8 Oct 2020 13:38:06 +0200

add initial seccomp docs

Diffstat:
SUMMARY.md
 | 
1
+
api/seccomp.md
 | 
46
++++++++++++++++++++++++++++++++++++++++++++++

2 files changed, 47 insertions(+), 0 deletions(-)
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -22,6 +22,7 @@
   * [Pgsql](api/pgsql.md)
   * [Pools](api/pools.md)
   * [Python](api/python.md)
+  * [Seccomp](api/seccomp.md)
   * [Tasks](api/tasks.md)
   * [Websockets](api/websockets.md)
 * [Examples](examples.md)
diff --git a/api/seccomp.md b/api/seccomp.md
@@ -0,0 +1,46 @@
+# seccomp
+
+(This is only valid for Linux).
+
+Kore uses seccomp to filter which system calls its processes can make.
+
+As an application developer you can extend the allow-list to better
+suit your application its needs.
+
+## Adding your own seccomp rules
+
+If you wish to extend the allow-list, you can use the KORE_SECCOMP_FILTER
+macro. In the example below we allow ioctl(2) and shmat(2) are allowed.
+
+```
+#include <kore/seccomp.h>
+
+KORE_SECCOMP_FILTER("app",
+	KORE_SYSCALL_ALLOW("ioctl"),
+	KORE_SYSCALL_ALLOW("shmat")
+);
+```
+
+In another example, we allow write() to stdout but no other file descriptor.
+
+```
+#include <kore/seccomp.h>
+
+KORE_SECCOMP_FILTER("app",
+	KORE_SYSCALL_ALLOW_ARG("write", 0, STDOUT_FILENO),
+	KORE_SYSCALL_DENY("write", EPERM)
+);
+```
+
+Kore provides a few handy macros that can be used in a KORE_SECCOMP_FILTER:
+
+- KORE_SYSCALL_DENY(name, errno)
+- KORE_SYSCALL_DENY_ARG(name, argidx, val, errno)
+- KORE_SYSCALL_DENY_MASK(name, argidx, val, errno)
+- KORE_SYSCALL_DENY_WITH_FLAG(name, argidx, val, errno)
+
+- KORE_SYSCALL_ALLOW(name)
+- KORE_SYSCALL_ALLOW_LOG(name)
+- KORE_SYSCALL_ALLOW_ARG(name, argidx, val)
+- KORE_SYSCALL_ALLOW_MASK(name, argidx, val)
+- KORE_SYSCALL_ALLOW_WITH_FLAG(name, argidx, val)