Skip to content

docs(security): align sandbox boundary claims with Runtime Host enforcement #4063

Description

@Sun-GLiang

What happened

SECURITY.md currently says that product compositions do not route command execution through the macOS Seatbelt transformer, so it is not a product boundary:

Maka does not run tools in a separate process or container by default. The runtime exposes a macOS Seatbelt command transformer for restricted profiles, but current product compositions do not yet route command execution through it, so it is not a product boundary today.

That statement is stale at 2b5dd8a8716cc90fcc2ca9bd50837efd21875a94.

Runtime Host now creates a builtin SandboxManager and sandboxed FilesystemWorkerClient, then injects both into the builtin tool composition:

The conflict is limited: it would also be incorrect to claim that every tool or profile is sandboxed.

Surface Current behavior under a restricted managed boundary
Foreground and background non-PTY Bash Seatbelt on macOS, bubblewrap on Linux; fails closed if required enforcement is unavailable
Managed PTY Bash Refused because command sandboxing is unavailable
Local-path file tools Sandboxed filesystem worker; AppContainer covers this purpose-built worker on Windows
Windows arbitrary-shell Bash Unsupported and fails closed when a command sandbox is required
Client integrated terminal (runtime.resource.start) Host PTY outside the managed agent execution boundary

Bypass, unrestricted, disabled, and external profiles do not add a Maka-managed local sandbox. workspace-write also permits the configured temporary roots, not only the workspace.

This is a documentation-consistency bug, not a report of a demonstrated sandbox escape.

Expected behavior: the security policy and runtime sandbox README describe the same product boundary and distinguish the OS-user-account trust envelope, per-command OS enforcement, and in-process permission heuristics.

How to reproduce

  1. Check out 2b5dd8a8716cc90fcc2ca9bd50837efd21875a94.
  2. Compare SECURITY.md:83-102 with packages/runtime/src/sandbox/README.md:49-68.
  3. Follow Bash through builtin-tools.ts:295-325 and shell-tools.ts:288-326.
  4. Follow local file tools through filesystem-executor.ts:178-248.
  5. Compare those paths with runtime-resource-coordinator.ts:357-398, which launches the integrated-terminal host PTY.
  6. Run git blame -L 97,102 SECURITY.md; the paragraph predates the current Runtime Host wiring.

Environment

  • Maka commit: 2b5dd8a8716cc90fcc2ca9bd50837efd21875a94
  • OS used for runtime verification: macOS
  • Surface: Runtime Host, builtin Bash/file tools, integrated terminal

Logs, screenshots, or additional context

Relevant history:

Acceptance criteria:

  • Remove the stale product-composition claim without claiming universal sandbox coverage.
  • Document the supported tool, profile, and platform matrix.
  • Treat supported Seatbelt, bubblewrap, and AppContainer paths as OS-enforced boundaries, distinct from in-process heuristics.
  • Document managed PTY and integrated-terminal exclusions.
  • Add Runtime Host product-composition evidence for restricted managed Bash and file tools.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions