@mastra/docker 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @mastra/docker
 
+## 0.2.0
+
+### Minor Changes
+
+- Docker sandbox containers now support resource limits and security hardening through Docker HostConfig options. Configure memory, CPU quota, process IDs, capabilities, security options, read-only root filesystems, and tmpfs mounts. ([#16577](https://github.com/mastra-ai/mastra/pull/16577))
+
+  ```typescript
+  const sandbox = new DockerSandbox({
+    memory: 512 * 1024 * 1024,
+    memorySwap: 512 * 1024 * 1024,
+    cpuQuota: 100_000,
+    pidsLimit: 256,
+    readonlyRootfs: true,
+    capDrop: ['ALL'],
+    securityOpt: ['no-new-privileges:true'],
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`20787de`](https://github.com/mastra-ai/mastra/commit/20787de5965234a1af28fe35f49437c537dbfa0d), [`784ad98`](https://github.com/mastra-ai/mastra/commit/784ad989549de91dc5d33ab8ef36caa6f7dcd34e), [`fceae1f`](https://github.com/mastra-ai/mastra/commit/fceae1f5f5db4722cb078a663c6eb4bd22944123), [`090a647`](https://github.com/mastra-ai/mastra/commit/090a647ba5a66d36f203f9f49457e03a1ff4e6fb), [`bf02acb`](https://github.com/mastra-ai/mastra/commit/bf02acbb8a6110f638ac844e89f1ebf04cb7fe74), [`090a647`](https://github.com/mastra-ai/mastra/commit/090a647ba5a66d36f203f9f49457e03a1ff4e6fb), [`bdb4cbf`](https://github.com/mastra-ai/mastra/commit/bdb4cbf8ba4b685d7481f28bb9dc3de6c79c9ed2), [`0fd3fbe`](https://github.com/mastra-ai/mastra/commit/0fd3fbe40fb63657aedd72f6e7b38c8e8ee6940d), [`f84447d`](https://github.com/mastra-ai/mastra/commit/f84447d6c80f3471836a9b300d246b331fb47e0d), [`a1a5b3e`](https://github.com/mastra-ai/mastra/commit/a1a5b3e42ab2ca5161ea21db59ebf28442680fa7), [`af84f57`](https://github.com/mastra-ai/mastra/commit/af84f571ed762e92e8e61c5f9a72363520914274), [`8b3c6f9`](https://github.com/mastra-ai/mastra/commit/8b3c6f90f7879833ba7d1bc70937e1d8f69d0804), [`fed0475`](https://github.com/mastra-ai/mastra/commit/fed0475ccfea31e4fc251469ac05640d0742c1f0), [`0d53730`](https://github.com/mastra-ai/mastra/commit/0d53730c1ed87ef80c87caa5701c4170ea8028e6), [`522f44d`](https://github.com/mastra-ai/mastra/commit/522f44d947214bfc06cff50599bae1ef3494880d)]:
+  - @mastra/core@1.34.0
+
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- Docker sandbox containers now support resource limits and security hardening through Docker HostConfig options. Configure memory, CPU quota, process IDs, capabilities, security options, read-only root filesystems, and tmpfs mounts. ([#16577](https://github.com/mastra-ai/mastra/pull/16577))
+
+  ```typescript
+  const sandbox = new DockerSandbox({
+    memory: 512 * 1024 * 1024,
+    memorySwap: 512 * 1024 * 1024,
+    cpuQuota: 100_000,
+    pidsLimit: 256,
+    readonlyRootfs: true,
+    capDrop: ['ALL'],
+    securityOpt: ['no-new-privileges:true'],
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`fceae1f`](https://github.com/mastra-ai/mastra/commit/fceae1f5f5db4722cb078a663c6eb4bd22944123), [`bf02acb`](https://github.com/mastra-ai/mastra/commit/bf02acbb8a6110f638ac844e89f1ebf04cb7fe74), [`0fd3fbe`](https://github.com/mastra-ai/mastra/commit/0fd3fbe40fb63657aedd72f6e7b38c8e8ee6940d), [`fed0475`](https://github.com/mastra-ai/mastra/commit/fed0475ccfea31e4fc251469ac05640d0742c1f0), [`522f44d`](https://github.com/mastra-ai/mastra/commit/522f44d947214bfc06cff50599bae1ef3494880d)]:
+  - @mastra/core@1.34.0-alpha.1
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var util = require('util');
 var workspace = require('@mastra/core/workspace');
 var Docker = require('dockerode');
 
@@ -275,6 +276,19 @@ var DockerSandbox = class extends workspace.MastraSandbox {
   _volumes;
   _network;
   _privileged;
+  _privilegedWasSet;
+  _memory;
+  _memorySwap;
+  _cpuShares;
+  _cpuQuota;
+  _cpuPeriod;
+  _pidsLimit;
+  _readonlyRootfs;
+  _capDrop;
+  _capAdd;
+  _securityOpt;
+  _ulimits;
+  _tmpfs;
   _workingDir;
   _labels;
   _instructionsOverride;
@@ -295,6 +309,19 @@ var DockerSandbox = class extends workspace.MastraSandbox {
     this._volumes = options.volumes ?? {};
     this._network = options.network;
     this._privileged = options.privileged ?? false;
+    this._privilegedWasSet = options.privileged !== void 0;
+    this._memory = options.memory;
+    this._memorySwap = options.memorySwap;
+    this._cpuShares = options.cpuShares;
+    this._cpuQuota = options.cpuQuota;
+    this._cpuPeriod = options.cpuPeriod;
+    this._pidsLimit = options.pidsLimit;
+    this._readonlyRootfs = options.readonlyRootfs;
+    this._capDrop = options.capDrop;
+    this._capAdd = options.capAdd;
+    this._securityOpt = options.securityOpt;
+    this._ulimits = options.ulimits;
+    this._tmpfs = options.tmpfs;
     this._workingDir = options.workingDir ?? "/workspace";
     this._labels = {
       ...options.labels,
@@ -324,6 +351,8 @@ var DockerSandbox = class extends workspace.MastraSandbox {
       this.logger.debug(`${LOG_PREFIX} Found existing container ${existing.Id}`);
       this._container = this._docker.getContainer(existing.Id);
       const info = await this._container.inspect();
+      this._warnOnPrivilegedHardeningConflict(info.HostConfig?.Privileged ?? this._privileged);
+      this._warnOnReconnectedHostConfigMismatch(existing.Id, info.HostConfig);
       const actualState = info.State?.Running ? "running" : "stopped";
       if (actualState !== "running") {
         this.logger.debug(`${LOG_PREFIX} Container exists but not running (${actualState}), starting...`);
@@ -333,6 +362,7 @@ var DockerSandbox = class extends workspace.MastraSandbox {
       this.logger.debug(`${LOG_PREFIX} Reconnected to container ${existing.Id}`);
       return;
     }
+    this._warnOnPrivilegedHardeningConflict(this._privileged);
     await this._ensureImage();
     const envArray = Object.entries(this._env).map(([k, v]) => `${k}=${v}`);
     const binds = Object.entries(this._volumes).map(([host, container]) => `${host}:${container}`);
@@ -346,7 +376,19 @@ var DockerSandbox = class extends workspace.MastraSandbox {
       HostConfig: {
         Binds: binds.length > 0 ? binds : void 0,
         NetworkMode: this._network,
-        Privileged: this._privileged
+        Privileged: this._privileged,
+        Memory: this._memory,
+        MemorySwap: this._memorySwap,
+        CpuShares: this._cpuShares,
+        CpuQuota: this._cpuQuota,
+        CpuPeriod: this._cpuPeriod,
+        PidsLimit: this._pidsLimit,
+        ReadonlyRootfs: this._readonlyRootfs,
+        CapDrop: this._capDrop,
+        CapAdd: this._capAdd,
+        SecurityOpt: this._securityOpt,
+        Ulimits: this._ulimits?.map(toDockerUlimit),
+        Tmpfs: this._tmpfs
       },
       // Keep stdin open for interactive use
       OpenStdin: true,
@@ -356,6 +398,64 @@ var DockerSandbox = class extends workspace.MastraSandbox {
     this.processes.setContainer(this._container);
     this.logger.debug(`${LOG_PREFIX} Container started: ${this._container.id}`);
   }
+  _warnOnPrivilegedHardeningConflict(effectivePrivileged) {
+    if (!effectivePrivileged) return;
+    const conflictedHostConfigFields = [
+      this._capDrop && this._capDrop.length > 0 ? "CapDrop" : void 0,
+      this._capAdd && this._capAdd.length > 0 ? "CapAdd" : void 0,
+      this._securityOpt && this._securityOpt.length > 0 ? "SecurityOpt" : void 0
+    ].filter((field) => field !== void 0);
+    if (conflictedHostConfigFields.length === 0) return;
+    const optionNames = conflictedHostConfigFields.map(toDockerSandboxOptionName);
+    this.logger.warn(
+      `${LOG_PREFIX} Privileged containers can bypass some requested hardening controls: ${optionNames.join(", ")}`,
+      { fields: optionNames, hostConfigFields: conflictedHostConfigFields }
+    );
+  }
+  _warnOnReconnectedHostConfigMismatch(containerId, hostConfig) {
+    if (!hostConfig) return;
+    const mismatchedHostConfigFields = this._requestedHardeningHostConfigEntries(hostConfig).filter(([field, requestedValue]) => !isHostConfigValueEqual(field, hostConfig[field], requestedValue)).map(([field]) => field);
+    if (mismatchedHostConfigFields.length === 0) return;
+    if (!this._privilegedWasSet && hostConfig.Privileged === true && mismatchedHostConfigFields.includes("Privileged")) {
+      this.logger.warn(
+        `${LOG_PREFIX} Reconnected to existing container ${containerId}; the existing container is privileged, but this DockerSandbox did not request privileged mode. Destroy and recreate the sandbox to apply the default non-privileged mode.`,
+        { containerId, fields: ["privileged"], hostConfigFields: ["Privileged"] }
+      );
+    }
+    const remainingMismatchedHostConfigFields = mismatchedHostConfigFields.filter(
+      (field) => field !== "Privileged" || this._privilegedWasSet
+    );
+    if (remainingMismatchedHostConfigFields.length === 0) return;
+    const mismatchedOptions = remainingMismatchedHostConfigFields.map(toDockerSandboxOptionName);
+    this.logger.warn(
+      `${LOG_PREFIX} Reconnected to existing container ${containerId}; requested Docker option(s) ${mismatchedOptions.join(
+        ", "
+      )} differ from inspected HostConfig field(s) ${remainingMismatchedHostConfigFields.join(
+        ", "
+      )} and cannot be applied to the existing container. Destroy and recreate the sandbox to apply them.`,
+      { containerId, fields: mismatchedOptions, hostConfigFields: remainingMismatchedHostConfigFields }
+    );
+  }
+  _requestedHardeningHostConfigEntries(hostConfig) {
+    const entries = [
+      ["Memory", this._memory],
+      ["MemorySwap", this._memorySwap],
+      ["CpuShares", this._cpuShares],
+      ["CpuQuota", this._cpuQuota],
+      ["CpuPeriod", this._cpuPeriod],
+      ["PidsLimit", this._pidsLimit],
+      ["ReadonlyRootfs", this._readonlyRootfs],
+      ["CapDrop", this._capDrop],
+      ["CapAdd", this._capAdd],
+      ["SecurityOpt", this._securityOpt],
+      ["Ulimits", this._ulimits],
+      ["Tmpfs", this._tmpfs]
+    ];
+    if (this._privilegedWasSet || hostConfig?.Privileged === true) {
+      entries.unshift(["Privileged", this._privileged]);
+    }
+    return entries.filter((entry) => isPresentHostConfigValue(entry[1]));
+  }
   async stop() {
     const container = await this._resolveContainer();
     if (!container) return;
@@ -517,6 +617,92 @@ function isImageNotFoundError(error) {
   }
   return false;
 }
+function isHostConfigValueEqual(field, actual, expected) {
+  return util.isDeepStrictEqual(normalizeHostConfigValue(field, actual), normalizeHostConfigValue(field, expected));
+}
+function normalizeHostConfigValue(field, value) {
+  if (value == null) return void 0;
+  if ((field === "CapAdd" || field === "CapDrop") && Array.isArray(value)) {
+    if (value.length === 0) return void 0;
+    return value.map(normalizeCapability).sort();
+  }
+  if (field === "SecurityOpt" && Array.isArray(value)) {
+    if (value.length === 0) return void 0;
+    return value.map(normalizeSecurityOpt).sort();
+  }
+  if (field === "Tmpfs" && value && typeof value === "object" && !Array.isArray(value)) {
+    if (Object.keys(value).length === 0) return void 0;
+    return Object.fromEntries(
+      Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([path, options]) => [path, typeof options === "string" ? normalizeTmpfsOptions(options) : options])
+    );
+  }
+  if (Array.isArray(value)) {
+    if (field === "Ulimits" && value.length === 0) return void 0;
+    return value.map((nestedValue) => normalizeHostConfigValue(field, nestedValue)).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  }
+  if (field === "Ulimits" && value && typeof value === "object") {
+    return normalizeUlimit(value);
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, nestedValue]) => [key, normalizeHostConfigValue(field, nestedValue)])
+    );
+  }
+  return value;
+}
+function isPresentHostConfigValue(value) {
+  if (value == null) return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (value && typeof value === "object") return Object.keys(value).length > 0;
+  return true;
+}
+function normalizeCapability(capability) {
+  return typeof capability === "string" ? capability.toUpperCase().replace(/^CAP_/, "") : capability;
+}
+function normalizeTmpfsOptions(options) {
+  return options.split(",").map((option) => option.trim()).filter(Boolean).sort().join(",");
+}
+function normalizeSecurityOpt(option) {
+  if (typeof option !== "string") return option;
+  const noNewPrivileges = option.match(/^no-new-privileges[:=](.+)$/i);
+  if (noNewPrivileges) {
+    return `no-new-privileges=${noNewPrivileges[1]}`;
+  }
+  return option;
+}
+function normalizeUlimit(value) {
+  const record = value;
+  return {
+    name: record.name ?? record.Name,
+    soft: record.soft ?? record.Soft,
+    hard: record.hard ?? record.Hard
+  };
+}
+function toDockerUlimit(ulimit) {
+  return {
+    Name: ulimit.name,
+    Soft: ulimit.soft,
+    Hard: ulimit.hard
+  };
+}
+function toDockerSandboxOptionName(field) {
+  const optionNames = {
+    Privileged: "privileged",
+    Memory: "memory",
+    MemorySwap: "memorySwap",
+    CpuShares: "cpuShares",
+    CpuQuota: "cpuQuota",
+    CpuPeriod: "cpuPeriod",
+    PidsLimit: "pidsLimit",
+    ReadonlyRootfs: "readonlyRootfs",
+    CapDrop: "capDrop",
+    CapAdd: "capAdd",
+    SecurityOpt: "securityOpt",
+    Ulimits: "ulimits",
+    Tmpfs: "tmpfs"
+  };
+  return optionNames[field] ?? String(field);
+}
 
 // src/provider.ts
 var dockerSandboxProvider = {
@@ -559,6 +745,68 @@ var dockerSandboxProvider = {
         type: "boolean",
         description: "Run in privileged mode",
         default: false
+      },
+      memory: {
+        type: "number",
+        description: "Memory limit in bytes"
+      },
+      memorySwap: {
+        type: "number",
+        description: "Total memory plus swap in bytes"
+      },
+      cpuShares: {
+        type: "number",
+        description: "CPU shares relative weight"
+      },
+      cpuQuota: {
+        type: "number",
+        description: "CPU quota in microseconds per period"
+      },
+      cpuPeriod: {
+        type: "number",
+        description: "CPU period in microseconds"
+      },
+      pidsLimit: {
+        type: "number",
+        description: "Maximum number of PIDs in the container"
+      },
+      readonlyRootfs: {
+        type: "boolean",
+        description: "Mount the container root filesystem as read-only"
+      },
+      capDrop: {
+        type: "array",
+        description: "Linux capabilities to drop",
+        items: { type: "string" }
+      },
+      capAdd: {
+        type: "array",
+        description: "Linux capabilities to add",
+        items: { type: "string" }
+      },
+      securityOpt: {
+        type: "array",
+        description: "Docker security options",
+        items: { type: "string" }
+      },
+      ulimits: {
+        type: "array",
+        description: "Ulimit entries for Docker HostConfig.Ulimits",
+        items: {
+          type: "object",
+          required: ["name", "soft", "hard"],
+          additionalProperties: false,
+          properties: {
+            name: { type: "string" },
+            soft: { type: "number" },
+            hard: { type: "number" }
+          }
+        }
+      },
+      tmpfs: {
+        type: "object",
+        description: "tmpfs mount paths with options",
+        additionalProperties: { type: "string" }
       }
     }
   },