ripperdoc 0.1.0__py3-none-any.whl

ripperdoc/utils/permissions/path_validation_utils.py

@@ -0,0 +1,165 @@
+"""Path validation utilities for shell commands (cd/ls/find)."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Set
+
+from ripperdoc.utils.safe_get_cwd import safe_get_cwd
+from ripperdoc.utils.shell_token_utils import parse_and_clean_shell_tokens
+
+_GLOB_PATTERN = re.compile(r"[*?\[\]{}]")
+_MAX_VISIBLE_ITEMS = 5
+
+
+@dataclass
+class ValidationResponse:
+    behavior: str  # 'passthrough' | 'ask' | 'deny'
+    message: str
+    rule_suggestions: None | list[str] = None
+
+
+def _format_allowed_dirs_preview(allowed_dirs: Iterable[str]) -> str:
+    dirs = list(allowed_dirs)
+    if len(dirs) <= _MAX_VISIBLE_ITEMS:
+        return ", ".join(f"'{item}'" for item in dirs)
+    return (
+        ", ".join(f"'{item}'" for item in dirs[:_MAX_VISIBLE_ITEMS])
+        + f", and {len(dirs) - _MAX_VISIBLE_ITEMS} more"
+    )
+
+
+def _expand_tilde(path_str: str) -> str:
+    if path_str == "~" or path_str.startswith("~/"):
+        return os.path.expanduser(path_str)
+    return path_str
+
+
+def _resolve_path(raw_path: str, cwd: str) -> Path:
+    expanded = _expand_tilde(raw_path.strip("'\""))
+    candidate = Path(expanded)
+    if not candidate.is_absolute():
+        candidate = Path(cwd) / candidate
+    try:
+        return candidate.resolve()
+    except Exception:
+        return candidate
+
+
+def _extract_directory_from_glob(glob_pattern: str) -> str:
+    match = _GLOB_PATTERN.search(glob_pattern)
+    if not match or match.start() == 0:
+        return glob_pattern
+    prefix = glob_pattern[: match.start()]
+    if "/" not in prefix:
+        return "."
+    return prefix.rsplit("/", 1)[0] or "/"
+
+
+def _is_path_allowed(resolved_path: Path, allowed_dirs: Set[str]) -> bool:
+    resolved_str = str(resolved_path)
+    for allowed in allowed_dirs:
+        normalized_allowed = os.path.abspath(allowed)
+        normalized = os.path.abspath(resolved_str)
+        if normalized == normalized_allowed:
+            return True
+        if normalized.startswith(normalized_allowed.rstrip(os.sep) + os.sep):
+            return True
+    return False
+
+
+def _validate_path(raw_path: str, cwd: str, allowed_dirs: Set[str]) -> tuple[bool, str]:
+    expanded = _expand_tilde(raw_path.strip() or ".")
+    if _GLOB_PATTERN.search(expanded):
+        directory = _extract_directory_from_glob(expanded)
+        resolved_dir = _resolve_path(directory, cwd)
+        return _is_path_allowed(resolved_dir, allowed_dirs), str(resolved_dir)
+
+    resolved = _resolve_path(expanded, cwd)
+    return _is_path_allowed(resolved, allowed_dirs), str(resolved)
+
+
+def _extract_paths_for_command(
+    command: str, args: List[str], cwd: str, allowed_dirs: Set[str]
+) -> ValidationResponse:
+    if command == "cd":
+        target = args[0] if args else os.path.expanduser("~")
+        allowed, resolved = _validate_path(target, cwd, allowed_dirs)
+    elif command == "ls":
+        candidates = [arg for arg in args if not arg.startswith("-")] or ["."]
+        for candidate in candidates:
+            allowed, resolved = _validate_path(candidate, cwd, allowed_dirs)
+            if not allowed:
+                break
+    elif command == "find":
+        paths: list[str] = []
+        for arg in args:
+            if arg.startswith("-"):
+                continue
+            paths.append(arg)
+        if not paths:
+            paths = ["."]
+        allowed = True
+        resolved = ""
+        for candidate in paths:
+            allowed, resolved = _validate_path(candidate, cwd, allowed_dirs)
+            if not allowed:
+                break
+    else:
+        return ValidationResponse(
+            behavior="passthrough",
+            message=f"Command '{command}' is not path-restricted",
+            rule_suggestions=None,
+        )
+
+    if allowed:
+        return ValidationResponse(
+            behavior="passthrough",
+            message="Path validation passed",
+            rule_suggestions=None,
+        )
+
+    preview = _format_allowed_dirs_preview(sorted(allowed_dirs))
+    action = {
+        "cd": "change directories to",
+        "ls": "list files in",
+        "find": "search files in",
+    }.get(command, "access")
+    return ValidationResponse(
+        behavior="ask",
+        message=f"{command} in '{resolved}' was blocked. For security, this session may only {action} the allowed working directories: {preview}.",
+        rule_suggestions=None,
+    )
+
+
+def validate_shell_command_paths(
+    shell_command: str | object, cwd: str | None = None, allowed_dirs: Set[str] | None = None
+) -> ValidationResponse:
+    """Validate path-oriented shell commands against allowed working directories."""
+    command_str = shell_command.command if hasattr(shell_command, "command") else str(shell_command)
+    cwd = cwd or safe_get_cwd()
+    allowed_dirs = allowed_dirs or {cwd}
+
+    tokens = parse_and_clean_shell_tokens(command_str)
+    if not tokens:
+        return ValidationResponse(
+            behavior="passthrough",
+            message="Empty command - no paths to validate",
+            rule_suggestions=None,
+        )
+
+    first, *rest = tokens
+    if first not in {"cd", "ls", "find"}:
+        return ValidationResponse(
+            behavior="passthrough",
+            message=f"Command '{first}' is not a path-restricted command",
+            rule_suggestions=None,
+        )
+
+    return _extract_paths_for_command(first, rest, cwd, allowed_dirs)
+
+
+__all__ = ["ValidationResponse", "validate_shell_command_paths"]

ripperdoc/utils/permissions/shell_command_validation.py

@@ -0,0 +1,74 @@
+"""Lightweight shell command validation heuristics."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass
+class ValidationResult:
+    behavior: str  # 'passthrough' | 'ask' | 'allow' | 'deny'
+    message: str
+    rule_suggestions: Optional[List[str]] = None
+
+
+_DANGEROUS_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"[`‵]"), "Command contains backticks for command substitution"),
+    (re.compile(r"\$\("), "Command contains $() command substitution"),
+    (re.compile(r"\$\{"), "Command contains ${} parameter substitution"),
+    (re.compile(r"<\("), "Command contains process substitution <()"),
+    (re.compile(r">\("), "Command contains process substitution >()"),
+    (re.compile(r"<<<?"), "Command contains heredoc redirection"),
+    (re.compile(r"(^|\s)source\s+"), "Command sources another script"),
+]
+
+
+def validate_shell_command(shell_command: str) -> ValidationResult:
+    """Validate a shell command for risky constructs."""
+    if not shell_command or not shell_command.strip():
+        return ValidationResult(
+            behavior="passthrough",
+            message="Empty command is safe",
+            rule_suggestions=None,
+        )
+
+    trimmed = shell_command.strip()
+
+    if re.search(r"\bjq\b.*\bsystem\s*\(", trimmed):
+        return ValidationResult(
+            behavior="ask",
+            message="jq command contains system() which executes arbitrary commands",
+            rule_suggestions=None,
+        )
+
+    if re.search(r"\b(cat|tee)\s+<<\s*['\"]?EOF", trimmed):
+        return ValidationResult(
+            behavior="ask",
+            message="Command contains heredoc which may run arbitrary content",
+            rule_suggestions=None,
+        )
+
+    if re.search(r"[<>]\s*/dev/null", trimmed):
+        # Explicit /dev/null redirection is benign for our purposes.
+        sanitized = re.sub(r"\s*[<>]\s*/dev/null", "", trimmed)
+    else:
+        sanitized = trimmed
+
+    for pattern, message in _DANGEROUS_PATTERNS:
+        if pattern.search(sanitized):
+            return ValidationResult(
+                behavior="ask",
+                message=message,
+                rule_suggestions=None,
+            )
+
+    return ValidationResult(
+        behavior="passthrough",
+        message="Command passed validation",
+        rule_suggestions=None,
+    )
+
+
+__all__ = ["validate_shell_command", "ValidationResult"]

ripperdoc/utils/permissions/tool_permission_utils.py

@@ -0,0 +1,279 @@
+"""Permission evaluation helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterable, List, Optional, Set
+
+from ripperdoc.utils.permissions.path_validation_utils import validate_shell_command_paths
+from ripperdoc.utils.permissions.shell_command_validation import validate_shell_command
+from ripperdoc.utils.safe_get_cwd import safe_get_cwd
+from ripperdoc.utils.shell_token_utils import parse_and_clean_shell_tokens, parse_shell_tokens
+
+
+@dataclass
+class ToolRule:
+    tool_name: str
+    rule_content: str
+    behavior: str = "allow"
+
+
+@dataclass
+class PermissionDecision:
+    behavior: str  # 'allow' | 'deny' | 'ask' | 'passthrough'
+    message: Optional[str] = None
+    updated_input: Optional[object] = None
+    decision_reason: Optional[dict] = None
+    rule_suggestions: Optional[List[ToolRule] | List[str]] = None
+
+
+def create_wildcard_rule(rule_name: str) -> str:
+    """Create a wildcard/prefix rule string."""
+    return f"{rule_name}:*"
+
+
+def create_tool_rule(rule_content: str) -> List[ToolRule]:
+    return [ToolRule(tool_name="Bash", rule_content=rule_content)]
+
+
+def create_wildcard_tool_rule(rule_name: str) -> List[ToolRule]:
+    return [ToolRule(tool_name="Bash", rule_content=create_wildcard_rule(rule_name))]
+
+
+def extract_rule_prefix(rule_string: str) -> Optional[str]:
+    return rule_string[:-2] if rule_string.endswith(":*") else None
+
+
+def match_rule(command: str, rule: str) -> bool:
+    """Return True if a command matches a rule (exact or wildcard)."""
+    command = command.strip()
+    if not command:
+        return False
+    prefix = extract_rule_prefix(rule)
+    if prefix is not None:
+        return command.startswith(prefix)
+    return command == rule
+
+
+def _merge_rules(*rules: Iterable[str]) -> Set[str]:
+    merged: Set[str] = set()
+    for collection in rules:
+        merged.update(collection)
+    return merged
+
+
+def _is_command_read_only(
+    command: str,
+    injection_check: Callable[[str], bool],
+) -> bool:
+    """Heuristic read-only detector mirroring the reference intent."""
+    validation = validate_shell_command(command)
+    if validation.behavior != "passthrough":
+        return False
+
+    cleaned_tokens = parse_and_clean_shell_tokens(command)
+    if not cleaned_tokens:
+        return True
+
+    # Treat pipelines/compound commands as read-only only if every segment is safe.
+    tokens = parse_shell_tokens(command)
+    if "|" in tokens:
+        parts: list[str] = []
+        current: list[str] = []
+        for token in tokens:
+            if token == "|":
+                if current:
+                    parts.append(" ".join(current))
+                current = []
+            else:
+                current.append(token)
+        if current:
+            parts.append(" ".join(current))
+        return all(_is_command_read_only(part, injection_check) for part in parts)
+
+    dangerous_prefixes = {
+        "rm",
+        "mv",
+        "chmod",
+        "chown",
+        "sudo",
+        "dd",
+        "tee",
+        "truncate",
+        "kill",
+        "pkill",
+        "systemctl",
+        "service",
+    }
+    first = cleaned_tokens[0]
+    if first in dangerous_prefixes:
+        return False
+    if first == "git":
+        if len(cleaned_tokens) < 2:
+            return False
+        allowed_git = {
+            "status",
+            "diff",
+            "show",
+            "log",
+            "rev-parse",
+            "ls-files",
+            "remote",
+            "branch",
+            "tag",
+            "blame",
+            "reflog",
+        }
+        return cleaned_tokens[1] in allowed_git
+
+    # If no injection was detected and the command is free of mutations, treat as read-only.
+    return not injection_check(command)
+
+
+def _collect_rule_suggestions(command: str) -> List[ToolRule]:
+    suggestions: list[ToolRule] = [ToolRule(tool_name="Bash", rule_content=command)]
+    tokens = parse_and_clean_shell_tokens(command)
+    if tokens:
+        suggestions.append(ToolRule(tool_name="Bash", rule_content=create_wildcard_rule(tokens[0])))
+    return suggestions
+
+
+def evaluate_shell_command_permissions(
+    tool_request: object,
+    allowed_rules: Iterable[str],
+    denied_rules: Iterable[str],
+    allowed_working_dirs: Set[str] | None = None,
+    *,
+    command_injection_detected: bool = False,
+    injection_detector: Callable[[str], bool] | None = None,
+    read_only_detector: Callable[[str, Callable[[str], bool]], bool] | None = None,
+) -> PermissionDecision:
+    """Evaluate whether a bash command should be allowed."""
+    command = tool_request.command if hasattr(tool_request, "command") else str(tool_request)
+    trimmed_command = command.strip()
+    allowed_working_dirs = allowed_working_dirs or {safe_get_cwd()}
+    injection_detector = injection_detector or (
+        lambda cmd: validate_shell_command(cmd).behavior != "passthrough"
+    )
+    read_only_detector = read_only_detector or _is_command_read_only
+
+    merged_denied = _merge_rules(denied_rules)
+    merged_allowed = _merge_rules(allowed_rules)
+
+    if any(match_rule(trimmed_command, rule) for rule in merged_denied):
+        return PermissionDecision(
+            behavior="deny",
+            message=f"Permission to run '{trimmed_command}' has been denied.",
+            decision_reason={"type": "rule"},
+            rule_suggestions=None,
+        )
+
+    if any(match_rule(trimmed_command, rule) for rule in merged_allowed):
+        return PermissionDecision(
+            behavior="allow",
+            updated_input=tool_request,
+            decision_reason={"type": "rule"},
+            message="Command approved by configured rule.",
+        )
+
+    path_result = validate_shell_command_paths(
+        trimmed_command, safe_get_cwd(), allowed_working_dirs
+    )
+    if path_result.behavior != "passthrough":
+        return PermissionDecision(
+            behavior="ask",
+            message=path_result.message,
+            decision_reason={"type": "path_validation"},
+            rule_suggestions=None,
+        )
+
+    validation_result = validate_shell_command(trimmed_command)
+    if validation_result.behavior != "passthrough":
+        return PermissionDecision(
+            behavior="ask",
+            message=validation_result.message,
+            decision_reason={"type": "validation"},
+            rule_suggestions=None,
+        )
+
+    tokens = parse_shell_tokens(trimmed_command)
+    if "|" in tokens:
+        left_tokens = []
+        right_tokens = []
+        pipe_seen = False
+        for token in tokens:
+            if token == "|":
+                pipe_seen = True
+                continue
+            if pipe_seen:
+                right_tokens.append(token)
+            else:
+                left_tokens.append(token)
+        left_command = " ".join(left_tokens).strip()
+        right_command = " ".join(right_tokens).strip()
+
+        left_result = evaluate_shell_command_permissions(
+            type("Cmd", (), {"command": left_command}),
+            merged_allowed,
+            merged_denied,
+            allowed_working_dirs,
+            command_injection_detected=command_injection_detected,
+            injection_detector=injection_detector,
+            read_only_detector=read_only_detector,
+        )
+        right_read_only = read_only_detector(right_command, injection_detector)
+
+        if left_result.behavior == "deny":
+            return left_result
+        if not right_read_only:
+            return PermissionDecision(
+                behavior="ask",
+                message="Pipe right-hand command is not read-only.",
+                decision_reason={"type": "subcommand"},
+                rule_suggestions=_collect_rule_suggestions(right_command),
+            )
+        if left_result.behavior == "allow":
+            return PermissionDecision(
+                behavior="allow",
+                updated_input=tool_request,
+                decision_reason={"type": "subcommand"},
+            )
+        return PermissionDecision(
+            behavior="ask",
+            message="Permission required for piped command.",
+            decision_reason={"type": "subcommand"},
+            rule_suggestions=_collect_rule_suggestions(trimmed_command),
+        )
+
+    if read_only_detector(trimmed_command, injection_detector) and not command_injection_detected:
+        return PermissionDecision(
+            behavior="allow",
+            updated_input=tool_request,
+            decision_reason={"type": "other", "reason": "Read-only command"},
+        )
+
+    return PermissionDecision(
+        behavior="passthrough",
+        message="Command requires permission",
+        decision_reason={"type": "default"},
+        rule_suggestions=_collect_rule_suggestions(trimmed_command),
+    )
+
+
+def is_command_read_only(command: str) -> bool:
+    """Public wrapper to test if a command is read-only using reference heuristics."""
+    return _is_command_read_only(
+        command, lambda cmd: validate_shell_command(cmd).behavior != "passthrough"
+    )
+
+
+__all__ = [
+    "PermissionDecision",
+    "ToolRule",
+    "create_tool_rule",
+    "create_wildcard_tool_rule",
+    "evaluate_shell_command_permissions",
+    "extract_rule_prefix",
+    "match_rule",
+    "is_command_read_only",
+]

ripperdoc/utils/safe_get_cwd.py

@@ -0,0 +1,24 @@
+"""Safe helpers for tracking and restoring the working directory."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_ORIGINAL_CWD = Path(os.getcwd()).resolve()
+
+
+def get_original_cwd() -> str:
+    """Return the process's initial working directory."""
+    return str(_ORIGINAL_CWD)
+
+
+def safe_get_cwd() -> str:
+    """Return the current working directory, falling back to the original on error."""
+    try:
+        return str(Path(os.getcwd()).resolve())
+    except Exception:
+        return get_original_cwd()
+
+
+__all__ = ["get_original_cwd", "safe_get_cwd"]

ripperdoc/utils/sandbox_utils.py

@@ -0,0 +1,38 @@
+"""Sandbox helpers.
+
+The reference uses macOS sandbox-exec profiles; in this environment we
+surface the same API surface but report unavailability by default.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import shutil
+import shlex
+from typing import Callable
+
+
+@dataclass
+class SandboxWrapper:
+    """Represents a wrapped command plus a cleanup callback."""
+
+    final_command: str
+    cleanup: Callable[[], None]
+
+
+def is_sandbox_available() -> bool:
+    """Return whether sandboxed execution is available on this host."""
+    return shutil.which("srt") is not None
+
+
+def create_sandbox_wrapper(command: str) -> SandboxWrapper:
+    """Wrap a command for sandboxed execution or raise if unsupported."""
+    if not is_sandbox_available():
+        raise RuntimeError(
+            "Sandbox mode requested but not available (install @anthropic-ai/sandbox-runtime and ensure 'srt' is on PATH)"
+        )
+    quoted = shlex.quote(command)
+    return SandboxWrapper(final_command=f"srt {quoted}", cleanup=lambda: None)
+
+
+__all__ = ["SandboxWrapper", "is_sandbox_available", "create_sandbox_wrapper"]