claude-dev-env 2.3.0 → 2.4.0

package/skills/prototype/scripts/probe_sandbox_safety.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""Prove both sandbox safety hooks block their probe payloads before trusting them.
+
+::
+
+    python probe_sandbox_safety.py --settings sandbox-settings.json
+    exit 0  ->  pii_prevention_blocker and destructive_command_blocker both blocked
+    exit 3  ->  one hook allowed its probe payload or errored
+
+The probe reads each safety hook command from the settings, feeds it a
+PreToolUse payload the hook's own tests prove it blocks, and confirms the
+hook returns a hard-deny decision. It runs each hook under the settings'
+``env`` block, so the destructive gate runs in deny mode and its block holds
+the way it does for the launched session. It runs the hook scripts directly,
+so it confirms each script is present, imports its constants package, and
+blocks its probe payload — it does not exercise Claude Code's matcher dispatch.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+from build_sandbox_settings import read_settings_document
+from prototype_scripts_constants.config.build_sandbox_settings_constants import (
+    ALL_SAFETY_HOOK_SCRIPT_BASENAMES,
+    COMMAND_KEY,
+    ENV_KEY,
+    HOOKS_KEY,
+    MATCHER_KEY,
+    PRE_TOOL_USE_KEY,
+)
+from prototype_scripts_constants.config.probe_sandbox_safety_constants import (
+    ALL_DESTRUCTIVE_PROBE_COMMAND_TOKENS,
+    COMMAND_TOKEN_JOIN_SEPARATOR,
+    DESTRUCTIVE_PROBE_TOOL_NAME,
+    ENVELOPE_HOOK_EVENT_NAME_KEY,
+    ENVELOPE_PRE_TOOL_USE_EVENT_NAME,
+    ENVELOPE_PROBE_SESSION_ID,
+    ENVELOPE_SESSION_ID_KEY,
+    ENVELOPE_TOOL_INPUT_KEY,
+    ENVELOPE_TOOL_NAME_KEY,
+    HARD_DENY_DECISION,
+    HOOK_SPECIFIC_REPLY_KEY,
+    MATCHER_JOIN_SEPARATOR,
+    PERMISSION_DECISION_KEY,
+    PII_PROBE_CONTENT_TEMPLATE,
+    PII_PROBE_FILE_PATH,
+    PII_PROBE_TOKEN_BODY_CHARACTER,
+    PII_PROBE_TOKEN_BODY_LENGTH,
+    PII_PROBE_TOKEN_PREFIX,
+    PII_PROBE_TOOL_NAME,
+    PROBE_FAILURE_EXIT_CODE,
+    PROBE_HOOK_TIMEOUT_SECONDS,
+    PROBE_SUCCESS_EXIT_CODE,
+    TOOL_INPUT_COMMAND_KEY,
+    TOOL_INPUT_CONTENT_KEY,
+    TOOL_INPUT_FILE_PATH_KEY,
+)
+from prototype_scripts_constants.config.prototype_common_constants import LOGGING_FORMAT
+
+logger = logging.getLogger("probe_sandbox_safety")
+
+
+def _build_pii_probe_payload() -> dict:
+    synthetic_secret = (
+        PII_PROBE_TOKEN_PREFIX
+        + PII_PROBE_TOKEN_BODY_CHARACTER * PII_PROBE_TOKEN_BODY_LENGTH
+    )
+    probe_content = PII_PROBE_CONTENT_TEMPLATE.format(secret=synthetic_secret)
+    return {
+        ENVELOPE_SESSION_ID_KEY: ENVELOPE_PROBE_SESSION_ID,
+        ENVELOPE_HOOK_EVENT_NAME_KEY: ENVELOPE_PRE_TOOL_USE_EVENT_NAME,
+        ENVELOPE_TOOL_NAME_KEY: PII_PROBE_TOOL_NAME,
+        ENVELOPE_TOOL_INPUT_KEY: {
+            TOOL_INPUT_FILE_PATH_KEY: PII_PROBE_FILE_PATH,
+            TOOL_INPUT_CONTENT_KEY: probe_content,
+        },
+    }
+
+
+def _build_destructive_probe_payload() -> dict:
+    destructive_command = COMMAND_TOKEN_JOIN_SEPARATOR.join(
+        ALL_DESTRUCTIVE_PROBE_COMMAND_TOKENS
+    )
+    return {
+        ENVELOPE_SESSION_ID_KEY: ENVELOPE_PROBE_SESSION_ID,
+        ENVELOPE_HOOK_EVENT_NAME_KEY: ENVELOPE_PRE_TOOL_USE_EVENT_NAME,
+        ENVELOPE_TOOL_NAME_KEY: DESTRUCTIVE_PROBE_TOOL_NAME,
+        ENVELOPE_TOOL_INPUT_KEY: {TOOL_INPUT_COMMAND_KEY: destructive_command},
+    }
+
+
+def build_probe_payload_for_basename(basename: str) -> dict:
+    """Build the PreToolUse probe payload a safety hook is proven to block.
+
+    ::
+
+        "pii_prevention_blocker.py"       -> Write payload carrying a secret
+        "destructive_command_blocker.py"  -> Bash payload carrying rm -rf
+
+    Args:
+        basename: the safety hook script basename to build a payload for.
+
+    Returns:
+        The PreToolUse payload the named hook blocks.
+
+    Raises:
+        ValueError: when the basename names no known safety hook.
+    """
+    if basename == ALL_SAFETY_HOOK_SCRIPT_BASENAMES[0]:
+        return _build_pii_probe_payload()
+    if basename == ALL_SAFETY_HOOK_SCRIPT_BASENAMES[1]:
+        return _build_destructive_probe_payload()
+    raise ValueError(f"no probe payload for hook basename: {basename}")
+
+
+def _command_in_block_for_basename(hook_block: dict, basename: str) -> str | None:
+    for each_subhook in hook_block.get(HOOKS_KEY, []):
+        command = each_subhook.get(COMMAND_KEY, "")
+        if basename in command:
+            return command
+    return None
+
+
+def find_hook_command_for_basename(
+    settings_document: dict, basename: str
+) -> str | None:
+    """Find the first hook command in the settings that runs the named script.
+
+    Args:
+        settings_document: the minimal sandbox settings document.
+        basename: the safety hook script basename to look for.
+
+    Returns:
+        The command string that runs the named script, or None when no
+        hook command names it.
+    """
+    pre_tool_use_blocks = settings_document.get(HOOKS_KEY, {}).get(PRE_TOOL_USE_KEY, [])
+    for each_block in pre_tool_use_blocks:
+        command = _command_in_block_for_basename(each_block, basename)
+        if command is not None:
+            return command
+    return None
+
+
+def settings_environment_overrides(settings_document: dict) -> dict[str, str]:
+    """Read the env-block overrides the settings apply to each hook subprocess.
+
+    ::
+
+        {"env": {deny-mode override}}  ->  that mapping
+        settings with no env block     ->  {}
+
+    Args:
+        settings_document: the minimal sandbox settings document.
+
+    Returns:
+        The env-block mapping keyed by variable name, or an empty mapping when
+        the settings carry no env block.
+    """
+    return settings_document.get(ENV_KEY, {})
+
+
+def _find_matchers_for_basename(settings_document: dict, basename: str) -> list[str]:
+    pre_tool_use_blocks = settings_document.get(HOOKS_KEY, {}).get(PRE_TOOL_USE_KEY, [])
+    all_matchers = []
+    for each_block in pre_tool_use_blocks:
+        names_basename = any(
+            basename in each_subhook.get(COMMAND_KEY, "")
+            for each_subhook in each_block.get(HOOKS_KEY, [])
+        )
+        if names_basename:
+            all_matchers.append(str(each_block.get(MATCHER_KEY)))
+    return all_matchers
+
+
+def parse_command_argv(command: str) -> list[str]:
+    """Split a hook command string into an argument vector, quotes removed.
+
+    ::
+
+        '"py" "a b.py"'  ->  ["py", "a b.py"]
+
+    Args:
+        command: the hook command string from the settings.
+
+    Returns:
+        The argument vector with any surrounding quotes stripped.
+    """
+    all_tokens = shlex.split(command, posix=False)
+    return [each_token.strip('"').strip("'") for each_token in all_tokens]
+
+
+def _run_hook_and_parse_reply(
+    all_command_tokens: list[str],
+    probe_payload: dict,
+    override_by_name: dict[str, str],
+) -> dict | None:
+    child_environment = {**os.environ, **override_by_name}
+    try:
+        completed_process = subprocess.run(
+            all_command_tokens,
+            input=json.dumps(probe_payload),
+            text=True,
+            capture_output=True,
+            timeout=PROBE_HOOK_TIMEOUT_SECONDS,
+            check=False,
+            env=child_environment,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if not completed_process.stdout.strip():
+        return None
+    try:
+        return json.loads(completed_process.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def hook_blocks_probe(
+    all_command_tokens: list[str],
+    probe_payload: dict,
+    override_by_name: dict[str, str],
+) -> bool:
+    """Run a hook against its probe payload and report whether it blocks.
+
+    Args:
+        all_command_tokens: the hook argument vector to run.
+        probe_payload: the PreToolUse payload fed to the hook on stdin.
+        override_by_name: env values keyed by variable name that the settings
+            apply to the hook, overlaid on the current environment first.
+
+    Returns:
+        True when the hook emits a hard-deny decision, False when it asks,
+        allows, emits no decision, or errors.
+    """
+    parsed_hook_reply = _run_hook_and_parse_reply(
+        all_command_tokens, probe_payload, override_by_name
+    )
+    if parsed_hook_reply is None:
+        return False
+    decision = parsed_hook_reply.get(HOOK_SPECIFIC_REPLY_KEY, {}).get(
+        PERMISSION_DECISION_KEY
+    )
+    return decision == HARD_DENY_DECISION
+
+
+def probe_safety_hook(settings_document: dict, basename: str) -> bool:
+    """Probe one safety hook from the settings and report whether it blocks.
+
+    Args:
+        settings_document: the minimal sandbox settings document.
+        basename: the safety hook script basename to probe.
+
+    Returns:
+        True when the hook blocks its probe payload, False otherwise.
+    """
+    command = find_hook_command_for_basename(settings_document, basename)
+    if command is None:
+        logger.error("no hook command in settings runs %s", basename)
+        return False
+    all_matchers = _find_matchers_for_basename(settings_document, basename)
+    logger.info("%s matchers: %s", basename, MATCHER_JOIN_SEPARATOR.join(all_matchers))
+    all_command_tokens = parse_command_argv(command)
+    probe_payload = build_probe_payload_for_basename(basename)
+    override_by_name = settings_environment_overrides(settings_document)
+    return hook_blocks_probe(all_command_tokens, probe_payload, override_by_name)
+
+
+def _parse_arguments(all_arguments: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--settings", required=True, help="the sandbox settings file")
+    return parser.parse_args(all_arguments)
+
+
+def main(all_arguments: list[str] | None = None) -> int:
+    """Probe both safety hooks and report whether the sandbox is contained.
+
+    Args:
+        all_arguments: the command-line arguments, or None to read sys.argv.
+
+    Returns:
+        0 when both safety hooks block their probe payloads, 3 when either
+        allows, errors, or the settings cannot be read.
+    """
+    logging.basicConfig(level=logging.INFO, format=LOGGING_FORMAT)
+    arguments = _parse_arguments(all_arguments)
+    settings_path = Path(arguments.settings).expanduser()
+    try:
+        settings_document = read_settings_document(settings_path)
+    except (OSError, json.JSONDecodeError) as read_error:
+        logger.error("cannot read settings %s: %s", settings_path, read_error)
+        return PROBE_FAILURE_EXIT_CODE
+    all_hook_block_outcomes = [
+        probe_safety_hook(settings_document, each_basename)
+        for each_basename in ALL_SAFETY_HOOK_SCRIPT_BASENAMES
+    ]
+    if all(all_hook_block_outcomes):
+        return PROBE_SUCCESS_EXIT_CODE
+    return PROBE_FAILURE_EXIT_CODE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/prototype/scripts/prototype_scripts_constants/__init__.py

@@ -0,0 +1 @@
+"""Named constants for the prototype skill scripts."""

package/skills/prototype/scripts/prototype_scripts_constants/config/build_sandbox_settings_constants.py

@@ -0,0 +1,41 @@
+"""Constants for the sandbox safety-settings builder.
+
+Groups: the two safety hook script basenames the sandbox keeps, the matchers
+each safety hook must cover, the mapping from basename to those matchers, the
+settings JSON key names, the env-block key with the deny-mode env variable and
+value, the default live settings source, the pretty-print indent, the join
+separator for the missing-basename message, and the exit codes.
+"""
+
+from __future__ import annotations
+
+ALL_SAFETY_HOOK_SCRIPT_BASENAMES = (
+    "pii_prevention_blocker.py",
+    "destructive_command_blocker.py",
+)
+
+ALL_PII_REQUIRED_MATCHERS = ("Write", "Edit", "MultiEdit", "Bash")
+ALL_DESTRUCTIVE_REQUIRED_MATCHERS = ("Bash",)
+
+ALL_REQUIRED_MATCHERS_BY_SAFETY_BASENAME = {
+    ALL_SAFETY_HOOK_SCRIPT_BASENAMES[0]: ALL_PII_REQUIRED_MATCHERS,
+    ALL_SAFETY_HOOK_SCRIPT_BASENAMES[1]: ALL_DESTRUCTIVE_REQUIRED_MATCHERS,
+}
+
+HOOKS_KEY = "hooks"
+PRE_TOOL_USE_KEY = "PreToolUse"
+MATCHER_KEY = "matcher"
+COMMAND_KEY = "command"
+ENV_KEY = "env"
+
+DESTRUCTIVE_DENY_MODE_ENV_VAR = "CLAUDE_DESTRUCTIVE_DENY_MODE"
+DESTRUCTIVE_DENY_MODE_ENV_VALUE = "1"
+
+DEFAULT_SETTINGS_SOURCE = "~/.claude/settings.json"
+JSON_INDENT_SPACES = 2
+
+MISSING_BASENAMES_JOIN_SEPARATOR = ", "
+
+BUILD_SUCCESS_EXIT_CODE = 0
+SETTINGS_MISSING_SAFETY_HOOK_EXIT_CODE = 2
+SETTINGS_SOURCE_UNREADABLE_EXIT_CODE = 2

package/skills/prototype/scripts/prototype_scripts_constants/config/launch_sandbox_constants.py

@@ -0,0 +1,23 @@
+"""Constants for the hookless sandbox launcher.
+
+Groups: the headless claude executable name and its flag tokens, the default
+session timeout, the JSON summary key names, the missing-path exit code, and
+the wall-clock timeout exit code.
+"""
+
+from __future__ import annotations
+
+CLAUDE_EXECUTABLE_NAME = "claude"
+PROMPT_FLAG = "-p"
+BARE_FLAG = "--bare"
+SKIP_PERMISSIONS_FLAG = "--dangerously-skip-permissions"
+SETTINGS_FLAG = "--settings"
+
+DEFAULT_TIMEOUT_SECONDS = 3600
+
+SUMMARY_KEY_WORKTREE = "worktree"
+SUMMARY_KEY_SETTINGS = "settings"
+SUMMARY_KEY_EXIT_CODE = "exit_code"
+
+LAUNCH_MISSING_PATH_EXIT_CODE = 2
+LAUNCH_TIMEOUT_EXIT_CODE = 124

package/skills/prototype/scripts/prototype_scripts_constants/config/probe_sandbox_safety_constants.py

@@ -0,0 +1,45 @@
+"""Constants for the sandbox safety-hook probe.
+
+Groups: the PreToolUse envelope keys and their probe payloads, the tool-input
+keys, the hook decision keys and the block decisions, the join separators, the
+destructive and personal-data probe payloads, the probe hook timeout, and the
+exit codes.
+"""
+
+from __future__ import annotations
+
+ENVELOPE_SESSION_ID_KEY = "session_id"
+ENVELOPE_PROBE_SESSION_ID = "probe"
+ENVELOPE_HOOK_EVENT_NAME_KEY = "hook_event_name"
+ENVELOPE_PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
+ENVELOPE_TOOL_NAME_KEY = "tool_name"
+ENVELOPE_TOOL_INPUT_KEY = "tool_input"
+
+TOOL_INPUT_COMMAND_KEY = "command"
+TOOL_INPUT_FILE_PATH_KEY = "file_path"
+TOOL_INPUT_CONTENT_KEY = "content"
+
+HOOK_SPECIFIC_REPLY_KEY = "hookSpecificOutput"
+PERMISSION_DECISION_KEY = "permissionDecision"
+HARD_DENY_DECISION = "deny"
+
+MATCHER_JOIN_SEPARATOR = ", "
+COMMAND_TOKEN_JOIN_SEPARATOR = " "
+
+DESTRUCTIVE_PROBE_TOOL_NAME = "Bash"
+ALL_DESTRUCTIVE_PROBE_COMMAND_TOKENS = ("rm", "-rf", "/var/log/myapp")
+DESTRUCTIVE_PROBE_COMMAND = COMMAND_TOKEN_JOIN_SEPARATOR.join(
+    ALL_DESTRUCTIVE_PROBE_COMMAND_TOKENS
+)
+
+PII_PROBE_TOOL_NAME = "Write"
+PII_PROBE_FILE_PATH = "src/config.env.example.md"
+PII_PROBE_TOKEN_PREFIX = "ghp" + "_"
+PII_PROBE_TOKEN_BODY_CHARACTER = "C"
+PII_PROBE_TOKEN_BODY_LENGTH = 36
+PII_PROBE_CONTENT_TEMPLATE = "TOKEN={secret}\n"
+
+PROBE_HOOK_TIMEOUT_SECONDS = 30
+
+PROBE_SUCCESS_EXIT_CODE = 0
+PROBE_FAILURE_EXIT_CODE = 3

package/skills/prototype/scripts/prototype_scripts_constants/config/prototype_common_constants.py

@@ -0,0 +1,10 @@
+"""Constants shared by every prototype skill script.
+
+Groups: the log line format the scripts configure, and the text encoding
+for reading the settings source and the sandbox task file.
+"""
+
+from __future__ import annotations
+
+LOGGING_FORMAT = "%(levelname)s %(name)s: %(message)s"
+TEXT_ENCODING_UTF8 = "utf-8"