Add Seccomp Notify support

This adds the specification for Seccomp Userspace Notification and the
Golang bindings. This contains:
- New fields in the seccomp section to use with seccomp userspace
  notification.
- Additional SeccompState struct containing the container state and file
  descriptors passed for seccomp.

This was discussed in the OCI Weekly Discussion on September 16th,
2020. After review on github, this implementation was changed to the
"Proposal with listenerPath and listenerExtraMetadata". For more
information see:
- #1073 (comment)

Docs presented on the community meeting (for the old implementation
using hooks):
- https://hackmd.io/El8Dd2xrTlCaCG59ns5cwg#September-16-2020
- https://docs.google.com/document/d/1xHw5GQjMj6ZKR-40aKmTWZRkvlPuzMGQRu-YpOFQc30/edit

Documentation for this feature:
- https://www.kernel.org/doc/html/v5.0/userspace-api/seccomp_filter.html#userspace-notification
- man pages: seccomp_user_notif.2 at
  https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=seccomp_user_notif
- brauner's blog:
  https://brauner.github.io/2020/07/23/seccomp-notify.html

This PR is an alternative proposal to PR 1038. While similar in nature,
the main difference is that this PR adds optional metadata to be sent to
the seccomp agent and specifies how the UNIX socket MUST be used.

Signed-off-by: Rodrigo Campos <[email protected]>
Signed-off-by: Alban Crequy <[email protected]>
Signed-off-by: Mauricio Vásquez <[email protected]>

Author: rata

config-linux.md

@@ -629,6 +629,21 @@ The following parameters can be specified to set up seccomp:
     * `SECCOMP_FILTER_FLAG_LOG`
     * `SECCOMP_FILTER_FLAG_SPEC_ALLOW`
 
+* **`listenerPath`** *(string, OPTIONAL)* - specifies the path of UNIX domain socket over which the runtime will send the [container process state](#containerprocessstate) data structure when the `SCMP_ACT_NOTIFY` action is used.
+    This socket MUST use `AF_UNIX` domain and `SOCK_STREAM` type.
+    The runtime MUST send exactly one [container process state](#containerprocessstate) per connection.
+    The connection MUST NOT be reused and it MUST be closed after sending a seccomp state.
+    If sending to this socket fails, the runtime MUST [generate an error](runtime.md#errors).
+    If the `SCMP_ACT_NOTIFY` action is not used this value is ignored.
+
+    The runtime sends the following file descriptors using `SCM_RIGHTS` and set their names in the `fds` array of the [container process state](#containerprocessstate):
+
+    * **`seccompFd`** (string, REQUIRED) is the seccomp file descriptor returned by the seccomp syscall.
+
+* **`listenerMetadata`** *(string, OPTIONAL)* - specifies an opaque data to pass to the seccomp agent.
+    This string will be sent as the `metadata` field in the [container process state](#containerprocessstate).
+    This field MUST NOT be set if `listenerPath` is not set.
+
 * **`syscalls`** *(array of objects, OPTIONAL)* - match a syscall in seccomp.
     While this property is OPTIONAL, some values of `defaultAction` are not useful without `syscalls` entries.
     For example, if `defaultAction` is `SCMP_ACT_KILL` and `syscalls` is empty or unset, the kernel will kill the container process on its first syscall.
@@ -637,7 +652,7 @@ The following parameters can be specified to set up seccomp:
     * **`names`** *(array of strings, REQUIRED)* - the names of the syscalls.
         `names` MUST contain at least one entry.
     * **`action`** *(string, REQUIRED)* - the action for seccomp rules.
-        A valid list of constants as of libseccomp v2.4.0 is shown below.
+        A valid list of constants as of libseccomp v2.5.0 is shown below.
 
         * `SCMP_ACT_KILL`
         * `SCMP_ACT_KILL_PROCESS`
@@ -647,6 +662,7 @@ The following parameters can be specified to set up seccomp:
         * `SCMP_ACT_TRACE`
         * `SCMP_ACT_ALLOW`
         * `SCMP_ACT_LOG`
+        * `SCMP_ACT_NOTIFY`
 
     * **`errnoRet`** *(uint, OPTIONAL)* - the errno return code to use.
         Some actions like `SCMP_ACT_ERRNO` and `SCMP_ACT_TRACE` allow to specify the errno code to return.
@@ -691,6 +707,45 @@ The following parameters can be specified to set up seccomp:
 }
 ```
 
+### <a name="containerprocessstate" />The Container Process State
+
+The container process state is a data structure passed via a UNIX socket.
+The container runtime MUST send the container process state over the UNIX socket as regular payload serialized in JSON and file descriptors MUST be sent using `SCM_RIGHTS`.
+The container runtime MAY use several `sendmsg(2)` calls to send the aforementioned data.
+If more than one `sendmsg(2)` is used, the file descriptors MUST be sent only in the first call.
+
+The container process state includes the following properties:
+
+* **`ociVersion`** (string, REQUIRED) is version of the Open Container Initiative Runtime Specification with which the container process state complies.
+* **`fds`** (array, OPTIONAL) is a string array containing the names of the file descriptors passed.
+    The index of the name in this array corresponds to index of the file descriptors in the `SCM_RIGHTS` array.
+* **`pid`** (int, REQUIRED) is the container process ID, as seen by the runtime.
+* **`metadata`** (string, OPTIONAL) opaque metadata.
+* **`state`** ([state](runtime.md#state), REQUIRED) is the state of the container.
+
+Example sending a single `seccompFD` file descriptor in the `SCM_RIGHTS` array:
+
+```json
+{
+    "ociVersion": "0.2.0",
+    "fds": [
+        "seccompFd"
+    ],
+    "pid": 4422,
+    "metadata": "MKNOD=/dev/null,/dev/net/tun;BPF_MAP_TYPES=hash,array",
+    "state": {
+        "ociVersion": "0.2.0",
+        "id": "oci-container1",
+        "status": "creating",
+        "pid": 4422,
+        "bundle": "/containers/redis",
+        "annotations": {
+            "myKey": "myValue"
+        }
+    }
+}
+```
+
 ## <a name="configLinuxRootfsMountPropagation" />Rootfs Mount Propagation
 
 **`rootfsPropagation`** (string, OPTIONAL) sets the rootfs's mount propagation.

schema/config-linux.json

@@ -212,6 +212,12 @@
                             "$ref": "defs-linux.json#/definitions/SeccompFlag"
                         }
                     },
+                    "listenerPath": {
+                        "type": "string"
+                    },
+                    "listenerMetadata": {
+                        "type": "string"
+                    },
                     "architectures": {
                         "type": "array",
                         "items": {

schema/defs-linux.json

@@ -61,15 +61,17 @@
                 "SCMP_ACT_ERRNO",
                 "SCMP_ACT_TRACE",
                 "SCMP_ACT_ALLOW",
-                "SCMP_ACT_LOG"
+                "SCMP_ACT_LOG",
+                "SCMP_ACT_NOTIFY"
             ]
         },
         "SeccompFlag": {
             "type": "string",
             "enum": [
                 "SECCOMP_FILTER_FLAG_TSYNC",
                 "SECCOMP_FILTER_FLAG_LOG",
-                "SECCOMP_FILTER_FLAG_SPEC_ALLOW"
+                "SECCOMP_FILTER_FLAG_SPEC_ALLOW",
+                "SECCOMP_FILTER_FLAG_NEW_LISTENER"
             ]
         },
         "SeccompOperators": {

specs-go/config.go

@@ -598,11 +598,13 @@ type VMImage struct {
 
 // LinuxSeccomp represents syscall restrictions
 type LinuxSeccomp struct {
-	DefaultAction   LinuxSeccompAction `json:"defaultAction"`
-	DefaultErrnoRet *uint              `json:"defaultErrnoRet,omitempty"`
-	Architectures   []Arch             `json:"architectures,omitempty"`
-	Flags           []LinuxSeccompFlag `json:"flags,omitempty"`
-	Syscalls        []LinuxSyscall     `json:"syscalls,omitempty"`
+	DefaultAction    LinuxSeccompAction `json:"defaultAction"`
+	DefaultErrnoRet  *uint              `json:"defaultErrnoRet,omitempty"`
+	Architectures    []Arch             `json:"architectures,omitempty"`
+	Flags            []LinuxSeccompFlag `json:"flags,omitempty"`
+	ListenerPath     string             `json:"listenerPath,omitempty"`
+	ListenerMetadata string             `json:"listenerMetadata,omitempty"`
+	Syscalls         []LinuxSyscall     `json:"syscalls,omitempty"`
 }
 
 // Arch used for additional architectures

specs-go/state.go

@@ -5,17 +5,17 @@ type ContainerState string
 
 const (
 	// StateCreating indicates that the container is being created
-	StateCreating ContainerState  = "creating"
+	StateCreating ContainerState = "creating"
 
 	// StateCreated indicates that the runtime has finished the create operation
-	StateCreated ContainerState  = "created"
+	StateCreated ContainerState = "created"
 
 	// StateRunning indicates that the container process has executed the
 	// user-specified program but has not exited
-	StateRunning ContainerState  = "running"
+	StateRunning ContainerState = "running"
 
 	// StateStopped indicates that the container process has exited
-	StateStopped ContainerState  = "stopped"
+	StateStopped ContainerState = "stopped"
 )
 
 // State holds information about the runtime state of the container.
@@ -33,3 +33,24 @@ type State struct {
 	// Annotations are key values associated with the container.
 	Annotations map[string]string `json:"annotations,omitempty"`
 }
+
+const (
+	// SeccompFdName is the name of the seccomp notify file descriptor.
+	SeccompFdName string = "seccompFd"
+)
+
+// ContainerProcessState holds information about the state of a container process.
+type ContainerProcessState struct {
+	// Version is the version of the specification that is supported.
+	Version string `json:"ociVersion"`
+	// Fds is a string array containing the names of the file descriptors passed.
+	// The index of the name in this array corresponds to index of the file
+	// descriptor in the `SCM_RIGHTS` array.
+	Fds []string `json:"fds"`
+	// Pid is the process ID as seen by the runtime.
+	Pid int `json:"pid"`
+	// Opaque metadata.
+	Metadata string `json:"metadata,omitempty"`
+	// State of the container.
+	State State `json:"state"`
+}