seccomp-util, analyze: export comments as a help string

Just to make the whole thing easier for users.

4 files changed, 23 insertions, 19 deletions

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 0de263cb07..dd574df82a 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -1339,11 +1339,11 @@
               </row>
               <row>
                 <entry>@module</entry>
-                <entry>Kernel module control (<citerefentry project='man-pages'><refentrytitle>init_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>delete_module</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry>
+                <entry>Loading and unloading of kernel modules (<citerefentry project='man-pages'><refentrytitle>init_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>delete_module</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry>
               </row>
               <row>
                 <entry>@mount</entry>
-                <entry>File system mounting and unmounting (<citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry>
+                <entry>Mounting and unmounting of file systems (<citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry>
               </row>
               <row>
                 <entry>@network-io</entry>
@@ -1359,7 +1359,7 @@
               </row>
               <row>
                 <entry>@process</entry>
-                <entry>Process control, execution, namespaces (<citerefentry project='man-pages'><refentrytitle>clone</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …</entry>
+                <entry>Process control, execution, namespaceing operations (<citerefentry project='man-pages'><refentrytitle>clone</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …</entry>
               </row>
               <row>
                 <entry>@raw-io</entry>
diff --git a/src/analyze/analyze.c b/src/analyze/analyze.c
index 0495fca17d..83e1cdf11d 100644
--- a/src/analyze/analyze.c
+++ b/src/analyze/analyze.c
@@ -1280,6 +1280,7 @@ static void dump_syscall_filter(const SyscallFilterSet *set) {
         const char *syscall;
 
         printf("%s\n", set->name);
+        printf("    # %s\n", set->help);
         NULSTR_FOREACH(syscall, set->value)
                 printf("    %s\n", syscall);
 }
diff --git a/src/shared/seccomp-util.c b/src/shared/seccomp-util.c
index 325dcc866e..fc1f6b68f2 100644
--- a/src/shared/seccomp-util.c
+++ b/src/shared/seccomp-util.c
@@ -218,8 +218,8 @@ bool is_seccomp_available(void) {
 
 const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
         [SYSCALL_FILTER_SET_DEFAULT] = {
-                /* Default list: the most basic of operations */
                 .name = "@default",
+                .help = "System calls that are always permitted",
                 .value =
                 "clock_getres\0"
                 "clock_gettime\0"
@@ -236,8 +236,8 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "time\0"
         },
         [SYSCALL_FILTER_SET_BASIC_IO] = {
-                /* Basic IO */
                 .name = "@basic-io",
+                .help = "Basic IO",
                 .value =
                 "close\0"
                 "dup2\0"
@@ -254,8 +254,8 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "writev\0"
         },
         [SYSCALL_FILTER_SET_CLOCK] = {
-                /* Clock */
                 .name = "@clock",
+                .help = "Change the system time",
                 .value =
                 "adjtimex\0"
                 "clock_adjtime\0"
@@ -264,8 +264,8 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "stime\0"
         },
         [SYSCALL_FILTER_SET_CPU_EMULATION] = {
-                /* CPU emulation calls */
                 .name = "@cpu-emulation",
+                .help = "System calls for CPU emulation functionality",
                 .value =
                 "modify_ldt\0"
                 "subpage_prot\0"
@@ -274,8 +274,8 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "vm86old\0"
         },
         [SYSCALL_FILTER_SET_DEBUG] = {
-                /* Debugging/Performance Monitoring/Tracing */
                 .name = "@debug",
+                .help = "Debugging, performance monitoring and tracing functionality",
                 .value =
                 "lookup_dcookie\0"
                 "perf_event_open\0"
@@ -289,8 +289,8 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "sys_debug_setcontext\0"
         },
         [SYSCALL_FILTER_SET_IO_EVENT] = {
-                /* Event loop use */
                 .name = "@io-event",
+                .help = "Event loop system calls",
                 .value =
                 "_newselect\0"
                 "epoll_create1\0"
@@ -308,9 +308,10 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "select\0"
         },
         [SYSCALL_FILTER_SET_IPC] = {
-                /* Message queues, SYSV IPC or other IPC */
                 .name = "@ipc",
-                .value = "ipc\0"
+                .help = "SysV IPC, POSIX Message Queues or other IPC",
+                .value =
+                "ipc\0"
                 "memfd_create\0"
                 "mq_getsetattr\0"
                 "mq_notify\0"
@@ -336,24 +337,24 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "shmget\0"
         },
         [SYSCALL_FILTER_SET_KEYRING] = {
-                /* Keyring */
                 .name = "@keyring",
+                .help = "Kernel keyring access",
                 .value =
                 "add_key\0"
                 "keyctl\0"
                 "request_key\0"
         },
         [SYSCALL_FILTER_SET_MODULE] = {
-                /* Kernel module control */
                 .name = "@module",
+                .help = "Loading and unloading of kernel modules",
                 .value =
                 "delete_module\0"
                 "finit_module\0"
                 "init_module\0"
         },
         [SYSCALL_FILTER_SET_MOUNT] = {
-                /* Mounting */
                 .name = "@mount",
+                .help = "Mounting and unmounting of file systems",
                 .value =
                 "chroot\0"
                 "mount\0"
@@ -362,8 +363,8 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "umount\0"
         },
         [SYSCALL_FILTER_SET_NETWORK_IO] = {
-                /* Network or Unix socket IO, should not be needed if not network facing */
                 .name = "@network-io",
+                .help = "Network or Unix socket IO, should not be needed if not network facing",
                 .value =
                 "accept4\0"
                 "accept\0"
@@ -388,8 +389,9 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "socketpair\0"
         },
         [SYSCALL_FILTER_SET_OBSOLETE] = {
-                /* Unusual, obsolete or unimplemented, some unknown even to libseccomp */
+                /* some unknown even to libseccomp */
                 .name = "@obsolete",
+                .help = "Unusual, obsolete or unimplemented system calls",
                 .value =
                 "_sysctl\0"
                 "afs_syscall\0"
@@ -417,8 +419,8 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "vserver\0"
         },
         [SYSCALL_FILTER_SET_PRIVILEGED] = {
-                /* Nice grab-bag of all system calls which need superuser capabilities */
                 .name = "@privileged",
+                .help = "All system calls which need super-user capabilities",
                 .value =
                 "@clock\0"
                 "@module\0"
@@ -459,8 +461,8 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "vhangup\0"
         },
         [SYSCALL_FILTER_SET_PROCESS] = {
-                /* Process control, execution, namespaces */
                 .name = "@process",
+                .help = "Process control, execution, namespaceing operations",
                 .value =
                 "arch_prctl\0"
                 "clone\0"
@@ -475,8 +477,8 @@ const SyscallFilterSet syscall_filter_sets[_SYSCALL_FILTER_SET_MAX] = {
                 "vfork\0"
         },
         [SYSCALL_FILTER_SET_RAW_IO] = {
-                /* Raw I/O ports */
                 .name = "@raw-io",
+                .help = "Raw I/O port access",
                 .value =
                 "ioperm\0"
                 "iopl\0"
diff --git a/src/shared/seccomp-util.h b/src/shared/seccomp-util.h
index ce7417b0ba..f0b9f455ab 100644
--- a/src/shared/seccomp-util.h
+++ b/src/shared/seccomp-util.h
@@ -34,6 +34,7 @@ bool is_seccomp_available(void);
 
 typedef struct SyscallFilterSet {
         const char *name;
+        const char *help;
         const char *value;
 } SyscallFilterSet;