SHADI Sandbox (MVP)

SHADI includes a kernel-enforced sandbox launcher to run agent processes with a restricted capability set. macOS uses the Seatbelt sandbox APIs. Windows uses AppContainer + ACL-based allowlists with optional network capability toggles, plus Job Objects to ensure child processes are terminated with the parent.

CLI

cargo run -p shadictl -- \
  --allow . \
  --net-block \
  -- \
  ./your-agent --arg value

Portable launcher profiles (no shell wrapper)

shadictl now has a built-in policy profile model so you can launch securely without platform-specific Bash/PowerShell wrappers:

cargo run -p shadictl -- --profile strict -- -- ./your-agent

Profiles: - strict: local workspace only, network blocked. - balanced (default): workspace access with network blocked. - connected: workspace access with network allowed.

On macOS, all built-in profiles now resolve through the minimal Seatbelt platform profile by default. That keeps the runtime allowances needed to start common tooling, but stops adding an implicit root read allowlist for balanced and connected. Add explicit --read or --allow paths when a workload needs extra filesystem access beyond the workspace.

Starter profile matrix

Use this matrix as a baseline when selecting a profile:

Workload	Recommended profile	Why
Local processing agent (no network calls)	strict	Smallest blast radius and full network block.
Typical development agent (reads toolchain/system paths)	balanced	Keeps network off while allowing common runtime reads.
API-integrated agent (GitHub/LLM calls)	connected	Enables network while keeping filesystem policy centralized.

Then tighten with explicit path flags (--allow, --read, --write) and only open command exceptions with --allow-command when strictly required.

Print the resolved profile policy:

cargo run -p shadictl -- --profile balanced --print-policy

The printed policy now includes platform_profile, which is minimal on macOS for the built-in launcher profiles.

JSON Policy

You can pass a JSON policy file to avoid long CLI arguments:

{
  "allow": ["."],
  "read": ["/opt/homebrew"],
  "write": ["./output"],
  "net_block": true,
  "net_allow": ["api.github.com", "127.0.0.1"],
  "allow_command": ["rm"],
  "block_command": ["curl"],
  "process_inject_keychain": [
    {
      "program": "/Users/example/bin/secops-agent",
      "key": "secops/api-token",
      "env": "SECOPS_TOKEN"
    }
  ],
  "process_trusted_secret": [
    {
      "program": "/Users/example/bin/avatar-agent",
      "key": "avatar/session-key",
      "name": "avatar-session",
      "fd_env": "AVATAR_SESSION_FD"
    }
  ],
  "process_secret_policy": [
    {
      "program": "/Users/example/bin/secops-agent",
      "secret": "secops/github_token",
      "actions": ["delegate-to-child"],
      "children": ["/usr/bin/curl"],
      "name": "github-token",
      "fd_env": "GITHUB_TOKEN_FD"
    }
  ]
}

Run it with:

cargo run -p shadictl -- --policy ./sandbox.json -- ./your-agent

CLI flags override policy file settings. Paths are canonicalized before use. Profile defaults are applied first, then policy file values, then CLI flags. Process-scoped secret rules are matched against the exact resolved executable path for the launched command, so a shared policy file can carry secrets for multiple entrypoints without making them ambient to every run. On Unix/macOS, trusted-secret delivery now uses a brokered one-shot fetch path instead of an inherited secret-bearing FD, which reduces relay risk when a matched process execs into a different executable before consuming the secret. For delegated child delivery, SHADI also adds only the temporary runtime allowances needed for the broker endpoint and, on macOS, local Unix sockets.

Flags

• --policy FILE: Load policy settings from a JSON file.
• --profile PROFILE: Built-in launcher profile (strict, balanced, connected).
• --allow PATH: Allow read+write under the path.
• --read PATH: Allow read-only access under the path.
• --write PATH: Allow write access under the path.
• --net-block: Block network access.
• --allow-command CMD: Override default command blocklist.
• --inject-keychain KEY=ENV: Read a keychain secret and inject it as an env var before sandboxing.
• --trusted-secret KEY=NAME: Configure direct trusted-secret delivery.
• --trusted-secret-exec NAME=PROGRAM: Bind a trusted secret to an exact executable.
• --trusted-secret-fd-env NAME=ENV: Set the endpoint env name for a trusted secret mapping.
• --git-snapshot: Capture before/after Git state for the current working tree.
• --git-snapshot-dir DIR: Override the default snapshot root at ${SHADI_TMP_DIR:-./.tmp}/git-snapshots.
• --git-snapshot-untracked: Include an explicit untracked-file inventory in the artifact.

net_allow is honored by the Python sandbox runner. It injects a sitecustomize.py hook that blocks connections outside the allowlist (best-effort; not OS-enforced).

Git-backed snapshots

shadictl can optionally capture a read-only Git snapshot around the sandboxed run. This is useful when you want an audit artifact for file changes without auto-committing anything or asking downstream tooling to reconstruct Git state from scratch.

Enable it explicitly:

cargo run -p shadictl -- \
  --allow . \
  --git-snapshot \
  --git-snapshot-untracked \
  -- \
  ./your-agent

What gets captured:

• repository detection based on the current working directory
• discovery of nested Git repositories under the sandbox working directory
• pre-run and post-run HEAD
• git status --porcelain=v1 --untracked-files=all
• git diff --binary
• optional untracked inventory via git ls-files --others --exclude-standard
• a derived comparison block so operators can tell whether HEAD, status, diff, or untracked state changed
• SHA-256 hashes for the captured Git payloads and a combined state hash

Artifact layout:

• ${SHADI_TMP_DIR:-./.tmp}/git-snapshots/runs/<artifact_id>/snapshot.json
• ${SHADI_TMP_DIR:-./.tmp}/git-snapshots/latest.json

This feature is opt-in by design. SHADI does not capture snapshots unless you pass --git-snapshot, and the first implementation remains Git-read-only.

Nested Git repos are handled explicitly. The artifact keeps the original top-level git.* fields for the primary repo rooted at the sandbox working directory, and adds git.repositories for per-repo records when additional Git repos exist below that directory. This prevents false negatives in workflows where an agent changes another repo under the same workspace.

Example: a SecOps agent may clone, pull, or commit inside a remediation target repo under its working folder. In that case the outer repo can remain clean, but the nested repo entry will still show the change through its own comparison block and will increment git.changed_repositories.

Key utilities

shadictl also manages OpenPGP keys and agent DIDs without invoking OS gpg:

cargo run -p shadictl -- \
  put-key --key human/gpg --in /path/to/human-secret.asc

cargo run -p shadictl -- \
  derive-agent-did --secret human/gpg --name agent-a --prefix agents

Secret delivery modes

SHADI supports three different secret-delivery modes at launch time:

• explicit env disclosure via --inject-keychain or process_inject_keychain
• process-scoped direct trusted delivery via process_trusted_secret
• delegated child delivery via process_secret_policy

Explicit disclosure

Keychain access is often restricted inside a sandbox. You can still read a secret before sandboxing and inject it as an environment variable when direct disclosure is intentional:

cargo run -p shadictl -- \
  --allow . \
  --read / \
  --net-block \
  --inject-keychain tourist_api_key=SHADI_BROKER_SECRET \
  -- \
  uv run agents/secops/secops.py

Trusted delivery

process_trusted_secret is the compatibility bridge between env disclosure and full delegated policy. It scopes the trusted secret to the exact launched executable and exposes a protocol-specific endpoint env instead of a broad ambient env var.

On Unix/macOS this is a one-shot broker fetch path protected by:

• exact executable matching
• process identity verification
• launch-scoped nonce presentation
• one-shot consumption semantics

On Windows, direct trusted-secret delivery remains a compatibility handle path.

Delegated child delivery

process_secret_policy adds action-based secret rules. The implemented secure path today is delegate-to-child on Unix/macOS:

• the parent process is allowed to request delivery to a specific child tool
• the parent does not receive the secret value itself
• SHADI verifies the child executable, optional child SHA-256 constraint, and nonce
• the child receives the secret directly as the final authorized consumer

Notes

• This is an MVP and uses a conservative Seatbelt profile. System paths required to execute processes are allowed for read access.
• On macOS, the built-in launcher profiles use the minimal Seatbelt platform profile by default; broader read allowances should be granted explicitly.
• Command blocking is enforced before launch in the CLI.
• Git snapshots are metadata capture only. They do not commit, stage, or rewrite Git history.
• On macOS, policy paths are resolved to absolute paths before Seatbelt rules are emitted; relative subpaths are not reliable enforcement inputs.
• The demo launchers may still pre-read secrets outside the sandbox when a workload requires explicit disclosure or when the optional 1Password backend cannot be accessed safely inside the sandbox.
• Windows: ACL allowlists are applied to the specified paths for the AppContainer SID and automatically reverted when the sandboxed process exits. Network access is controlled by AppContainer capabilities.

Sandbox boundary guidance

Use the sandbox as the security boundary, not application-level path deny rules. Path-matching controls are useful for operator ergonomics, but they are weaker than OS-enforced policy because the agent can reason about alternate paths and wrappers. SHADI resolves and applies the effective sandbox policy before launch, which is the property you should rely on for enforcement.

Windows integration test

The Windows AppContainer sandbox has an opt-in integration test. Run it on Windows with:

SHADI_WINDOWS_INTEGRATION=1 cargo test -p shadi_sandbox

Or via Just:

just windows-integration