Add capabilities support (#444)

Closes #442

This adds capabilities support to LinuxContainer via a new surface in
ContainerizationOS + some C wrappers.

Author: dcantah

Sources/CShim/capability.c

@@ -0,0 +1,32 @@
+/*
+ * Copyright © 2025 Apple Inc. and the Containerization project authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#if defined(__linux__)
+
+#include <sys/syscall.h>
+#include <unistd.h>
+#include "capability.h"
+
+// Capability syscall wrappers
+int CZ_capget(void *header, void *data) {
+    return syscall(SYS_capget, header, data);
+}
+
+int CZ_capset(void *header, void *data) {
+    return syscall(SYS_capset, header, data);
+}
+
+#endif

Sources/CShim/include/capability.h

@@ -0,0 +1,28 @@
+/*
+ * Copyright © 2025 Apple Inc. and the Containerization project authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __CAPABILITY_H
+#define __CAPABILITY_H
+
+#if defined(__linux__)
+
+// Capability syscall wrappers
+int CZ_capget(void *header, void *data);
+int CZ_capset(void *header, void *data);
+
+#endif
+
+#endif

Sources/CShim/include/prctl.h

@@ -0,0 +1,33 @@
+/*
+ * Copyright © 2025 Apple Inc. and the Containerization project authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __PRCTL_H
+#define __PRCTL_H
+
+#if defined(__linux__)
+
+#include <sys/types.h>
+
+// Capability management prctl wrappers
+int CZ_prctl_set_keepcaps();
+int CZ_prctl_clear_keepcaps();
+int CZ_prctl_capbset_drop(unsigned int capability);
+int CZ_prctl_cap_ambient_clear_all();
+int CZ_prctl_cap_ambient_raise(unsigned int capability);
+
+#endif
+
+#endif

Sources/CShim/prctl.c

@@ -0,0 +1,47 @@
+/*
+ * Copyright © 2025 Apple Inc. and the Containerization project authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#if defined(__linux__)
+
+#include <sys/prctl.h>
+#include "prctl.h"
+
+// Set keep caps to preserve capabilities across setuid()
+int CZ_prctl_set_keepcaps() {
+    return prctl(PR_SET_KEEPCAPS, 1, 0, 0, 0);
+}
+
+// Clear keep caps after user change
+int CZ_prctl_clear_keepcaps() {
+    return prctl(PR_SET_KEEPCAPS, 0, 0, 0, 0);
+}
+
+// Drop capability from bounding set
+int CZ_prctl_capbset_drop(unsigned int capability) {
+    return prctl(PR_CAPBSET_DROP, capability, 0, 0, 0);
+}
+
+// Clear all ambient capabilities
+int CZ_prctl_cap_ambient_clear_all() {
+    return prctl(PR_CAP_AMBIENT, PR_CAP_AMBIENT_CLEAR_ALL, 0, 0, 0);
+}
+
+// Raise ambient capability
+int CZ_prctl_cap_ambient_raise(unsigned int capability) {
+    return prctl(PR_CAP_AMBIENT, PR_CAP_AMBIENT_RAISE, capability, 0, 0);
+}
+
+#endif

Sources/Containerization/LinuxProcessConfiguration.swift

@@ -17,6 +17,116 @@
 import ContainerizationOCI
 import ContainerizationOS
 
+/// User-friendly Linux capabilities configuration
+public struct LinuxCapabilities: Sendable {
+    /// Capabilities that define the maximum set of capabilities a process can have
+    public var bounding: [CapabilityName] = []
+    /// Capabilities that are actually in effect for the current process
+    public var effective: [CapabilityName] = []
+    /// Capabilities that can be inherited by child processes
+    public var inheritable: [CapabilityName] = []
+    /// Capabilities that are currently permitted for the process
+    public var permitted: [CapabilityName] = []
+    /// Capabilities that are preserved across execve() calls
+    public var ambient: [CapabilityName] = []
+
+    /// Grant all capabilities
+    public static let allCapabilities = LinuxCapabilities(
+        bounding: CapabilityName.allCases,
+        effective: CapabilityName.allCases,
+        inheritable: CapabilityName.allCases,
+        permitted: CapabilityName.allCases,
+        ambient: CapabilityName.allCases
+    )
+
+    /// Default configuration
+    public static let defaultOCICapabilities = LinuxCapabilities(
+        bounding: [
+            .chown,
+            .dacOverride,
+            .fsetid,
+            .fowner,
+            .mknod,
+            .netRaw,
+            .setgid,
+            .setuid,
+            .setfcap,
+            .setpcap,
+            .netBindService,
+            .sysChroot,
+            .kill,
+            .auditWrite,
+        ],
+        effective: [
+            .chown,
+            .dacOverride,
+            .fsetid,
+            .fowner,
+            .mknod,
+            .netRaw,
+            .setgid,
+            .setuid,
+            .setfcap,
+            .setpcap,
+            .netBindService,
+            .sysChroot,
+            .kill,
+            .auditWrite,
+        ],
+        permitted: [
+            .chown,
+            .dacOverride,
+            .fsetid,
+            .fowner,
+            .mknod,
+            .netRaw,
+            .setgid,
+            .setuid,
+            .setfcap,
+            .setpcap,
+            .netBindService,
+            .sysChroot,
+            .kill,
+            .auditWrite,
+        ],
+    )
+
+    public init(
+        bounding: [CapabilityName] = [],
+        effective: [CapabilityName] = [],
+        inheritable: [CapabilityName] = [],
+        permitted: [CapabilityName] = [],
+        ambient: [CapabilityName] = []
+    ) {
+        self.bounding = bounding
+        self.effective = effective
+        self.inheritable = inheritable
+        self.permitted = permitted
+        self.ambient = ambient
+    }
+
+    /// Convenience initializer that sets the same capabilities to effective, permitted, and bounding sets
+    /// This matches the typical pattern used by containerd/runc
+    public init(capabilities: [CapabilityName]) {
+        self.bounding = capabilities
+        self.effective = capabilities
+        self.inheritable = []
+        self.permitted = capabilities
+        self.ambient = []
+    }
+
+    /// Convert to OCI format for transport
+    public func toOCI() -> ContainerizationOCI.LinuxCapabilities {
+        ContainerizationOCI.LinuxCapabilities(
+            bounding: bounding.isEmpty ? nil : bounding.map { $0.description },
+            effective: effective.isEmpty ? nil : effective.map { $0.description },
+            inheritable: inheritable.isEmpty ? nil : inheritable.map { $0.description },
+            permitted: permitted.isEmpty ? nil : permitted.map { $0.description },
+            ambient: ambient.isEmpty ? nil : ambient.map { $0.description }
+        )
+    }
+}
+
 public struct LinuxProcessConfiguration: Sendable {
     /// The default PATH value for a process.
     public static let defaultPath = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
@@ -31,6 +141,8 @@ public struct LinuxProcessConfiguration: Sendable {
     public var user: ContainerizationOCI.User = .init()
     /// The rlimits for the container process.
     public var rlimits: [POSIXRlimit] = []
+    /// The Linux capabilities for the container process.
+    public var capabilities: LinuxCapabilities = .allCapabilities
     /// Whether to allocate a pseudo terminal for the process. If you'd like interactive
     /// behavior and are planning to use a terminal for stdin/out/err on the client side,
     /// this should likely be set to true.
@@ -50,6 +162,7 @@ public struct LinuxProcessConfiguration: Sendable {
         workingDirectory: String = "/",
         user: ContainerizationOCI.User = .init(),
         rlimits: [POSIXRlimit] = [],
+        capabilities: LinuxCapabilities = .allCapabilities,
         terminal: Bool = false,
         stdin: ReaderStream? = nil,
         stdout: Writer? = nil,
@@ -60,6 +173,7 @@ public struct LinuxProcessConfiguration: Sendable {
         self.workingDirectory = workingDirectory
         self.user = user
         self.rlimits = rlimits
+        self.capabilities = capabilities
         self.terminal = terminal
         self.stdin = stdin
         self.stdout = stdout
@@ -92,6 +206,7 @@ public struct LinuxProcessConfiguration: Sendable {
             args: self.arguments,
             cwd: self.workingDirectory,
             env: self.environmentVariables,
+            capabilities: self.capabilities.toOCI(),
             user: self.user,
             rlimits: self.rlimits,
             terminal: self.terminal

Sources/ContainerizationOCI/Spec.swift

@@ -157,6 +157,7 @@ public struct Process: Codable, Sendable {
         }()
         self.init(args: args, cwd: cwd, env: env, user: user)
     }
+
     public init(from decoder: Decoder) throws {
         self.init()
 
@@ -194,25 +195,51 @@ public struct Process: Codable, Sendable {
 }
 
 public struct LinuxCapabilities: Codable, Sendable {
-    public var bounding: [String]
-    public var effective: [String]
-    public var inheritable: [String]
-    public var permitted: [String]
-    public var ambient: [String]
+    public var bounding: [String]?
+    public var effective: [String]?
+    public var inheritable: [String]?
+    public var permitted: [String]?
+    public var ambient: [String]?
+
+    enum CodingKeys: String, CodingKey {
+        case bounding
+        case effective
+        case inheritable
+        case permitted
+        case ambient
+    }
 
     public init(
-        bounding: [String],
-        effective: [String],
-        inheritable: [String],
-        permitted: [String],
-        ambient: [String]
+        bounding: [String]? = nil,
+        effective: [String]? = nil,
+        inheritable: [String]? = nil,
+        permitted: [String]? = nil,
+        ambient: [String]? = nil
     ) {
         self.bounding = bounding
         self.effective = effective
         self.inheritable = inheritable
         self.permitted = permitted
         self.ambient = ambient
     }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        self.bounding = try container.decodeIfPresent([String].self, forKey: .bounding)
+        self.effective = try container.decodeIfPresent([String].self, forKey: .effective)
+        self.inheritable = try container.decodeIfPresent([String].self, forKey: .inheritable)
+        self.permitted = try container.decodeIfPresent([String].self, forKey: .permitted)
+        self.ambient = try container.decodeIfPresent([String].self, forKey: .ambient)
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encodeIfPresent(bounding, forKey: .bounding)
+        try container.encodeIfPresent(effective, forKey: .effective)
+        try container.encodeIfPresent(inheritable, forKey: .inheritable)
+        try container.encodeIfPresent(permitted, forKey: .permitted)
+        try container.encodeIfPresent(ambient, forKey: .ambient)
+    }
 }
 
 public struct Box: Codable, Sendable {