Merge pull request opencontainers#675 from crosbymichael/caps

Add ambient and bounding capability support
stefanberger · Feb 22, 2017 · ac9f8e0 · ac9f8e0
2 parents 8c22b69 + eb114f0
commit ac9f8e0
Show file tree

Hide file tree

Showing 4 changed files with 110 additions and 17 deletions.
diff --git a/config.md b/config.md
@@ -132,7 +132,13 @@ For Windows, see links for details about [mountvol](http://ss64.com/nt/mountvol.
 * **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2001's `environ`][ieee-1003.1-2001-xbd-c8.1].
 * **`args`** (array of strings, REQUIRED) with similar semantics to [IEEE Std 1003.1-2001 `execvp`'s *argv*][ieee-1003.1-2001-xsh-exec].
   This specification extends the IEEE standard in that at least one entry is REQUIRED, and that entry is used with the same semantics as `execvp`'s *file*.
-* **`capabilities`** (array of strings, OPTIONAL) is an array that specifies the set of capabilities of the process(es) inside the container. Valid values are platform-specific. For example, valid values for Linux are defined in the [CAPABILITIES(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html) man page.
+* **`capabilities`** (object, OPTIONAL) is an object containing arrays that specifies the sets of capabilities for the process(es) inside the container. Valid values are platform-specific. For example, valid values for Linux are defined in the [CAPABILITIES(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html) man page.
+  capabilities contains the following properties:
+    * **`effective`** (array of strings, OPTIONAL) - the `effective` field is an array of effective capabilities that are kept for the process.
+    * **`bounding`** (array of strings, OPTIONAL) - the `bounding` field is an array of bounding capabilities that are kept for the process.
+    * **`inheritable`** (array of strings, OPTIONAL) - the `inheritable` field is an array of inheritable capabilities that are kept for the process.
+    * **`permitted`** (array of strings, OPTIONAL) - the `permitted` field is an array of permitted capabilities that are kept for the process.
+    * **`ambient`** (array of strings, OPTIONAL) - the `ambient` field is an array of ambient capabilities that are kept for the process.
 * **`rlimits`** (array of objects, OPTIONAL) allows setting resource limits for a process inside the container.
   Each entry has the following structure:
 
@@ -191,11 +197,30 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are
     "apparmorProfile": "acme_secure_profile",
     "selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
     "noNewPrivileges": true,
-    "capabilities": [
-        "CAP_AUDIT_WRITE",
-        "CAP_KILL",
-        "CAP_NET_BIND_SERVICE"
-    ],
+    "capabilities": {
+        "bounding": [
+            "CAP_AUDIT_WRITE",
+            "CAP_KILL",
+            "CAP_NET_BIND_SERVICE"
+        ],
+       "permitted": [
+            "CAP_AUDIT_WRITE",
+            "CAP_KILL",
+            "CAP_NET_BIND_SERVICE"
+        ],
+       "inheritable": [
+            "CAP_AUDIT_WRITE",
+            "CAP_KILL",
+            "CAP_NET_BIND_SERVICE"
+        ],
+        "effective": [
+            "CAP_AUDIT_WRITE",
+            "CAP_KILL",
+        ],
+        "ambient": [
+            "CAP_NET_BIND_SERVICE"
+        ]
+    },
     "rlimits": [
         {
             "type": "RLIMIT_NOFILE",
@@ -446,11 +471,30 @@ Here is a full example `config.json` for reference.
             "TERM=xterm"
         ],
         "cwd": "/",
-        "capabilities": [
-            "CAP_AUDIT_WRITE",
-            "CAP_KILL",
-            "CAP_NET_BIND_SERVICE"
-        ],
+        "capabilities": {
+            "bounding": [
+                "CAP_AUDIT_WRITE",
+                "CAP_KILL",
+                "CAP_NET_BIND_SERVICE"
+            ],
+            "permitted": [
+                "CAP_AUDIT_WRITE",
+                "CAP_KILL",
+                "CAP_NET_BIND_SERVICE"
+            ],
+            "inheritable": [
+                "CAP_AUDIT_WRITE",
+                "CAP_KILL",
+                "CAP_NET_BIND_SERVICE"
+            ],
+            "effective": [
+                "CAP_AUDIT_WRITE",
+                "CAP_KILL",
+            ],
+            "ambient": [
+                "CAP_NET_BIND_SERVICE"
+            ]
+        },
         "rlimits": [
             {
                 "type": "RLIMIT_CORE",

diff --git a/schema/config-schema.json b/schema/config-schema.json
@@ -135,9 +135,43 @@
                 },
                 "capabilities": {
                     "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities",
-                    "type": "array",
-                    "items": {
-                        "$ref": "defs-linux.json#/definitions/Capability"
+                    "type": "object",
+                    "properties": {
+                        "bounding": {
+                            "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/bounding",
+                            "type": "array",
+                            "items": {
+                                "$ref": "defs-linux.json#/definitions/Capability"
+                            }
+                        },
+                        "permitted": {
+                            "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/permitted",
+                            "type": "array",
+                            "items": {
+                                "$ref": "defs-linux.json#/definitions/Capability"
+                            }
+                        },
+                        "effective": {
+                            "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/effective",
+                            "type": "array",
+                            "items": {
+                                "$ref": "defs-linux.json#/definitions/Capability"
+                            }
+                        },
+                        "inheritable": {
+                            "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/inheritable",
+                            "type": "array",
+                            "items": {
+                                "$ref": "defs-linux.json#/definitions/Capability"
+                            }
+                        },
+                        "ambient": {
+                            "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/ambient",
+                            "type": "array",
+                            "items": {
+                                "$ref": "defs-linux.json#/definitions/Capability"
+                            }
+                        }
                     }
                 },
                 "apparmorProfile": {

diff --git a/schema/defs-linux.json b/schema/defs-linux.json
@@ -78,7 +78,7 @@
             }
         },
         "Capability": {
-            "description": "Linux process permissions",
+            "description": "Linux process capabilities",
             "type": "string",
             "pattern": "^CAP_([A-Z]|_)+$"
         },

diff --git a/specs-go/config.go b/specs-go/config.go
@@ -44,8 +44,8 @@ type Process struct {
 	// Cwd is the current working directory for the process and must be
 	// relative to the container's root.
 	Cwd string `json:"cwd"`
-	// Capabilities are Linux capabilities that are kept for the container.
-	Capabilities []string `json:"capabilities,omitempty" platform:"linux"`
+	// Capabilities are Linux capabilities that are kept for the process.
+	Capabilities *LinuxCapabilities `json:"capabilities,omitempty" platform:"linux"`
 	// Rlimits specifies rlimit options to apply to the process.
 	Rlimits []LinuxRlimit `json:"rlimits,omitempty" platform:"linux"`
 	// NoNewPrivileges controls whether additional privileges could be gained by processes in the container.
@@ -56,6 +56,21 @@ type Process struct {
 	SelinuxLabel string `json:"selinuxLabel,omitempty" platform:"linux"`
 }
 
+// LinuxCapabilities specifies the whitelist of capabilities that are kept for a process.
+// http://man7.org/linux/man-pages/man7/capabilities.7.html
+type LinuxCapabilities struct {
+	// Bounding is the set of capabilities checked by the kernel.
+	Bounding []string `json:"bounding,omitempty" platform:"linux"`
+	// Effective is the set of capabilities checked by the kernel.
+	Effective []string `json:"effective,omitempty" platform:"linux"`
+	// Inheritable is the capabilities preserved across execve.
+	Inheritable []string `json:"inheritable,omitempty" platform:"linux"`
+	// Permitted is the limiting superset for effective capabilities.
+	Permitted []string `json:"permitted,omitempty" platform:"linux"`
+	// Ambient is the ambient set of capabilities that are kept.
+	Ambient []string `json:"ambient,omitempty" platform:"linux"`
+}
+
 // Box specifies dimensions of a rectangle. Used for specifying the size of a console.
 type Box struct {
 	// Height is the vertical dimension of a box.