hammerkit 1.27.0-next.22 → 1.27.0-next.24

package/build.schema.json

@@ -311,6 +311,56 @@
                   "volumeSize": {
                     "type": "string",
                     "description": "size of its claim on Kubernetes, e.g. 10Gi"
+                  },
+                  "capAdd": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "AUDIT_CONTROL",
+                        "AUDIT_READ",
+                        "AUDIT_WRITE",
+                        "BLOCK_SUSPEND",
+                        "BPF",
+                        "CHECKPOINT_RESTORE",
+                        "CHOWN",
+                        "DAC_OVERRIDE",
+                        "DAC_READ_SEARCH",
+                        "FOWNER",
+                        "FSETID",
+                        "IPC_LOCK",
+                        "IPC_OWNER",
+                        "KILL",
+                        "LEASE",
+                        "LINUX_IMMUTABLE",
+                        "MAC_ADMIN",
+                        "MAC_OVERRIDE",
+                        "MKNOD",
+                        "NET_ADMIN",
+                        "NET_BIND_SERVICE",
+                        "NET_BROADCAST",
+                        "NET_RAW",
+                        "PERFMON",
+                        "SETFCAP",
+                        "SETGID",
+                        "SETPCAP",
+                        "SETUID",
+                        "SYS_ADMIN",
+                        "SYS_BOOT",
+                        "SYS_CHROOT",
+                        "SYS_MODULE",
+                        "SYS_NICE",
+                        "SYS_PACCT",
+                        "SYS_PTRACE",
+                        "SYS_RAWIO",
+                        "SYS_RESOURCE",
+                        "SYS_TIME",
+                        "SYS_TTY_CONFIG",
+                        "SYSLOG",
+                        "WAKE_ALARM"
+                      ]
+                    },
+                    "description": "Linux capabilities added to the container, e.g. [SYS_ADMIN]"
                   }
                 },
                 "required": [

package/dist/cache/backends/local-cache-backend.js

@@ -80,6 +80,12 @@ function createLocalCacheBackend(spec) {
                 return false;
             }
         },
+        async touch(taskId, stateKey, environment) {
+            const remoteDir = (0, path_1.join)(root, taskId, stateKey);
+            if (await environment.file.exists((0, path_1.join)(remoteDir, 'stats.json'))) {
+                await (0, promises_1.writeFile)((0, path_1.join)(remoteDir, LAST_ACCESS_FILE), `${Date.now()}`);
+            }
+        },
         async push(taskId, stateKey, from, environment) {
             const remoteDir = (0, path_1.join)(root, taskId, stateKey);
             await environment.file.createDirectory(remoteDir);

package/dist/cli.js

@@ -81,6 +81,7 @@ class Cli {
                         timeout: options?.timeout ?? null,
                         maxTimeout: options?.maxTimeout ?? null,
                         skipDeps: options?.skipDeps ?? true,
+                        restore: options?.restore ?? true,
                         wait: options?.wait ?? 'ready',
                         resourceCheck: options?.resourceCheck ?? true,
                         network: options?.network ?? null,

package/dist/executer/deferred-restore.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restoreDeferred = exports.clearDeferredRestore = exports.deferRestore = void 0;
+const abort_1 = require("./abort");
+// Keyed by the item's state, which every run replaces (resetWorkTree): a hit
+// deferred in one run of a Cli is never restored in a later one, over outputs
+// that run built.
+const deferred = new WeakMap();
+function deferRestore(item, run) {
+    deferred.set(item.state, { run, promise: null });
+}
+exports.deferRestore = deferRestore;
+// Every cache check starts from scratch: a key that changed since a hit was
+// deferred must not restore the old entry.
+function clearDeferredRestore(item) {
+    deferred.delete(item.state);
+}
+exports.clearDeferredRestore = clearDeferredRestore;
+// Restore every given item that was a hit without its outputs, in parallel,
+// each at most once however many items wait on it.
+async function restoreDeferred(work, items, abort) {
+    await Promise.all(items.map((item) => {
+        const entry = deferred.get(item.state);
+        if (!entry) {
+            return Promise.resolve();
+        }
+        if (!entry.promise) {
+            work.status.write('debug', `restore ${item.name} from cache, ${work.name} needs its outputs`);
+            entry.promise = entry.run();
+        }
+        return entry.promise;
+    }));
+    (0, abort_1.checkForAbort)(abort);
+}
+exports.restoreDeferred = restoreDeferred;
+//# sourceMappingURL=deferred-restore.js.map

package/dist/executer/docker-task.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dockerTask = exports.buildCreateOptions = void 0;
+exports.dockerTask = exports.getCapabilityHostConfig = exports.buildCreateOptions = void 0;
 const run_labels_1 = require("../docker/run-labels");
 const execute_docker_1 = require("./execute-docker");
 const abort_1 = require("./abort");
@@ -47,10 +47,30 @@ function buildCreateOptions(item, stateKey, network, environment, secrets, resou
             ...(0, item_network_1.getNetworkHostConfig)(network),
             AutoRemove: true,
             ...resources,
+            ...getCapabilityHostConfig(item, environment),
         },
     };
 }
 exports.buildCreateOptions = buildCreateOptions;
+/**
+ * The capabilities a task adds (`capAdd`). On a server they are only granted in the
+ * sandboxed runtime of `backend.capabilities`, never by the kernel of the docker host.
+ */
+function getCapabilityHostConfig(item, environment) {
+    const capAdd = item.data.capAdd;
+    if (capAdd.length === 0) {
+        return {};
+    }
+    if (!environment.hosted) {
+        return { CapAdd: capAdd };
+    }
+    const runtime = environment.hosted.capabilityRuntime;
+    if (!runtime) {
+        throw new Error(`${item.name}: adds the capabilities ${capAdd.join(', ')}, which this server grants in no sandboxed runtime`);
+    }
+    return { CapAdd: capAdd, Runtime: runtime };
+}
+exports.getCapabilityHostConfig = getCapabilityHostConfig;
 async function dockerTask(docker, item, environment, options) {
     item.status.write('info', `execute ${item.name} in container`);
     let network = null;

package/dist/executer/execute-work-service.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeWorkService = exports.stopService = void 0;
 const work_item_1 = require("../planner/work-item");
 const await_completed_dependencies_1 = require("./await-completed-dependencies");
+const deferred_restore_1 = require("./deferred-restore");
 const abort_1 = require("./abort");
 const log_1 = require("../log");
 const watch_loop_1 = require("./watch-loop");
@@ -35,6 +36,7 @@ async function executeWorkService(work, environment, options) {
         });
         await (0, watch_loop_1.watchLoop)(work, environment, options, async (cacheState, abort, stop) => {
             await (0, await_completed_dependencies_1.awaitCompletedDependencies)(work, work.deps, abort);
+            await (0, deferred_restore_1.restoreDeferred)(work, (0, await_completed_dependencies_1.transitiveDeps)(work.deps), abort);
             work.state.set({
                 type: 'ready',
                 stateKey: cacheState.stateKey,

package/dist/executer/execute-work-task.js

@@ -11,6 +11,7 @@ const deadline_1 = require("./deadline");
 const explain_1 = require("../cache/explain");
 const archive_task_entry_1 = require("./archive-task-entry");
 const units_1 = require("../utils/units");
+const deferred_restore_1 = require("./deferred-restore");
 async function pushToBackend(work, environment, cacheState, options) {
     const { resolved, stateKey, provable } = cacheState;
     // an aggregate has nothing to store, see checkCacheState
@@ -89,6 +90,10 @@ dependents = null) {
                 }
             }
             await (0, await_completed_dependencies_1.awaitCompletedDependencies)(work, work.deps, abort);
+            // an aggregate runs nothing, so it needs no outputs on disk
+            if (!(0, work_task_1.isAggregateTask)(work.data)) {
+                await (0, deferred_restore_1.restoreDeferred)(work, (0, await_completed_dependencies_1.transitiveDeps)(work.deps), abort);
+            }
             await (0, await_completed_dependencies_1.awaitRunningNeeds)(work, work.needs.map((n) => n.service), abort);
             await options.processManager.task(work, async () => {
                 work.state.set({

package/dist/executer/scheduler/enqueue-next.js

@@ -9,13 +9,17 @@ const work_task_cache_description_1 = require("../../optimizer/work-task-cache-d
 const log_1 = require("../../log");
 const state_key_1 = require("./state-key");
 const work_instance_id_1 = require("../../planner/work-instance-id");
+const deferred_restore_1 = require("../deferred-restore");
 // The key a task whose cache is off runs and records its outputs under. It is
 // no hash, so a later run with its cache on never takes those outputs as its own.
 exports.UNCACHED_STATE_KEY = 'uncached';
 async function checkCacheState(item, defaultCacheMethod, environment, 
 // watch mode compares keys to rerun on a change, so it needs one even when
 // the cache is off
+// restore: false only looks a backend hit up, its outputs are downloaded once
+// something that runs depends on them (`run --no-restore`, see deferred-restore)
 options = {}) {
+    (0, deferred_restore_1.clearDeferredRestore)(item);
     // A task whose cache is off is never looked up, so hashing its sources buys
     // nothing, and a `**` over a node_modules takes most of a minute (every run
     // with arguments). Its dependents still hash its sources for their own key.
@@ -47,13 +51,30 @@ options = {}) {
         if (runtimeStateKey === stateKey) {
             return { cached: true, stateKey, resolved, provable };
         }
+        if (options.restore === false && options.watch) {
+            item.status.write('debug', `${item.name} restores cache hits, --no-restore has no effect in watch mode`);
+        }
+        if (options.restore === false && !options.watch) {
+            try {
+                if (await resolved.backend.has(item.id(), stateKey, environment)) {
+                    item.status.write('info', `${item.name} found in cache "${resolved.name}" (${resolved.backend.type}), not restored`);
+                    await touchEntry(item, resolved, stateKey, environment);
+                    (0, deferred_restore_1.deferRestore)(item, async () => {
+                        if (!(await restoreFromBackend(item, resolved, stateKey, currentStats, environment))) {
+                            throw new Error(`${item.name} is no longer in cache "${resolved.name}", its outputs can not be restored. ` +
+                                'Run again without --no-restore.');
+                        }
+                    });
+                    return { cached: true, stateKey, resolved, provable };
+                }
+            }
+            catch (e) {
+                item.status.write('warn', `${item.name} failed to look up cache "${resolved.name}": ${(0, log_1.getErrorMessage)(e)} — continuing with local execution`);
+            }
+            return { cached: false, stateKey, resolved, provable };
+        }
         try {
-            const cacheDir = (0, get_cache_directory_1.getCacheDirectory)((0, work_instance_id_1.getWorkInstanceId)(item));
-            const pulled = await resolved.backend.pull(item.id(), stateKey, cacheDir, environment);
-            if (pulled) {
-                item.status.write('info', `${item.name} pulled from cache "${resolved.name}" (${resolved.backend.type})`);
-                await item.runtime.restore(environment, cacheDir, stateKey);
-                await (0, cache_metadata_1.writeCacheMetadata)(environment, item, currentStats, (0, work_task_cache_description_1.getWorkTaskCacheDescription)(item));
+            if (await restoreFromBackend(item, resolved, stateKey, currentStats, environment)) {
                 return { cached: true, stateKey, resolved, provable };
             }
         }
@@ -64,4 +85,27 @@ options = {}) {
     return { cached: false, stateKey, resolved, provable };
 }
 exports.checkCacheState = checkCacheState;
+// Pull a task's entry and restore its outputs into the checkout. False when the
+// backend has no such entry.
+async function restoreFromBackend(item, resolved, stateKey, currentStats, environment) {
+    const cacheDir = (0, get_cache_directory_1.getCacheDirectory)((0, work_instance_id_1.getWorkInstanceId)(item));
+    const pulled = await resolved.backend.pull(item.id(), stateKey, cacheDir, environment);
+    if (!pulled) {
+        return false;
+    }
+    item.status.write('info', `${item.name} pulled from cache "${resolved.name}" (${resolved.backend.type})`);
+    await item.runtime.restore(environment, cacheDir, stateKey);
+    await (0, cache_metadata_1.writeCacheMetadata)(environment, item, currentStats, (0, work_task_cache_description_1.getWorkTaskCacheDescription)(item));
+    return true;
+}
+// A hit that is only looked up still counts as used, so retention keeps it.
+// Best effort: the hit stands whether or not the marker could be written.
+async function touchEntry(item, resolved, stateKey, environment) {
+    try {
+        await resolved.backend.touch?.(item.id(), stateKey, environment);
+    }
+    catch (e) {
+        item.status.write('debug', `${item.name} could not mark its cache entry as used: ${(0, log_1.getErrorMessage)(e)}`);
+    }
+}
 //# sourceMappingURL=enqueue-next.js.map

package/dist/executer/watch-loop.js

@@ -12,7 +12,10 @@ async function watchLoop(work, environment, options, factory) {
     // kubernetes-service has no such field. Read it wherever it exists.
     const continuous = 'continuous' in work.data ? work.data.continuous : false;
     const watchMode = options.watch && !options.daemon && !continuous;
-    const currentStats = await (0, enqueue_next_1.checkCacheState)(work, options.cacheDefault, environment, { watch: watchMode });
+    const currentStats = await (0, enqueue_next_1.checkCacheState)(work, options.cacheDefault, environment, {
+        watch: watchMode,
+        restore: options.restore,
+    });
     (0, abort_1.checkForAbort)(environment.abortCtrl.signal);
     const watchState = watchMode
         ? (0, watch_state_key_1.watchStateKey)(work, currentStats, environment, options)

package/dist/kubernetes/job-placement.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getContainerSecurity = exports.getRunLabels = exports.getRunLabelValue = exports.RUN_LABEL = exports.getPodPlacement = exports.placeOnPool = exports.getNodeArch = exports.runInToolImage = exports.getLocalTaskPool = void 0;
+exports.getPodRuntimeClass = exports.getContainerSecurity = exports.getRunLabels = exports.getRunLabelValue = exports.RUN_LABEL = exports.getPodPlacement = exports.placeOnPool = exports.getNodeArch = exports.runInToolImage = exports.getLocalTaskPool = void 0;
 const crypto_1 = require("crypto");
 /**
  * The pool a local task runs on: the first that offers its platform. A pool says
@@ -34,6 +34,7 @@ function runInToolImage(task, server, platform) {
         user: null,
         mounts: [],
         volumeSize: null,
+        capAdd: [],
         pool: pool.name,
         arch: getNodeArch(pool),
     };
@@ -82,18 +83,41 @@ exports.getRunLabels = getRunLabels;
 /**
  * What a container of a run may do on a server, where it shares nodes with the pods of
  * other callers: no privilege escalation (setuid binaries such as sudo), no raw sockets
- * (spoofing on a bridge network) and the runtime's seccomp profile.
+ * (spoofing on a bridge network) and the runtime's seccomp profile. The capabilities a
+ * task adds (`capAdd`) come on top, in the sandbox of getPodRuntimeClass on a server.
  */
-function getContainerSecurity(kubernetes) {
-    return kubernetes.server
-        ? {
-            securityContext: {
-                allowPrivilegeEscalation: false,
-                capabilities: { drop: ['NET_RAW'] },
-                seccompProfile: { type: 'RuntimeDefault' },
-            },
-        }
-        : {};
+function getContainerSecurity(kubernetes, capAdd = []) {
+    const add = capAdd.length > 0 ? { add: [...capAdd] } : {};
+    if (!kubernetes.server) {
+        return capAdd.length > 0 ? { securityContext: { capabilities: add } } : {};
+    }
+    const drop = capAdd.includes('NET_RAW') ? {} : { drop: ['NET_RAW'] };
+    return {
+        securityContext: {
+            allowPrivilegeEscalation: false,
+            capabilities: { ...drop, ...add },
+            seccompProfile: { type: 'RuntimeDefault' },
+        },
+    };
 }
 exports.getContainerSecurity = getContainerSecurity;
+/**
+ * The RuntimeClass of the pod of a task that adds capabilities on a server: the sandbox the
+ * operator named (`backend.capabilities.runtimeClass`), so the capabilities hold in its own
+ * kernel and never in the node's. Elsewhere the cluster is the build file's own.
+ */
+function getPodRuntimeClass(task, kubernetes) {
+    if (task.capAdd.length === 0 || !kubernetes.server) {
+        return {};
+    }
+    const sandbox = kubernetes.server.capabilities;
+    if (!sandbox) {
+        throw new Error(`${task.name}: adds the capabilities ${task.capAdd.join(', ')}, which this server grants in no sandboxed runtime`);
+    }
+    if (sandbox.unavailable) {
+        throw new Error(`${task.name}: adds the capabilities ${task.capAdd.join(', ')}, but ${sandbox.unavailable}`);
+    }
+    return { runtimeClassName: sandbox.runtimeClass };
+}
+exports.getPodRuntimeClass = getPodRuntimeClass;
 //# sourceMappingURL=job-placement.js.map

package/dist/kubernetes/sandbox-runner.js

@@ -151,7 +151,9 @@ function canUseRunner(task, kubernetes, persistence) {
         persistence.mounts.some((mount) => (0, path_1.relative)(workspace.root, mount.mount.mountPath) === '') &&
         task.needs.length === 0 &&
         task.data.secrets.length === 0 &&
-        task.data.generates.length === 0);
+        task.data.generates.length === 0 &&
+        // its pod would need the sandboxed runtime of a Job
+        task.data.capAdd.length === 0);
 }
 exports.canUseRunner = canUseRunner;
 // What the runner is made of: the same key for the same pod

package/dist/planner/utils/append-work-task.js

@@ -92,10 +92,12 @@ function parseTask(cwd, task, environment, context) {
         return {
             ...baseWorkNode,
             type: 'container-task',
-            user: (0, get_container_user_1.getContainerUser)(),
+            // a capability holds for root only: a task that adds some runs as its image's user
+            user: task.schema.capAdd?.length ? null : (0, get_container_user_1.getContainerUser)(),
             image: (0, template_value_1.templateValue)(task.schema.image, envs),
             mounts: (0, parse_work_mounts_1.parseWorkMounts)(cwd, task.schema, envs),
             volumeSize: task.schema.volumeSize ?? null,
+            capAdd: task.schema.capAdd ?? [],
         };
     }
     else {

package/dist/planner/work-runtime-kubernetes.js

@@ -130,7 +130,8 @@ exports.describeFailedJob = describeFailedJob;
  * The containers of the Job of a command: the network gate first, nothing runs before the
  * item's policy holds, then the init containers that read its secrets, then the command. The
  * proxy's token (`network.secretEnv`) reaches the init containers through `secretSpec` only:
- * the command's container gets the proxy variables of a limited network without it.
+ * the command's container gets the proxy variables of a limited network without it. A task that
+ * adds capabilities gets them in the sandbox's RuntimeClass only.
  */
 function getTaskJobContainers(options) {
     const { task, cmd, envs, secrets, network, secretSpec, kubernetes } = options;
@@ -155,9 +156,10 @@ function getTaskJobContainers(options) {
                 name: options.container,
                 volumeMounts: [...options.mounts, ...secrets.mounts, ...secretSpec.mounts],
                 ...(0, container_resources_1.getKubernetesResources)(task.data.resources),
-                ...(0, job_placement_1.getContainerSecurity)(kubernetes),
+                ...(0, job_placement_1.getContainerSecurity)(kubernetes, task.data.capAdd),
             },
         ],
+        ...(0, job_placement_1.getPodRuntimeClass)({ name: task.name, capAdd: task.data.capAdd }, kubernetes),
     };
 }
 exports.getTaskJobContainers = getTaskJobContainers;

package/dist/program.js

@@ -705,6 +705,7 @@ async function getProgram(environment, argv) {
             .addOption(new commander_1.Option('--max-timeout <duration>', 'fail any task after this long, also one with a longer timeout of its own (e.g. 2m)').argParser(units_1.parseDuration))
             .addOption(new commander_1.Option('--network <level>', 'the most any task or service reaches besides its needs: none, open or allow:<host>,<host>').argParser(parseNetworkArgument))
             .addOption(new commander_1.Option('--no-skip-deps', 'run dependencies even when nothing needing them has to run'))
+            .addOption(new commander_1.Option('--no-restore', 'only look cache hits up, download their outputs only when a task that runs needs them'))
             .action(async (task, options, command) => {
             try {
                 // For machine-readable JSON, suppress the human progress logger (which
@@ -740,6 +741,7 @@ async function getProgram(environment, argv) {
                     maxTimeout: options.maxTimeout ?? null,
                     network: options.network ?? null,
                     skipDeps: options.skipDeps !== false,
+                    restore: options.restore !== false,
                 });
                 // Reporting only: the summary never changes the exit code or behavior.
                 if (!options.watch) {

package/dist/remote/remote-work-commands.js

@@ -122,6 +122,7 @@ function describePlan(plan) {
         ...(entry.mounts.length > 0 ? [`    mounts: ${entry.mounts.map(server_client_1.printable).join(', ')}`] : []),
         ...(entry.ports.length > 0 ? [`    ports: ${entry.ports.map(server_client_1.printable).join(', ')}`] : []),
         ...(entry.generates.length > 0 ? [`    generates: ${entry.generates.map(server_client_1.printable).join(', ')}`] : []),
+        ...(entry.capAdd?.length ? [`    capAdd: ${entry.capAdd.map(server_client_1.printable).join(', ')}`] : []),
     ]);
 }
 exports.describePlan = describePlan;

package/dist/schema/build-file-container-task-schema.js

@@ -4,12 +4,16 @@ exports.buildFileContainerTaskSchema = void 0;
 const build_file_base_task_schema_1 = require("./build-file-base-task-schema");
 const zod_1 = require("zod");
 const size_schema_1 = require("./size-schema");
+const capabilities_schema_1 = require("./capabilities-schema");
 exports.buildFileContainerTaskSchema = build_file_base_task_schema_1.buildFileBaseTaskSchema
     .extend({
     image: (0, zod_1.string)(),
     mounts: (0, zod_1.array)((0, zod_1.string)()).optional(),
     // on Kubernetes, the size of the claim that holds its sources, mounts and outputs
     volumeSize: size_schema_1.sizeSchema.describe('size of its claim on Kubernetes, e.g. 10Gi').optional(),
+    // Linux capabilities added to the container, such as SYS_ADMIN for a daemonless image
+    // build. A server allows them only in a sandboxed runtime (`backend.capabilities`).
+    capAdd: capabilities_schema_1.capabilitiesSchema.describe('Linux capabilities added to the container, e.g. [SYS_ADMIN]').optional(),
 })
     .strict()
     .describe('container task');

package/dist/schema/capabilities-schema.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capabilitiesSchema = exports.LINUX_CAPABILITIES = void 0;
+const zod_1 = require("zod");
+// The Linux capabilities, without the CAP_ prefix (capabilities(7))
+exports.LINUX_CAPABILITIES = [
+    'AUDIT_CONTROL',
+    'AUDIT_READ',
+    'AUDIT_WRITE',
+    'BLOCK_SUSPEND',
+    'BPF',
+    'CHECKPOINT_RESTORE',
+    'CHOWN',
+    'DAC_OVERRIDE',
+    'DAC_READ_SEARCH',
+    'FOWNER',
+    'FSETID',
+    'IPC_LOCK',
+    'IPC_OWNER',
+    'KILL',
+    'LEASE',
+    'LINUX_IMMUTABLE',
+    'MAC_ADMIN',
+    'MAC_OVERRIDE',
+    'MKNOD',
+    'NET_ADMIN',
+    'NET_BIND_SERVICE',
+    'NET_BROADCAST',
+    'NET_RAW',
+    'PERFMON',
+    'SETFCAP',
+    'SETGID',
+    'SETPCAP',
+    'SETUID',
+    'SYS_ADMIN',
+    'SYS_BOOT',
+    'SYS_CHROOT',
+    'SYS_MODULE',
+    'SYS_NICE',
+    'SYS_PACCT',
+    'SYS_PTRACE',
+    'SYS_RAWIO',
+    'SYS_RESOURCE',
+    'SYS_TIME',
+    'SYS_TTY_CONFIG',
+    'SYSLOG',
+    'WAKE_ALARM',
+];
+// Capabilities a container gets on top of its runtime's default set, by name such as
+// SYS_ADMIN. `ALL` is not one: a task names what it needs.
+exports.capabilitiesSchema = (0, zod_1.array)((0, zod_1.enum)(exports.LINUX_CAPABILITIES, {
+    errorMap: (issue, ctx) => issue.code === 'invalid_enum_value'
+        ? { message: `unknown capability ${JSON.stringify(issue.received)}, expected a name such as SYS_ADMIN` }
+        : { message: ctx.defaultError },
+})).refine((names) => new Set(names).size === names.length, 'a capability is listed twice');
+//# sourceMappingURL=capabilities-schema.js.map

package/dist/server/executor.js

@@ -238,6 +238,7 @@ class HostExecutor {
                         }
                         : {}),
                     ...(placed ? { kubernetes: placed.kubernetes } : {}),
+                    ...(!placed && this.options.capabilityRuntime ? { capabilityRuntime: this.options.capabilityRuntime } : {}),
                 }, cwd, { ...this.processEnvironment(home, cache), ...placed?.env }, context, abortCtrl.signal);
             }
             finally {

package/dist/server/kubernetes-backend.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.awaitRunObjectsGone = exports.removeRunObjects = exports.CallerNamespaces = exports.getVolumeScope = exports.KubernetesExecutor = exports.getRunRoleBinding = exports.removeServiceRunNamespace = exports.getServerIngressPolicy = exports.getNamespacePolicies = exports.getClusterAccess = exports.isCallerNamespace = exports.SERVICE_RUN_LABEL = exports.getServiceRunNamespace = exports.getCallerNamespace = void 0;
+exports.awaitRunObjectsGone = exports.removeRunObjects = exports.CallerNamespaces = exports.getVolumeScope = exports.getPrivilegedNamespaceProblem = exports.getCapabilitiesProblem = exports.getPodSecurityLabels = exports.KubernetesExecutor = exports.getRunRoleBinding = exports.removeServiceRunNamespace = exports.getServerIngressPolicy = exports.getNamespacePolicies = exports.getClusterAccess = exports.isCallerNamespace = exports.SERVICE_RUN_LABEL = exports.getServiceRunNamespace = exports.getCallerNamespace = void 0;
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -368,11 +368,12 @@ class KubernetesExecutor {
                     return { kubernetes: this.environmentOf(run, namespace), env: this.access.env };
                 }
                 const label = (0, job_placement_1.getRunLabelValue)(run.id);
+                let capabilitiesProblem;
                 await this.enqueue(namespace, async () => {
                     if (context.signal.aborted) {
                         throw new Error('the run was cancelled');
                     }
-                    await this.namespaces.prepare(namespace);
+                    capabilitiesProblem = await this.namespaces.prepare(namespace);
                     // what an earlier run left when the server stopped before its end, or when its
                     // release failed: the objects of a run that does not execute. One that starts
                     // after this waits for it here before it makes any.
@@ -394,7 +395,10 @@ class KubernetesExecutor {
                 });
                 this.sweepLeftClaims();
                 context.emit({ type: 'log', task: 'hammerkit', stream: 'stdout', text: `runs in the namespace ${namespace}` });
-                return { kubernetes: this.environmentOf(run, namespace, work), env: this.access.env };
+                return {
+                    kubernetes: this.environmentOf(run, namespace, work, capabilitiesProblem),
+                    env: this.access.env,
+                };
             },
             release: async (run, context) => {
                 const namespace = this.namespaceOf(run);
@@ -462,7 +466,7 @@ class KubernetesExecutor {
         };
     }
     // The cluster as the process of a run sees it: the namespace its tasks and services go in.
-    environmentOf(run, namespace, work) {
+    environmentOf(run, namespace, work, capabilitiesProblem) {
         const backend = this.config.backend;
         return {
             type: 'kubernetes',
@@ -483,6 +487,14 @@ class KubernetesExecutor {
                 ...(work?.claim ? { workspace: getWorkspace(work.root, work.claim, namespace, backend.sandboxes.runner) } : {}),
                 // the claims of a service run go with its namespace
                 ...(this.keep > 0 && !run.up ? { volumeScope: getVolumeScope(run) } : {}),
+                ...(backend.capabilities
+                    ? {
+                        capabilities: {
+                            runtimeClass: backend.capabilities.runtimeClass,
+                            ...(capabilitiesProblem ? { unavailable: capabilitiesProblem } : {}),
+                        },
+                    }
+                    : {}),
             },
         };
     }
@@ -565,6 +577,50 @@ class KubernetesExecutor {
     }
 }
 exports.KubernetesExecutor = KubernetesExecutor;
+const ENFORCE_LABEL = 'pod-security.kubernetes.io/enforce';
+const AUDIT_LABEL = 'pod-security.kubernetes.io/audit';
+/**
+ * The Pod Security level a caller's namespace is made with: `baseline`, no privileged pods,
+ * host paths or host network, whatever a build asks. `baseline` also refuses the capabilities
+ * of `backend.capabilities`, sandboxed or not: with them the namespace enforces `privileged`
+ * and audits `baseline`, and the operator's admission policy (see the docs on capabilities)
+ * refuses what `baseline` would to a pod outside the sandbox's RuntimeClass.
+ */
+function getPodSecurityLabels(backend) {
+    return backend.capabilities
+        ? { [ENFORCE_LABEL]: 'privileged', [AUDIT_LABEL]: 'baseline' }
+        : { [ENFORCE_LABEL]: 'baseline' };
+}
+exports.getPodSecurityLabels = getPodSecurityLabels;
+/**
+ * The server never changes the level of a namespace it made (that would take `patch` on every
+ * namespace of the cluster): one made before `backend.capabilities` is relabelled by the
+ * operator. Until then its tasks that add capabilities fail with this, the others run.
+ */
+function getCapabilitiesProblem(namespace, labels, backend) {
+    const enforce = labels?.[ENFORCE_LABEL];
+    if (!backend.capabilities || enforce === 'privileged') {
+        return undefined;
+    }
+    return (`the namespace ${namespace} was made before backend.capabilities and enforces ` +
+        `${enforce ? `Pod Security ${enforce}` : 'no Pod Security level of its own'}, not privileged: kubectl label namespace ${namespace} ` +
+        `${ENFORCE_LABEL}=privileged ${AUDIT_LABEL}=baseline --overwrite`);
+}
+exports.getCapabilitiesProblem = getCapabilitiesProblem;
+/**
+ * A namespace made while the server had `backend.capabilities` admits privileged pods but for
+ * the operator's admission policy. Without capabilities the server runs nothing in it until the
+ * operator sets it back.
+ */
+function getPrivilegedNamespaceProblem(namespace, labels, backend) {
+    if (backend.capabilities || labels?.[ENFORCE_LABEL] !== 'privileged') {
+        return undefined;
+    }
+    return (`the namespace ${namespace} enforces Pod Security privileged, made while the server had ` +
+        `backend.capabilities, and the server runs nothing in it without them: kubectl label namespace ` +
+        `${namespace} ${ENFORCE_LABEL}=baseline ${AUDIT_LABEL}- --overwrite`);
+}
+exports.getPrivilegedNamespaceProblem = getPrivilegedNamespaceProblem;
 // What may mount a claim a run kept: the runs of the same repository, as they share the
 // cache, and on a sandbox the runs of that sandbox only, whose claim is on the same node or
 // zone as the kept ones. The owner is the namespace's.
@@ -595,7 +651,8 @@ class CallerNamespaces {
     // are admitted under a quota on compute. All of it is replaced when the server sets up
     // a namespace it did not set up in the last `NAMESPACE_SETUP_REUSE_MS` (it reads the
     // config once, at its start), so the namespace follows the config; a namespace made anew
-    // since (deleted and made again) is set up again at once.
+    // since (deleted and made again) is set up again at once. Returns what keeps the tasks that
+    // add capabilities from running in it (getCapabilitiesProblem), if anything.
     async prepare(namespace, 
     // a service run's own namespace: its label, the namespace of the server that reaches its
     // endpoints, and its quota
@@ -613,6 +670,12 @@ class CallerNamespaces {
         if (existing && existing.metadata?.labels?.[MANAGED_LABEL] !== 'true') {
             throw new Error(`the namespace ${namespace} was not made by hammerkit, the server does not run tasks in it`);
         }
+        const privileged = getPrivilegedNamespaceProblem(namespace, existing?.metadata?.labels, backend);
+        if (privileged) {
+            throw new Error(privileged);
+        }
+        // one made by another run of this server at the same time has the labels of its config
+        const problem = () => getCapabilitiesProblem(namespace, existing?.metadata?.labels ?? getPodSecurityLabels(backend), backend);
         const started = Date.now();
         const applied = this.applied.get(namespace);
         if (existing &&
@@ -620,7 +683,7 @@ class CallerNamespaces {
             applied &&
             applied.uid === existing.metadata?.uid &&
             started - applied.at < NAMESPACE_SETUP_REUSE_MS) {
-            return;
+            return problem();
         }
         this.applied.delete(namespace);
         if (!existing) {
@@ -633,8 +696,7 @@ class CallerNamespaces {
                                 [MANAGED_LABEL]: 'true',
                                 'hammerkit.dev/caller': namespace,
                                 ...(serviceRun ? { [exports.SERVICE_RUN_LABEL]: serviceRun.serviceRun } : {}),
-                                // no privileged pods, host paths or host network, whatever a build asks
-                                'pod-security.kubernetes.io/enforce': 'baseline',
+                                ...getPodSecurityLabels(backend),
                             },
                         },
                     },
@@ -703,6 +765,7 @@ class CallerNamespaces {
         if (uid) {
             this.applied.set(namespace, { uid, at: started });
         }
+        return problem();
     }
     whoAmI() {
         if (!this.subject) {

package/dist/server/plan.js

@@ -188,6 +188,18 @@ function findItemPolicyProblems(item, policy, root) {
         problems.push(`${item.name}: runs on the ${runtime} runtime, which this server does not allow (runtimes: ${policy.runtimes.join(', ')})`);
     }
     const data = item.data;
+    // a capability holds in the sandboxed runtime the operator named for it, so only those
+    // the operator allows are added
+    const refused = policy.capabilities
+        ? ('capAdd' in data ? data.capAdd : []).filter((capability) => !policy.capabilities?.includes(capability))
+        : [];
+    if (refused.length > 0) {
+        const from = policy.capabilitiesFrom ?? 'backend.capabilities.allow';
+        problems.push(`${item.name}: adds the ${refused.length > 1 ? 'capabilities' : 'capability'} ${refused.join(', ')}, ` +
+            (policy.capabilities && policy.capabilities.length > 0
+                ? `which this server does not allow (${from}: ${policy.capabilities.join(', ')})`
+                : `and this server allows none (${from})`));
+    }
     // what a task reads and writes is the bundle's: `src: ../..` would have the server
     // copy its own files (its credentials, other callers' caches) into the task
     for (const source of 'src' in data ? data.src : []) {
@@ -303,6 +315,10 @@ function toPlan(root, item) {
     if (data.scope.remote) {
         flags.push('remote-include');
     }
+    const capAdd = (0, work_task_1.isContainerWorkTask)(data) ? data.capAdd : [];
+    if (capAdd.length > 0) {
+        flags.push('capabilities');
+    }
     const isTask = data.type === 'local-task' || data.type === 'container-task';
     return {
         kind: isTask ? 'task' : 'service',
@@ -321,6 +337,7 @@ function toPlan(root, item) {
         mounts,
         ports,
         generates: 'generates' in data ? data.generates.map((generate) => generate.path) : [],
+        ...(capAdd.length > 0 ? { capAdd: [...capAdd] } : {}),
         flags,
     };
 }

package/dist/server/run-worker.js

@@ -51,6 +51,9 @@ exports.workerInputSchema = zod_1.z
     kubernetes: zod_1.z
         .custom((value) => typeof value === 'object' && value !== null && value.type === 'kubernetes')
         .optional(),
+    // on the server's docker host, the runtime a container that adds capabilities runs in
+    // (`backend.capabilities.runtime`)
+    capabilityRuntime: zod_1.z.string().min(1).optional(),
     // the most any task or service reaches besides its needs, as `--network`: `runs.network`
     network: network_schema_1.networkSchema.optional(),
     // for a run on a sandbox, `sandboxes.network`: the run gets the lower of the two
@@ -153,7 +156,12 @@ up) {
     // is what is streamed: it is redacted with the secrets of this run
     const environment = {
         processEnvs,
-        hosted: { catalog: input.catalog, accounts: input.accounts, kubernetes: input.kubernetes },
+        hosted: {
+            catalog: input.catalog,
+            accounts: input.accounts,
+            kubernetes: input.kubernetes,
+            capabilityRuntime: input.capabilityRuntime,
+        },
         abortCtrl,
         cwd: work,
         file: (0, get_file_context_1.getFileContext)(work),

package/dist/server/server-config.js

@@ -8,6 +8,7 @@ const log_1 = require("../log");
 const units_1 = require("../utils/units");
 const version_1 = require("../version");
 const network_schema_1 = require("../schema/network-schema");
+const capabilities_schema_1 = require("../schema/capabilities-schema");
 const build_file_secret_provider_schema_1 = require("../schema/build-file-secret-provider-schema");
 const repo_1 = require("./repo");
 const work_network_1 = require("../planner/work-network");
@@ -117,12 +118,24 @@ exports.accountSchema = zod_1.z
         });
     }
 });
+// The capabilities (`capAdd`) a task of a run may add, and the sandboxed runtime its
+// container then runs in, so they hold in the sandbox's own kernel and never in the host's
+const capabilitiesAllowSchema = zod_1.z
+    .array(zod_1.z.enum(capabilities_schema_1.LINUX_CAPABILITIES))
+    .min(1)
+    .refine((names) => new Set(names).size === names.length, 'a capability is listed twice');
 // The tasks of runs execute on this machine, with its docker daemon and local tools.
 const hostBackendSchema = zod_1.z
     .object({
     type: zod_1.z.literal('host'),
     // what this machine offers; detected when left out
     platform: exports.serverPlatformSchema.optional(),
+    // `runtime` is a runtime of the docker daemon (`runtimes` in its daemon.json), such as
+    // runsc of gVisor
+    capabilities: zod_1.z
+        .object({ allow: capabilitiesAllowSchema, runtime: zod_1.z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*$/) })
+        .strict()
+        .optional(),
 })
     .strict();
 const tolerationSchema = zod_1.z
@@ -282,6 +295,9 @@ const kubernetesBackendSchema = zod_1.z
     // build file's environment does: hammerkit can't tell from the API, and without it a
     // task with a limited network fails rather than runs open
     networkPolicy: zod_1.z.literal('enforced').optional(),
+    // `runtimeClass` is a RuntimeClass of a sandbox, such as gvisor; the pods of tasks that
+    // add capabilities run in it
+    capabilities: zod_1.z.object({ allow: capabilitiesAllowSchema, runtimeClass: kubernetesNameSchema }).strict().optional(),
 })
     .strict();
 // the most a task's claim may request on a server whose operator states no maxVolumeSize
@@ -546,6 +562,9 @@ exports.serverConfigSchema = zod_1.z
             .object({ allow: zod_1.z.array(zod_1.z.string().regex(/^[A-Za-z_][A-Za-z0-9_()]*$/)).default([]) })
             .strict()
             .default({}),
+        // the capabilities of `backend.capabilities.allow` a task of a run on a sandbox may
+        // add: none by default, a sandbox holds code nobody reviewed
+        capabilities: zod_1.z.array(zod_1.z.enum(capabilities_schema_1.LINUX_CAPABILITIES)).default([]),
         // what one caller may keep; a sandbox over it can't be created
         limits: zod_1.z
             .object({
@@ -677,6 +696,16 @@ exports.serverConfigSchema = zod_1.z
             }
         }
     });
+    const allowed = config.backend.capabilities?.allow ?? [];
+    config.sandboxes.capabilities.forEach((capability, index) => {
+        if (!allowed.includes(capability)) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: ['sandboxes', 'capabilities', index],
+                message: `the capability ${capability} is not in backend.capabilities.allow, no run may add it`,
+            });
+        }
+    });
     const sandboxNetwork = (0, work_network_1.parseWorkNetwork)(config.sandboxes.network);
     const runsNetwork = (0, work_network_1.parseWorkNetwork)(config.runs.network);
     if ((0, work_network_1.exceedsNetwork)(sandboxNetwork, runsNetwork)) {

package/dist/server/server.js

@@ -617,6 +617,7 @@ async function startServer(config, environment, options = {}) {
             network: (0, work_network_1.parseWorkNetwork)(config.runs.network),
             secretNetwork: (0, work_network_1.parseWorkNetwork)(config.runs.secretNetwork),
             args: config.runs.args,
+            capabilities: config.backend.capabilities?.allow ?? [],
             proxiedProviders: config.backend.type === 'kubernetes'
                 ? Object.entries(config.backend.providers)
                     .filter(([, provider]) => provider.allow)
@@ -657,6 +658,8 @@ async function startServer(config, environment, options = {}) {
             envs: config.sandboxes.env.allow,
             envsFrom: 'sandboxes.env.allow',
             runtimes: sandboxRuntimes,
+            capabilities: config.sandboxes.capabilities,
+            capabilitiesFrom: 'sandboxes.capabilities',
         },
     };
     if (sandboxRuntimes.length === 0 && config.entitlements.some((entitlement) => entitlement.sandboxes?.length)) {
@@ -676,6 +679,9 @@ async function startServer(config, environment, options = {}) {
         cache: (0, path_1.join)(storage, 'cache'),
         worker: options.worker,
         sandboxes: { ...sandboxes, network: config.sandboxes.network },
+        ...(config.backend.type === 'host' && config.backend.capabilities
+            ? { capabilityRuntime: config.backend.capabilities.runtime }
+            : {}),
         log,
     };
     const backend = config.backend;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hammerkit",
   "description": "Containerized build tool with incremental caching that runs the same build file locally, in Docker and on Kubernetes.",
-  "version": "1.27.0-next.22",
+  "version": "1.27.0-next.24",
   "keywords": [
     "build",
     "build-tool",