aiskillstore/marketplace / pending/cagdasyurekli/agy-worker
agy-worker
UnverifiedUse when Codex or Claude Code should delegate repository exploration or implementation to Google Antigravity CLI (agy), then review, verify, repair, and deliver the result.
runtime/scripts/agy_dispatch_containment.py
View on GitHub#!/usr/bin/env python3
"""macOS OS containment for selected-content and self-verification launches.
The dispatcher remains responsible for deciding whether a launch is scoped and
for binding the provider selection. This module owns only the native launch
envelope: an owner-private profile, private provider state, a per-attempt temp
directory, and identity-safe process-group termination.
``sandbox-exec`` is a deprecated macOS interface. The implementation therefore
binds the Darwin build and launcher bytes and fails closed everywhere else. A
caller must re-run :func:`confirm_contained_launch` immediately before ``Popen``.
This primitive binds the stage directory, not its contents. The trusted dispatcher
must supply a freshly copied, no-hardlink stage and rebind its complete approved
manifest before launch. A pre-existing hardlink inside an allowed directory still
names the outside inode. It must also launch with DEVNULL stdin, private pipes for
stdout/stderr, close_fds=True and no pass_fds: an inherited open descriptor is not
revoked by a pathname sandbox. Neither prerequisite is proved by directory binding.
"""
from __future__ import annotations
import ctypes
import dataclasses
import hashlib
import json
import os
from pathlib import Path
import platform
import plistlib
import posixpath
import pwd
import signal
import stat
import subprocess
import sys
import time
from typing import Mapping, Sequence, cast
import uuid
SANDBOX_EXEC = Path("/usr/bin/sandbox-exec")
MAX_EXECUTABLE_BYTES = 512 * 1024 * 1024
MAX_PROFILE_BYTES = 64 * 1024
DEDICATED_KEYCHAIN_NAME = "agy-worker-provider.keychain-db"
KEYCHAIN_SETUP_DOC = "references/TROUBLESHOOTING.md (Dedicated agy keychain for native isolation)"
KEYCHAIN_STATUS_DEADLINE_SECONDS = 5
EXIT_NATIVE_HOST_UNAVAILABLE = 27
MAX_GROUP_MEMBERS = 4096
PROCESS_GROUP_CLEANUP_SCOPE = "bound-process-group-only"
ROLE_PROVIDER = "provider"
ROLE_SELF_VERIFY = "self-verify"
NETWORK_DENY_ALL = "deny-all"
NETWORK_PROVIDER_TLS = "provider-tls"
GRANT_PROFILE_BASELINE = "baseline"
GRANT_PROFILE_A = "A"
GRANT_PROFILE_B = "B"
GRANT_PROFILE_AB = "AB"
# Only new command/preview construction reads this policy choice. Legacy callers
# retain the literal baseline defaults on render and prepare.
NEW_NATIVE_GRANT_PROFILE = "baseline"
_GRANT_PROFILES = frozenset({
GRANT_PROFILE_BASELINE, GRANT_PROFILE_A, GRANT_PROFILE_B, GRANT_PROFILE_AB,
})
_ROLES = frozenset({ROLE_PROVIDER, ROLE_SELF_VERIFY})
_PROC_PIDTBSDINFO = 3
_MAXCOMLEN = 16
# SecKeychainGetStatus reports kSecUnlockStateStatus (1) without ever prompting.
_KEYCHAIN_STATUS_PROBE = """
import ctypes, sys
framework = "/System/Library/Frameworks/"
sec = ctypes.CDLL(framework + "Security.framework/Security")
cf = ctypes.CDLL(framework + "CoreFoundation.framework/CoreFoundation")
sec.SecKeychainOpen.argtypes = [ctypes.c_char_p, ctypes.c_void_p]
sec.SecKeychainOpen.restype = ctypes.c_int32
sec.SecKeychainGetStatus.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
sec.SecKeychainGetStatus.restype = ctypes.c_int32
cf.CFRelease.argtypes = [ctypes.c_void_p]
ref, status = ctypes.c_void_p(), ctypes.c_uint32()
if sec.SecKeychainOpen(sys.argv[1].encode(), ctypes.byref(ref)) != 0 or not ref.value:
raise SystemExit(1)
try:
if sec.SecKeychainGetStatus(ref, ctypes.byref(status)) != 0:
raise SystemExit(1)
finally:
cf.CFRelease(ref)
print("unlocked" if status.value & 1 else "locked")
"""
class ContainmentError(RuntimeError):
"""The scoped native launch boundary could not be established exactly."""
class KeychainUnavailableError(ContainmentError):
"""The dedicated Keychain is missing or locked; the message is actionable."""
@dataclasses.dataclass(frozen=True)
class FileBinding:
path: str
device: int
inode: int
uid: int
gid: int
mode: int
nlink: int
size: int
mtime_ns: int
ctime_ns: int
sha256: str | None
@dataclasses.dataclass(frozen=True)
class DirectoryBinding:
path: str
device: int
inode: int
uid: int
gid: int
mode: int
nlink: int
@dataclasses.dataclass(frozen=True)
class KeychainBinding:
"""Metadata-only identity for the database used by Security.framework."""
path: str
device: int
inode: int
uid: int
mode: int
@dataclasses.dataclass(frozen=True)
class ProcessIdentity:
pid: int
parent_pid: int
process_group: int
session_id: int
uid: int
start_seconds: int
start_microseconds: int
@dataclasses.dataclass(frozen=True)
class PreparedContainedLaunch:
role: str
network_policy: str
grant_profile: str
darwin_release: str
darwin_version: str
launcher: FileBinding
target: FileBinding
profile: FileBinding
read_only_inputs: tuple[FileBinding, ...]
keychain: KeychainBinding | None
keychain_preferences: FileBinding | None
provider_settings: FileBinding | None
stage: DirectoryBinding
private_home: DirectoryBinding
attempt_tmp: DirectoryBinding
target_argv: tuple[str, ...]
environment: tuple[tuple[str, str], ...]
allow_keychain: bool
@dataclasses.dataclass(frozen=True)
class ConfirmedContainedLaunch:
argv: tuple[str, ...]
executable: str
cwd: str
environment: dict[str, str]
class _ProcBsdInfo(ctypes.Structure):
_fields_ = [
("pbi_flags", ctypes.c_uint32),
("pbi_status", ctypes.c_uint32),
("pbi_xstatus", ctypes.c_uint32),
("pbi_pid", ctypes.c_uint32),
("pbi_ppid", ctypes.c_uint32),
("pbi_uid", ctypes.c_uint32),
("pbi_gid", ctypes.c_uint32),
("pbi_ruid", ctypes.c_uint32),
("pbi_rgid", ctypes.c_uint32),
("pbi_svuid", ctypes.c_uint32),
("pbi_svgid", ctypes.c_uint32),
("rfu_1", ctypes.c_uint32),
("pbi_comm", ctypes.c_char * _MAXCOMLEN),
("pbi_name", ctypes.c_char * (2 * _MAXCOMLEN)),
("pbi_nfiles", ctypes.c_uint32),
("pbi_pgid", ctypes.c_uint32),
("pbi_pjobc", ctypes.c_uint32),
("e_tdev", ctypes.c_uint32),
("e_tpgid", ctypes.c_uint32),
("pbi_nice", ctypes.c_int32),
("pbi_start_tvsec", ctypes.c_uint64),
("pbi_start_tvusec", ctypes.c_uint64),
]
def require_supported_host() -> None:
"""Reject unsupported hosts even when no check has been selected."""
if sys.platform != "darwin" or platform.system() != "Darwin":
raise ContainmentError("native launch containment requires macOS")
def _canonical_existing(path: str | Path) -> Path:
candidate = Path(os.fsdecode(path))
if not candidate.is_absolute() or "\0" in str(candidate):
raise ContainmentError("containment path must be canonical and absolute")
if Path(os.path.realpath(candidate)) != candidate:
raise ContainmentError("containment path must not contain aliases")
return candidate
def _read_hash(descriptor: int, limit: int) -> str:
digest = hashlib.sha256()
size = 0
os.lseek(descriptor, 0, os.SEEK_SET)
while True:
chunk = os.read(descriptor, 1024 * 1024)
if not chunk:
break
size += len(chunk)
if size > limit:
raise ContainmentError("containment executable or profile exceeds its byte limit")
digest.update(chunk)
return digest.hexdigest()
def _bind_file(
path: str | Path, *, modes: set[int], executable: bool = False,
limit: int = MAX_EXECUTABLE_BYTES, require_single_link: bool = True,
) -> FileBinding:
candidate = _canonical_existing(path)
nofollow = getattr(os, "O_NOFOLLOW", 0)
try:
named = os.lstat(candidate)
descriptor = os.open(candidate, os.O_RDONLY | nofollow)
except OSError as exc:
raise ContainmentError("containment file is unavailable") from exc
try:
before = os.fstat(descriptor)
mode = stat.S_IMODE(before.st_mode)
identity = (
before.st_dev, before.st_ino, before.st_uid, before.st_gid,
before.st_mode, before.st_nlink, before.st_size,
before.st_mtime_ns, before.st_ctime_ns,
)
named_identity = (
named.st_dev, named.st_ino, named.st_uid, named.st_gid,
named.st_mode, named.st_nlink, named.st_size,
named.st_mtime_ns, named.st_ctime_ns,
)
if (
not stat.S_ISREG(before.st_mode)
or before.st_uid not in {0, os.getuid()}
or (require_single_link and before.st_nlink != 1)
or (not require_single_link and before.st_nlink < 1)
or mode not in modes
or identity != named_identity
or (executable and mode & 0o111 == 0)
):
raise ContainmentError("containment file authority is invalid")
content_sha = _read_hash(descriptor, limit)
after = os.fstat(descriptor)
after_identity = (
after.st_dev, after.st_ino, after.st_uid, after.st_gid,
after.st_mode, after.st_nlink, after.st_size,
after.st_mtime_ns, after.st_ctime_ns,
)
if after_identity != identity or os.lstat(candidate) != after:
raise ContainmentError("containment file changed during binding")
return FileBinding(
str(candidate), before.st_dev, before.st_ino, before.st_uid,
before.st_gid, mode, before.st_nlink, before.st_size,
before.st_mtime_ns, before.st_ctime_ns, content_sha,
)
finally:
os.close(descriptor)
def _bind_keychain(path: str | Path) -> KeychainBinding:
"""Bind the dedicated Keychain by metadata without opening its database."""
candidate = _canonical_existing(path)
try:
before = os.lstat(candidate)
after = os.lstat(candidate)
except OSError as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
mode = stat.S_IMODE(before.st_mode)
stable_identity = lambda item: (
item.st_dev, item.st_ino, item.st_uid,
stat.S_IFMT(item.st_mode), stat.S_IMODE(item.st_mode),
)
if (
stable_identity(before) != stable_identity(after)
or stat.S_ISLNK(before.st_mode)
or not stat.S_ISREG(before.st_mode)
or before.st_uid != os.getuid()
or mode & 0o022
):
raise ContainmentError("native provider authentication is unavailable")
return KeychainBinding(
str(candidate), before.st_dev, before.st_ino, before.st_uid, mode,
)
def dedicated_keychain_path() -> Path:
"""Return the only Keychain native isolation may use, under the passwd-resolved HOME."""
try:
owner_home = _canonical_existing(pwd.getpwuid(os.getuid()).pw_dir)
owner = os.lstat(owner_home)
except (ContainmentError, OSError, KeyError) as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
if not stat.S_ISDIR(owner.st_mode) or owner.st_uid != os.getuid():
raise ContainmentError("native provider authentication is unavailable")
return owner_home / "Library" / "Keychains" / DEDICATED_KEYCHAIN_NAME
def _keychain_is_unlocked(path: str) -> bool:
"""Read the lock state without UI: a locked lookup would otherwise hang on a dialog."""
try:
completed = subprocess.run(
[sys.executable, "-I", "-S", "-B", "-c", _KEYCHAIN_STATUS_PROBE, path],
stdin=subprocess.DEVNULL, capture_output=True, check=False,
timeout=KEYCHAIN_STATUS_DEADLINE_SECONDS,
env={"PATH": "/usr/bin:/bin", "LANG": "C", "LC_ALL": "C"},
)
except (OSError, subprocess.TimeoutExpired) as exc:
raise KeychainUnavailableError(
f"cannot read the lock state of {path} within {KEYCHAIN_STATUS_DEADLINE_SECONDS}s"
) from exc
if completed.returncode == 0 and completed.stdout in {b"locked\n", b"unlocked\n"}:
return completed.stdout == b"unlocked\n"
raise KeychainUnavailableError(f"cannot read the lock state of {path}")
def _require_unlocked(path: str) -> None:
if not _keychain_is_unlocked(path):
raise KeychainUnavailableError(
f"the dedicated agy keychain {path} is locked; unlock it with: "
f"security unlock-keychain ~/Library/Keychains/{DEDICATED_KEYCHAIN_NAME}"
)
def _dedicated_keychain() -> KeychainBinding:
"""Bind the dedicated Keychain, failing closed when it is missing, unsafe or locked."""
path = dedicated_keychain_path()
if not os.path.lexists(path):
raise KeychainUnavailableError(
f"native isolation needs the dedicated agy keychain {path}, which does not "
f"exist; create it once as described in {KEYCHAIN_SETUP_DOC}"
)
try:
binding = _bind_keychain(path)
except ContainmentError as exc:
raise KeychainUnavailableError(
f"the dedicated agy keychain {path} must be a regular file you own "
"without group or other write access"
) from exc
_require_unlocked(binding.path)
return binding
def _bind_directory(path: str | Path) -> DirectoryBinding:
candidate = _canonical_existing(path)
nofollow = getattr(os, "O_NOFOLLOW", 0)
directory = getattr(os, "O_DIRECTORY", 0)
try:
named = os.lstat(candidate)
descriptor = os.open(candidate, os.O_RDONLY | nofollow | directory)
except OSError as exc:
raise ContainmentError("containment directory is unavailable") from exc
try:
current = os.fstat(descriptor)
if (
not stat.S_ISDIR(current.st_mode)
or stat.S_ISLNK(named.st_mode)
or current.st_uid != os.getuid()
or stat.S_IMODE(current.st_mode) != 0o700
or (
current.st_dev, current.st_ino, current.st_uid,
current.st_gid, current.st_mode, current.st_nlink
) != (
named.st_dev, named.st_ino, named.st_uid,
named.st_gid, named.st_mode, named.st_nlink
)
):
raise ContainmentError("containment directory authority is invalid")
return DirectoryBinding(
str(candidate), current.st_dev, current.st_ino, current.st_uid,
current.st_gid, stat.S_IMODE(current.st_mode), current.st_nlink,
)
finally:
os.close(descriptor)
def _ensure_private_directory(path: Path, *, existing_ok: bool) -> DirectoryBinding:
try:
os.mkdir(path, 0o700)
except FileExistsError:
if not existing_ok:
raise ContainmentError("per-attempt containment directory already exists") # noqa: B904 -- preserve existing exception context and public diagnostics
except OSError as exc:
raise ContainmentError("cannot create containment directory") from exc
try:
os.chmod(path, 0o700, follow_symlinks=False)
except OSError as exc:
raise ContainmentError("cannot normalize containment directory") from exc
return _bind_directory(path)
def _publish_profile(path: Path, payload: bytes) -> FileBinding:
if not payload or len(payload) > MAX_PROFILE_BYTES:
raise ContainmentError("containment profile has invalid size")
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
try:
descriptor = os.open(path, flags, 0o600)
except OSError as exc:
raise ContainmentError("cannot create containment profile") from exc
try:
view = memoryview(payload)
while view:
written = os.write(descriptor, view)
if written <= 0:
raise ContainmentError("cannot write containment profile")
view = view[written:]
os.fsync(descriptor)
os.fchmod(descriptor, 0o400)
finally:
os.close(descriptor)
return _bind_file(path, modes={0o400}, limit=MAX_PROFILE_BYTES)
def _publish_private_file(path: Path, payload: bytes) -> FileBinding:
"""Publish a small owner-private internal artifact without replacement."""
if not payload or len(payload) > MAX_PROFILE_BYTES:
raise ContainmentError("native provider authentication is unavailable")
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
try:
descriptor = os.open(path, flags, 0o600)
except OSError as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
try:
try:
view = memoryview(payload)
while view:
written = os.write(descriptor, view)
if written <= 0:
raise ContainmentError("native provider authentication is unavailable")
view = view[written:]
os.fsync(descriptor)
os.fchmod(descriptor, 0o600)
except OSError as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
finally:
try:
os.close(descriptor)
except OSError as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
return _bind_file(path, modes={0o600}, limit=MAX_PROFILE_BYTES)
def _default_keychain_preferences_payload(keychain: KeychainBinding) -> bytes:
"""Create the minimal private DefaultKeychain preference from Security's GUID."""
try:
framework = ctypes.CDLL("/System/Library/Frameworks/Security.framework/Security")
guid = (ctypes.c_ubyte * 16).in_dll(framework, "gGuidAppleCSPDL")
value = {
"DefaultKeychain": [{
"GUID": "{" + str(uuid.UUID(bytes=bytes(guid))).upper() + "}",
"SubserviceId": 0,
"SubserviceType": 6,
"MajorVersion": 0,
"MinorVersion": 0,
"DbName": keychain.path,
}],
}
return plistlib.dumps(value, fmt=plistlib.FMT_XML, sort_keys=True)
except (AttributeError, OSError, ValueError) as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
def _file_binding_record(binding: FileBinding) -> bytes:
return (json.dumps(dataclasses.asdict(binding), sort_keys=True, separators=(",", ":")) + "\n").encode("ascii")
def _load_file_binding_record(path: Path) -> FileBinding:
try:
sidecar = _bind_file(path, modes={0o600}, limit=MAX_PROFILE_BYTES)
descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
try:
raw = os.read(descriptor, MAX_PROFILE_BYTES + 1)
finally:
os.close(descriptor)
if len(raw) > MAX_PROFILE_BYTES:
raise ValueError("sidecar too large")
value = json.loads(raw.decode("ascii", "strict"))
if set(value) != {field.name for field in dataclasses.fields(FileBinding)}:
raise ValueError("sidecar schema")
binding = FileBinding(**value)
if not isinstance(binding.path, str) or not binding.path.startswith("/"):
raise ValueError("sidecar path")
# Bind after read: sidecar bytes and identity must be stable.
if _bind_file(path, modes={0o600}, limit=MAX_PROFILE_BYTES) != sidecar:
raise ValueError("sidecar changed")
return binding
except (ContainmentError, OSError, UnicodeError, ValueError, TypeError, json.JSONDecodeError) as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
def _prepare_keychain_preferences(
job: Path, home: Path, keychain: KeychainBinding,
) -> FileBinding:
"""Create once, then only reuse the exact private preference identity."""
preferences_dir = home / "Library" / "Preferences"
_ensure_private_directory(home / "Library", existing_ok=True)
_ensure_private_directory(preferences_dir, existing_ok=True)
preferences = preferences_dir / "com.apple.security.plist"
sidecar = job / ".provider-keychain-preferences.binding"
payload = _default_keychain_preferences_payload(keychain)
if os.path.lexists(sidecar):
prior = _load_file_binding_record(sidecar)
try:
current = _bind_file(preferences, modes={0o600}, limit=MAX_PROFILE_BYTES)
except ContainmentError as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
if current != prior or current.sha256 != hashlib.sha256(payload).hexdigest():
raise ContainmentError("native provider authentication is unavailable")
return current
if os.path.lexists(preferences):
raise ContainmentError("native provider authentication is unavailable")
created = _publish_private_file(preferences, payload)
try:
_publish_private_file(sidecar, _file_binding_record(created))
except ContainmentError:
# Never overwrite or accept a partly-created preference without its
# protected identity record on a later repair attempt.
raise
return created
def _validate_provider_write_selectors(
selectors: Sequence[Mapping[str, str]],
) -> tuple[tuple[str, str], ...]:
"""Accept only the closed, already-validated scope selector shape."""
if isinstance(selectors, (str, bytes)):
raise ContainmentError("native provider permission settings are unavailable")
result: list[tuple[str, str]] = []
previous: str | None = None
forbidden = frozenset("()[]{}*?\\\"'")
for entry in selectors:
if not isinstance(entry, Mapping) or set(entry) != {"kind", "path"}:
raise ContainmentError("native provider permission settings are unavailable")
kind, path = entry["kind"], entry["path"]
if (
kind not in {"file", "tree"}
or not isinstance(path, str)
or not path
or path.startswith("/")
or path.endswith("/")
or "\x00" in path
or any(character in forbidden for character in path)
):
raise ContainmentError("native provider permission settings are unavailable")
normalized = posixpath.normpath(path)
parts = normalized.split("/")
if (
normalized != path
or normalized in {"", ".", ".."}
or normalized.startswith("../")
or any(part in {"", ".", "..", ".git", ".agy-worker-control"} for part in parts)
or previous is not None and path <= previous
):
raise ContainmentError("native provider permission settings are unavailable")
previous = path
result.append((kind, path))
return tuple(result)
def _provider_settings_payload(
job: Path, max_cycles: int, selectors: tuple[tuple[str, str], ...],
) -> bytes:
if type(max_cycles) is not int or not 1 <= max_cycles <= 5:
raise ContainmentError("native provider permission settings are unavailable")
forbidden = frozenset("()[]{}*?\\\"'")
def rule_target(path: Path) -> str:
value = str(path)
if (
not path.is_absolute()
or "\x00" in value
or "\r" in value
or "\n" in value
or any(character in forbidden for character in value)
):
raise ContainmentError("native provider permission settings are unavailable")
return value
job_target = rule_target(job)
if Path(os.path.realpath(job_target)) != job:
raise ContainmentError("native provider permission settings are unavailable")
allowed: list[str] = []
for cycle in range(1, max_cycles + 1):
stage = job / f"stage-{cycle:03d}"
allowed.append(f"read_file({rule_target(stage)})")
allowed.extend(
f"write_file({rule_target(stage / path)})" for _kind, path in selectors
)
payload = json.dumps(
{"permissions": {"allow": allowed}},
sort_keys=True, separators=(",", ":"),
).encode("utf-8")
if not payload or len(payload) > MAX_PROFILE_BYTES:
raise ContainmentError("native provider permission settings are unavailable")
return payload
def _prepare_provider_settings(
job: Path, home: Path, max_cycles: int,
selectors: tuple[tuple[str, str], ...],
) -> FileBinding:
"""Create once and then exactly rebind the private provider policy."""
settings_parent = home / ".gemini" / "antigravity-cli"
_ensure_private_directory(home / ".gemini", existing_ok=True)
_ensure_private_directory(settings_parent, existing_ok=True)
settings = settings_parent / "settings.json"
sidecar = job / ".provider-antigravity-settings.binding"
payload = _provider_settings_payload(job, max_cycles, selectors)
if os.path.lexists(sidecar):
prior = _load_file_binding_record(sidecar)
try:
current = _bind_file(settings, modes={0o600}, limit=MAX_PROFILE_BYTES)
except ContainmentError as exc:
raise ContainmentError("native provider permission settings are unavailable") from exc
if current != prior or current.sha256 != hashlib.sha256(payload).hexdigest():
raise ContainmentError("native provider permission settings are unavailable")
return current
if os.path.lexists(settings):
raise ContainmentError("native provider permission settings are unavailable")
created = _publish_private_file(settings, payload)
_publish_private_file(sidecar, _file_binding_record(created))
return created
def _scheme_string(value: str) -> str:
if "\0" in value:
raise ContainmentError("sandbox profile value contains NUL")
escaped = value.replace("\\", "\\\\").replace('"', '\\"')
escaped = escaped.replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
return f'"{escaped}"'
def _validate_grant_profile(
grant_profile: str, role: str, network_policy: str, allow_keychain: bool,
) -> None:
if type(grant_profile) is not str or grant_profile not in _GRANT_PROFILES:
raise ContainmentError("native grant profile is invalid")
if role != ROLE_PROVIDER and grant_profile != GRANT_PROFILE_BASELINE:
raise ContainmentError("only provider launches may select native grants")
if grant_profile in {GRANT_PROFILE_A, GRANT_PROFILE_AB} and not allow_keychain:
raise ContainmentError("native grant profile requires provider keychain")
if grant_profile in {GRANT_PROFILE_B, GRANT_PROFILE_AB} and network_policy != NETWORK_PROVIDER_TLS:
raise ContainmentError("native grant profile requires provider TLS")
def render_profile(
*, target_executable: str, role: str, network_policy: str,
allow_keychain: bool, read_only_inputs: Sequence[str] = (),
keychain_path: str | None = None, provider_settings_path: str | None = None,
grant_profile: str = "baseline",
) -> bytes:
"""Render the fixed default-deny profile; dynamic paths use ``-D`` params."""
if role not in _ROLES:
raise ContainmentError("containment role is invalid")
if network_policy not in {NETWORK_DENY_ALL, NETWORK_PROVIDER_TLS}:
raise ContainmentError("containment network policy is invalid")
if network_policy == NETWORK_PROVIDER_TLS and role != ROLE_PROVIDER:
raise ContainmentError("only provider launches may use provider TLS")
if role != ROLE_PROVIDER and allow_keychain:
raise ContainmentError("only provider launches may access the keychain")
_validate_grant_profile(grant_profile, role, network_policy, allow_keychain)
if (allow_keychain and (
not isinstance(keychain_path, str) or not keychain_path.startswith("/")
)) or (not allow_keychain and keychain_path is not None):
raise ContainmentError("containment keychain input is invalid")
if provider_settings_path is not None and (
not allow_keychain
or not isinstance(provider_settings_path, str)
or not provider_settings_path.startswith("/")
):
raise ContainmentError("containment provider settings input is invalid")
if provider_settings_path is not None:
settings = Path(provider_settings_path)
if (
str(settings) != provider_settings_path
or ".." in settings.parts
or settings.parts[-3:] != (".gemini", "antigravity-cli", "settings.json")
or settings.parents[2] == Path("/")
):
raise ContainmentError("containment provider settings input is invalid")
if len(read_only_inputs) > 8 or any(
not isinstance(path, str) or not path.startswith("/") for path in read_only_inputs
):
raise ContainmentError("containment read-only inputs are invalid")
runtime_reads = ""
if read_only_inputs:
runtime_reads = "\n(allow file-read*\n" + "".join(
f" (literal {_scheme_string(path)})\n" for path in read_only_inputs
) + ")\n"
provider_parent_metadata = ""
if role == ROLE_PROVIDER:
# Core Foundation needs the executable directory's metadata to build
# its main bundle and SSL policy. Keep contents and exec helpers denied.
provider_parent_metadata = f"""
(with-filter (process-path {_scheme_string(target_executable)})
(allow file-read-metadata file-test-existence
(literal {_scheme_string(str(Path(target_executable).parent))}))
; SQLite resolves every ancestor before opening its private conversation DB.
(allow file-read-metadata (path-ancestors (param "HOME"))))
"""
keychain = ""
if allow_keychain:
# A fork retains the target image and its exact service authority. An
# exec normally loses that authority; /usr/bin/security is the sole
# Keychain-helper exception and inherits every other profile boundary.
direct_keychain = f"""(with-filter (process-path {_scheme_string(target_executable)})
(allow mach-lookup
(global-name "com.apple.SecurityServer")
(global-name "com.apple.securityd.xpc")
(global-name "com.apple.securityd.general")
(global-name "com.apple.trustd")
(global-name "com.apple.trustd.agent")))
"""
helper_keychain = f"""(with-filter (process-path {_scheme_string("/usr/bin/security")})
(allow mach-lookup
(global-name "com.apple.SecurityServer")
(global-name "com.apple.securityd.xpc")
(global-name "com.apple.securityd.general")
(global-name "com.apple.trustd")
(global-name "com.apple.trustd.agent"))
(allow file-read*
(literal {_scheme_string(cast(str, keychain_path))})))
"""
keychain = "\n"
if grant_profile not in {GRANT_PROFILE_A, GRANT_PROFILE_AB}:
keychain += direct_keychain
keychain += helper_keychain
network = ""
if network_policy == NETWORK_PROVIDER_TLS:
# Apple's localhost token was qualified against owned IPv4, IPv6, and
# interface-local listeners. This is a process/port boundary, not a
# recipient allowlist or proof that the connection uses TLS. For local
# listeners it also permits wildcard binds; the exact provider image is
# trusted to request its advertised localhost endpoint.
network = f"""
(with-filter (process-path {_scheme_string(target_executable)})
(allow network-outbound
(require-all (remote tcp "*:443")
(require-not (remote ip "localhost:*"))))
(allow network-outbound (literal "/private/var/run/mDNSResponder"))
"""
if grant_profile not in {GRANT_PROFILE_B, GRANT_PROFILE_AB}:
network += ' (allow network-bind network-inbound (local tcp "localhost:*"))\n'
network += """ (allow mach-lookup (global-name "com.apple.mDNSResponder")))
(deny network-outbound (remote ip "localhost:*"))
"""
provider_settings = ""
if provider_settings_path is not None:
# Protect the directory entries as well as the leaf: replacing an
# ancestor otherwise changes which policy the same pathname names.
# Literal rules keep mutable logs and state below these parents writable.
settings = Path(provider_settings_path)
provider_settings = f"""
(deny file-write*
(literal (param "HOME"))
(literal {_scheme_string(str(settings.parent.parent))})
(literal {_scheme_string(str(settings.parent))}))
(deny file-write*
(literal {_scheme_string(provider_settings_path)}))
"""
profile_text = f"""(version 1)
(deny default)
(import "dyld-support.sb")
; Fork/exec is required for ordinary build tools. Every exec inherits this
; profile. Darwin implements setsid/setpgid without a process-info-setcontrol
; hook, so explicitly deny those two syscalls while leaving fork available.
(allow syscall*)
(allow mach-bootstrap)
(deny syscall-unix
(syscall-number SYS_setsid)
(syscall-number SYS_setpgid))
(allow process-fork)
(allow process-exec
(literal (param "TARGET"))
(subpath (param "STAGE"))
(subpath "/bin")
(subpath "/usr/bin")
(subpath "/Library/Developer/CommandLineTools"))
(allow process-info-pidinfo (target self))
(allow sysctl-read)
(allow file-read* file-map-executable
(literal (param "TARGET"))
(subpath (param "STAGE"))
(subpath (param "HOME"))
(subpath (param "TMPDIR"))
(subpath "/bin")
(subpath "/usr/bin")
(subpath "/usr/lib")
(subpath "/usr/share")
(subpath "/System")
(subpath "/Library/Apple")
(subpath "/Library/Developer/CommandLineTools")
(subpath "/private/var/db/timezone")
(literal "/")
(literal "/dev/null")
(literal "/dev/zero")
(literal "/dev/random")
(literal "/dev/urandom")
(literal "/etc/resolv.conf")
(literal "/private/etc/resolv.conf")
(literal "/private/var/run/resolv.conf"))
(allow file-read-metadata file-test-existence
(path-ancestors "/Library/Developer/CommandLineTools")
(literal "/var")
(literal "/private/var/select")
(literal "/private/var/select/developer_dir")
(literal "/private/var/select/sh"))
(allow file-write-data
(literal "/dev/null")
(literal "/dev/zero")
(subpath "/dev/fd"))
(allow file-read* file-write*
(subpath (param "STAGE"))
(subpath (param "HOME"))
(subpath (param "TMPDIR")))
{runtime_reads}{provider_parent_metadata}{keychain}{network}{provider_settings}"""
return profile_text.encode("utf-8")
def _bind_target(path: str | Path) -> FileBinding:
binding = _bind_file(
path, modes={0o700, 0o750, 0o755}, executable=True,
require_single_link=False,
)
if binding.uid != 0 and binding.nlink != 1:
raise ContainmentError("user-owned containment target has multiple links")
return binding
def prepare_contained_launch(
*,
role: str,
network_policy: str,
job_dir: str | Path,
attempt: int,
stage_dir: str | Path,
target_executable: str | Path,
target_argv: Sequence[str],
child_environment: Mapping[str, str],
allow_keychain: bool = False,
read_only_inputs: Sequence[str | Path] = (),
provider_max_cycles: int | None = None,
provider_write_selectors: Sequence[Mapping[str, str]] = (),
grant_profile: str = "baseline",
) -> PreparedContainedLaunch:
"""Create and bind one native selected-content launch envelope."""
require_supported_host()
if role not in _ROLES:
raise ContainmentError("containment role is invalid")
if network_policy not in {NETWORK_DENY_ALL, NETWORK_PROVIDER_TLS}:
raise ContainmentError("containment network policy is invalid")
if network_policy == NETWORK_PROVIDER_TLS and role != ROLE_PROVIDER:
raise ContainmentError("only provider launches may use provider TLS")
if role != ROLE_PROVIDER and allow_keychain:
raise ContainmentError("only provider launches may access the keychain")
_validate_grant_profile(grant_profile, role, network_policy, allow_keychain)
if allow_keychain and provider_max_cycles is None:
raise ContainmentError("native provider permission settings are unavailable")
if not allow_keychain and (
provider_max_cycles is not None or tuple(provider_write_selectors)
):
raise ContainmentError("containment provider settings are invalid")
if type(attempt) is not int or not 1 <= attempt <= 999:
raise ContainmentError("containment attempt is invalid")
if not target_argv or any(
not isinstance(value, str) or "\0" in value for value in target_argv
):
raise ContainmentError("containment target argv is invalid")
if any(
not isinstance(key, str) or not isinstance(value, str)
or not key or "=" in key or "\0" in key or "\0" in value
for key, value in child_environment.items()
):
raise ContainmentError("child environment is invalid")
job = _canonical_existing(job_dir)
job_binding = _bind_directory(job)
stage = _bind_directory(stage_dir)
if Path(stage.path).parent != Path(job_binding.path):
raise ContainmentError("scoped stage must be an immediate job child")
if allow_keychain and Path(stage.path) != Path(job_binding.path) / f"stage-{attempt:03d}":
raise ContainmentError("native provider permission settings are unavailable")
launcher = _bind_file(SANDBOX_EXEC, modes={0o755}, executable=True)
target = _bind_target(target_executable)
if target_argv[0] != target.path:
raise ContainmentError("containment target argv does not name the bound executable")
if len(read_only_inputs) > 8:
raise ContainmentError("too many containment read-only inputs")
bound_inputs = tuple(
_bind_file(
path, modes={0o400, 0o444, 0o600, 0o644},
limit=MAX_PROFILE_BYTES,
)
for path in read_only_inputs
)
if len({item.path for item in bound_inputs}) != len(bound_inputs):
raise ContainmentError("containment read-only inputs are repeated")
stem = "provider" if role == ROLE_PROVIDER else "self-verify"
keychain: KeychainBinding | None = None
keychain_preferences: FileBinding | None = None
provider_settings: FileBinding | None = None
if allow_keychain:
try:
assert provider_max_cycles is not None
selectors = _validate_provider_write_selectors(provider_write_selectors)
if type(provider_max_cycles) is not int or not attempt <= provider_max_cycles <= 5:
raise ContainmentError("native provider permission settings are unavailable")
except ContainmentError as exc:
raise ContainmentError("native provider permission settings are unavailable") from exc
try:
# Before any provider HOME exists: a missing or locked keychain leaves the job untouched.
keychain = _dedicated_keychain()
except KeychainUnavailableError:
raise
except ContainmentError as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
home = _ensure_private_directory(job / f"{stem}-home", existing_ok=True)
if allow_keychain:
assert provider_max_cycles is not None
try:
keychain_preferences = _prepare_keychain_preferences(
job, Path(home.path), cast(KeychainBinding, keychain),
)
except ContainmentError as exc:
raise ContainmentError("native provider authentication is unavailable") from exc
try:
provider_settings = _prepare_provider_settings(
job, Path(home.path), provider_max_cycles, selectors,
)
# Creating the private preference subtree changes the directory's
# link count; bind the final provider HOME, not an earlier shape.
home = _bind_directory(home.path)
except ContainmentError as exc:
raise ContainmentError("native provider permission settings are unavailable") from exc
attempt_tmp = _ensure_private_directory(
job / f"{stem}-tmp-{attempt:03d}", existing_ok=False,
)
profile_payload = render_profile(
target_executable=target.path,
role=role,
network_policy=network_policy,
allow_keychain=allow_keychain,
read_only_inputs=tuple(item.path for item in bound_inputs),
keychain_path=keychain.path if keychain is not None else None,
provider_settings_path=(
provider_settings.path if provider_settings is not None else None
),
grant_profile=grant_profile,
)
profile_binding = _publish_profile(
job / f"{stem}-sandbox-{attempt:03d}.sb", profile_payload,
)
if role == ROLE_SELF_VERIFY:
environment = {
"PATH": "/usr/bin:/bin",
"LANG": "C",
"LC_ALL": "C",
"TERM": "dumb",
"NO_COLOR": "1",
}
else:
environment = dict(child_environment)
environment.update({
"HOME": home.path,
"TMPDIR": attempt_tmp.path,
"XDG_CACHE_HOME": str(Path(home.path) / ".cache"),
"XDG_CONFIG_HOME": str(Path(home.path) / ".config"),
"XDG_DATA_HOME": str(Path(home.path) / ".local" / "share"),
"XDG_STATE_HOME": str(Path(home.path) / ".local" / "state"),
})
return PreparedContainedLaunch(
role, network_policy, grant_profile, platform.release(), platform.version(), launcher,
target, profile_binding, bound_inputs, keychain, keychain_preferences, provider_settings,
stage, home, attempt_tmp, tuple(target_argv),
tuple(sorted(environment.items())), bool(allow_keychain),
)
def confirm_contained_launch(
prepared: PreparedContainedLaunch,
) -> ConfirmedContainedLaunch:
"""Revalidate every native authority immediately before caller ``Popen``."""
require_supported_host()
if (platform.release(), platform.version()) != (
prepared.darwin_release, prepared.darwin_version,
):
raise ContainmentError("Darwin build changed before scoped launch")
if _bind_file(prepared.launcher.path, modes={0o755}, executable=True) != prepared.launcher:
raise ContainmentError("sandbox launcher changed before scoped launch")
if _bind_file(
prepared.target.path, modes={0o700, 0o750, 0o755}, executable=True,
require_single_link=False,
) != prepared.target:
raise ContainmentError("target executable changed before contained launch")
if _bind_file(
prepared.profile.path, modes={0o400}, limit=MAX_PROFILE_BYTES,
) != prepared.profile:
raise ContainmentError("sandbox profile changed before scoped launch")
expected_profile = render_profile(
target_executable=prepared.target.path,
role=prepared.role,
network_policy=prepared.network_policy,
allow_keychain=prepared.allow_keychain,
read_only_inputs=tuple(item.path for item in prepared.read_only_inputs),
keychain_path=prepared.keychain.path if prepared.keychain is not None else None,
provider_settings_path=(
prepared.provider_settings.path if prepared.provider_settings is not None else None
),
grant_profile=prepared.grant_profile,
)
if hashlib.sha256(expected_profile).hexdigest() != prepared.profile.sha256:
raise ContainmentError("native grant profile changed before scoped launch")
if any(
_bind_file(
item.path, modes={0o400, 0o444, 0o600, 0o644},
limit=MAX_PROFILE_BYTES,
) != item
for item in prepared.read_only_inputs
):
raise ContainmentError("containment read-only input changed before launch")
if prepared.allow_keychain:
if prepared.keychain is None or prepared.keychain_preferences is None:
raise ContainmentError("native provider authentication is unavailable")
if _bind_keychain(prepared.keychain.path) != prepared.keychain:
raise ContainmentError("native provider authentication is unavailable")
_require_unlocked(prepared.keychain.path)
if _bind_file(
prepared.keychain_preferences.path, modes={0o600}, limit=MAX_PROFILE_BYTES,
) != prepared.keychain_preferences:
raise ContainmentError("native provider authentication is unavailable")
try:
if prepared.provider_settings is None or _bind_file(
prepared.provider_settings.path, modes={0o600}, limit=MAX_PROFILE_BYTES,
) != prepared.provider_settings:
raise ContainmentError("native provider permission settings are unavailable")
except ContainmentError as exc:
raise ContainmentError("native provider permission settings are unavailable") from exc
elif (
prepared.keychain is not None or prepared.keychain_preferences is not None
or prepared.provider_settings is not None
):
raise ContainmentError("native provider authentication is unavailable")
if _bind_directory(prepared.stage.path) != prepared.stage:
raise ContainmentError("scoped stage changed before launch")
if _bind_directory(prepared.private_home.path) != prepared.private_home:
raise ContainmentError("private HOME changed before launch")
if _bind_directory(prepared.attempt_tmp.path) != prepared.attempt_tmp:
raise ContainmentError("private provider TMPDIR changed before launch")
argv = (
prepared.launcher.path,
"-f", prepared.profile.path,
"-D", f"TARGET={prepared.target.path}",
"-D", f"STAGE={prepared.stage.path}",
"-D", f"HOME={prepared.private_home.path}",
"-D", f"TMPDIR={prepared.attempt_tmp.path}",
prepared.target.path,
*prepared.target_argv[1:],
)
return ConfirmedContainedLaunch(
argv, prepared.launcher.path, prepared.stage.path,
dict(prepared.environment),
)
def _libproc() -> ctypes.CDLL:
require_supported_host()
library = ctypes.CDLL("/usr/lib/libproc.dylib", use_errno=True)
library.proc_pidinfo.argtypes = [
ctypes.c_int, ctypes.c_int, ctypes.c_uint64,
ctypes.c_void_p, ctypes.c_int,
]
library.proc_pidinfo.restype = ctypes.c_int
library.proc_listpgrppids.argtypes = [ctypes.c_int, ctypes.c_void_p, ctypes.c_int]
library.proc_listpgrppids.restype = ctypes.c_int
return library
def capture_process_identity(pid: int) -> ProcessIdentity:
"""Bind a Darwin PID to kernel start time, owner, group, and session."""
if type(pid) is not int or pid <= 1:
raise ContainmentError("provider PID is invalid")
info = _ProcBsdInfo()
library = _libproc()
size = library.proc_pidinfo(
pid, _PROC_PIDTBSDINFO, 0, ctypes.byref(info), ctypes.sizeof(info),
)
if size != ctypes.sizeof(info) or int(info.pbi_pid) != pid:
raise ContainmentError("provider process identity is unavailable")
try:
session_id = os.getsid(pid)
except OSError as exc:
raise ContainmentError("provider process session is unavailable") from exc
return ProcessIdentity(
pid, int(info.pbi_ppid), int(info.pbi_pgid), session_id,
int(info.pbi_uid), int(info.pbi_start_tvsec), int(info.pbi_start_tvusec),
)
def bind_new_process_group(pid: int) -> ProcessIdentity:
"""Bind the session leader created by ``Popen(start_new_session=True)``."""
identity = capture_process_identity(pid)
if (
identity.uid != os.getuid()
or identity.process_group != pid
or identity.session_id != pid
):
raise ContainmentError("provider process is not a new bound session leader")
return identity
def _process_group_members(process_group: int) -> tuple[int, ...]:
library = _libproc()
capacity = 64
while capacity <= MAX_GROUP_MEMBERS:
values = (ctypes.c_int * capacity)()
size = library.proc_listpgrppids(
process_group, ctypes.byref(values), ctypes.sizeof(values),
)
if size < 0:
raise ContainmentError("provider process group is unavailable")
# Unlike proc_pidinfo(), proc_listpgrppids() returns a PID count.
count = size
if count < capacity:
return tuple(sorted({int(values[index]) for index in range(count) if values[index] > 1}))
capacity *= 2
raise ContainmentError("provider process group exceeds the cleanup bound")
def _bind_group_members(root: ProcessIdentity) -> tuple[ProcessIdentity, ...]:
# A member may exit after proc_listpgrppids() reports it but before its
# identity is queried. Re-list that race; never treat an unbound PID as a
# group member and never signal until one complete pass is stable.
for _attempt in range(32):
members: list[ProcessIdentity] = []
retry = False
for pid in _process_group_members(root.process_group):
try:
current = capture_process_identity(pid)
except ContainmentError:
retry = True
break
if (
current.uid != root.uid
or current.process_group != root.process_group
or current.session_id != root.session_id
or (current.start_seconds, current.start_microseconds)
< (root.start_seconds, root.start_microseconds)
):
raise ContainmentError("contained process group identity drifted")
members.append(current)
if retry:
time.sleep(0.005)
continue
live_root = next((item for item in members if item.pid == root.pid), None)
if live_root is not None and live_root != root:
raise ContainmentError("contained root PID was reused")
return tuple(members)
raise ContainmentError("contained process group changed during binding")
def process_group_is_quiescent(root: ProcessIdentity) -> bool:
"""Return true when the bound group is empty, without a lineage claim.
A child can create another session through posix_spawn attributes even
though direct setsid/setpgid syscalls are denied. Such a child retains this
Seatbelt profile but is outside this process-group cleanup primitive.
"""
return not _bind_group_members(root)
def terminate_bound_process_group(
root: ProcessIdentity, number: int = signal.SIGKILL,
) -> tuple[ProcessIdentity, ...]:
"""Signal only members of the exact new session rooted at ``root``.
Direct ``setsid`` and ``setpgid`` syscalls are denied, but posix_spawn
session/group attributes are a confirmed bypass. This function covers only
processes still in the bound group. It binds and re-checks every current
member before ``killpg``; a PID-reused or unrelated group is rejected
instead of signalled. Escaped descendants retain filesystem/network
containment but are outside this cleanup primitive.
"""
if number not in {signal.SIGTERM, signal.SIGKILL}:
raise ContainmentError("cleanup signal is invalid")
members = _bind_group_members(root)
if not members:
return ()
# A surviving member with the bound session ID proves this is still the
# original session even if its leader has already exited.
for item in members:
if capture_process_identity(item.pid) != item:
raise ContainmentError("provider process changed before cleanup")
try:
os.killpg(root.process_group, number)
except ProcessLookupError:
return ()
except OSError as exc:
raise ContainmentError("provider process-group cleanup failed") from exc
return members
def write_login_preferences(home: Path) -> None:
"""Point an empty private HOME at the dedicated Keychain for the one-time sign-in."""
keychain = _dedicated_keychain()
preferences = home / "Library" / "Preferences"
_ensure_private_directory(home / "Library", existing_ok=True)
_ensure_private_directory(preferences, existing_ok=True)
_publish_private_file(
preferences / "com.apple.security.plist",
_default_keychain_preferences_payload(keychain),
)
def main(argv: Sequence[str]) -> int:
"""Shell entry: ``keychain-preflight`` or ``keychain-login-home PRIVATE_HOME``."""
try:
require_supported_host()
if list(argv) == ["keychain-preflight"]:
_dedicated_keychain()
elif len(argv) == 2 and argv[0] == "keychain-login-home":
write_login_preferences(Path(argv[1]))
else:
print("usage: keychain-preflight | keychain-login-home PRIVATE_HOME", file=sys.stderr)
return 64
except ContainmentError as exc:
print(f"agy-worker: {exc}", file=sys.stderr)
return EXIT_NATIVE_HOST_UNAVAILABLE
return 0
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |