scc-cli 1.5.3__py3-none-any.whl

scc_cli/__init__.py

@@ -0,0 +1,15 @@
+"""SCC - Sandboxed Claude CLI.
+
+Provide a command-line tool for safely running Claude Code in Docker sandboxes
+with team-specific configurations and worktree management.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("scc-cli")
+except PackageNotFoundError:
+    # Package not installed (e.g., running from source without install)
+    __version__ = "0.0.0-dev"
+
+__author__ = "Cagri Cimen"

scc_cli/audit/__init__.py

@@ -0,0 +1,37 @@
+"""Provide plugin audit module for SCC.
+
+Expose functionality for auditing Claude Code plugins,
+including manifest parsing, file reading, and plugin discovery.
+"""
+
+from scc_cli.audit.parser import (
+    create_missing_result,
+    create_parsed_result,
+    create_plugin_manifests,
+    create_unreadable_result,
+    parse_hooks_content,
+    parse_json_content,
+    parse_mcp_content,
+)
+from scc_cli.audit.reader import (
+    audit_all_plugins,
+    audit_plugin,
+    discover_installed_plugins,
+    read_plugin_manifests,
+)
+
+__all__ = [
+    # Parser functions
+    "create_missing_result",
+    "create_parsed_result",
+    "create_plugin_manifests",
+    "create_unreadable_result",
+    "parse_hooks_content",
+    "parse_json_content",
+    "parse_mcp_content",
+    # Reader functions
+    "audit_all_plugins",
+    "audit_plugin",
+    "discover_installed_plugins",
+    "read_plugin_manifests",
+]

scc_cli/audit/parser.py

@@ -0,0 +1,191 @@
+"""Provide pure functions for parsing plugin manifest files.
+
+Implement parsing logic for:
+- .mcp.json files (MCP server definitions)
+- hooks/hooks.json files (hook definitions)
+
+All functions are pure (no I/O) - file reading is handled elsewhere.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from scc_cli.models.plugin_audit import (
+    HookInfo,
+    ManifestResult,
+    ManifestStatus,
+    MCPServerInfo,
+    ParseError,
+    PluginManifests,
+)
+
+
+def parse_json_content(content: str) -> ManifestResult:
+    """Parse JSON content string into a ManifestResult.
+
+    Args:
+        content: Raw JSON string to parse.
+
+    Returns:
+        ManifestResult with PARSED status if valid JSON,
+        or MALFORMED status with error details if invalid.
+    """
+    try:
+        parsed = json.loads(content)
+        return ManifestResult(
+            status=ManifestStatus.PARSED,
+            content=parsed,
+        )
+    except json.JSONDecodeError as e:
+        return ManifestResult(
+            status=ManifestStatus.MALFORMED,
+            error=ParseError.from_json_error(e),
+        )
+
+
+def parse_mcp_content(content: dict[str, Any]) -> list[MCPServerInfo]:
+    """Extract MCP server information from parsed .mcp.json content.
+
+    Args:
+        content: Parsed JSON content from .mcp.json file.
+
+    Returns:
+        List of MCPServerInfo objects for each declared server.
+    """
+    servers: list[MCPServerInfo] = []
+    mcp_servers = content.get("mcpServers", {})
+
+    for name, config in mcp_servers.items():
+        if not isinstance(config, dict):
+            continue
+
+        # Default transport is 'stdio' when not specified
+        transport = config.get("transport", "stdio")
+
+        servers.append(
+            MCPServerInfo(
+                name=name,
+                transport=transport,
+                command=config.get("command"),
+                url=config.get("url"),
+                description=config.get("description"),
+            )
+        )
+
+    return servers
+
+
+def parse_hooks_content(content: dict[str, Any]) -> list[HookInfo]:
+    """Extract hook information from parsed hooks.json content.
+
+    Args:
+        content: Parsed JSON content from hooks.json file.
+
+    Returns:
+        List of HookInfo objects for each declared hook.
+    """
+    hooks_list: list[HookInfo] = []
+    hooks_config = content.get("hooks", {})
+
+    for event, event_hooks in hooks_config.items():
+        if not isinstance(event_hooks, list):
+            continue
+
+        for hook_group in event_hooks:
+            if not isinstance(hook_group, dict):
+                continue
+
+            matcher = hook_group.get("matcher")
+            hooks = hook_group.get("hooks", [])
+
+            if not isinstance(hooks, list):
+                continue
+
+            for hook in hooks:
+                if not isinstance(hook, dict):
+                    continue
+
+                hook_type = hook.get("type", "unknown")
+                hooks_list.append(
+                    HookInfo(
+                        event=event,
+                        hook_type=hook_type,
+                        matcher=matcher,
+                    )
+                )
+
+    return hooks_list
+
+
+def create_missing_result(path: Path) -> ManifestResult:
+    """Create a ManifestResult for a missing manifest file.
+
+    Args:
+        path: Relative path where manifest was expected.
+
+    Returns:
+        ManifestResult with MISSING status.
+    """
+    return ManifestResult(
+        status=ManifestStatus.MISSING,
+        path=path,
+    )
+
+
+def create_unreadable_result(path: Path, error_message: str) -> ManifestResult:
+    """Create a ManifestResult for an unreadable manifest file.
+
+    Args:
+        path: Relative path to the manifest file.
+        error_message: Description of the read error.
+
+    Returns:
+        ManifestResult with UNREADABLE status.
+    """
+    return ManifestResult(
+        status=ManifestStatus.UNREADABLE,
+        path=path,
+        error_message=error_message,
+    )
+
+
+def create_parsed_result(path: Path, content: dict[str, Any]) -> ManifestResult:
+    """Create a ManifestResult for a successfully parsed manifest.
+
+    Args:
+        path: Relative path to the manifest file.
+        content: Parsed JSON content.
+
+    Returns:
+        ManifestResult with PARSED status.
+    """
+    return ManifestResult(
+        status=ManifestStatus.PARSED,
+        path=path,
+        content=content,
+    )
+
+
+def create_plugin_manifests(
+    mcp_result: ManifestResult,
+    hooks_result: ManifestResult,
+    plugin_json_result: ManifestResult | None = None,
+) -> PluginManifests:
+    """Create a PluginManifests aggregate from individual manifest results.
+
+    Args:
+        mcp_result: Result of parsing .mcp.json.
+        hooks_result: Result of parsing hooks/hooks.json.
+        plugin_json_result: Optional result of parsing .claude-plugin/plugin.json.
+
+    Returns:
+        PluginManifests containing all manifest results.
+    """
+    return PluginManifests(
+        mcp=mcp_result,
+        hooks=hooks_result,
+        plugin_json=plugin_json_result,
+    )

scc_cli/audit/reader.py

@@ -0,0 +1,180 @@
+"""Provide I/O layer for reading plugin manifests and discovering installed plugins.
+
+Implement file system operations for:
+- Reading manifest files from plugin directories
+- Discovering installed plugins from the Claude Code registry
+- Creating audit results for plugins
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from scc_cli.audit.parser import (
+    create_missing_result,
+    create_parsed_result,
+    create_plugin_manifests,
+    create_unreadable_result,
+    parse_json_content,
+)
+from scc_cli.models.plugin_audit import (
+    AuditOutput,
+    ManifestResult,
+    ManifestStatus,
+    PluginAuditResult,
+    PluginManifests,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def read_manifest_file(plugin_dir: Path, relative_path: Path) -> ManifestResult:
+    """Read and parse a manifest file from a plugin directory.
+
+    Args:
+        plugin_dir: Absolute path to the plugin directory.
+        relative_path: Relative path to the manifest file within the plugin.
+
+    Returns:
+        ManifestResult with appropriate status based on file existence,
+        readability, and JSON validity.
+    """
+    full_path = plugin_dir / relative_path
+
+    if not full_path.exists():
+        return create_missing_result(relative_path)
+
+    try:
+        content = full_path.read_text(encoding="utf-8")
+    except PermissionError as e:
+        return create_unreadable_result(relative_path, str(e))
+    except UnicodeDecodeError as e:
+        return create_unreadable_result(relative_path, f"invalid encoding: {e}")
+    except OSError as e:
+        return create_unreadable_result(relative_path, str(e))
+
+    # Parse the JSON content
+    result = parse_json_content(content)
+
+    # Add the path to the result
+    if result.status == ManifestStatus.PARSED:
+        return create_parsed_result(relative_path, result.content)  # type: ignore[arg-type]
+    elif result.status == ManifestStatus.MALFORMED:
+        return ManifestResult(
+            status=ManifestStatus.MALFORMED,
+            path=relative_path,
+            error=result.error,
+        )
+    else:
+        return result
+
+
+def read_plugin_manifests(plugin_dir: Path) -> PluginManifests:
+    """Read all manifest files from a plugin directory.
+
+    Args:
+        plugin_dir: Absolute path to the plugin directory.
+
+    Returns:
+        PluginManifests containing results for all manifest files.
+    """
+    mcp_result = read_manifest_file(plugin_dir, Path(".mcp.json"))
+    hooks_result = read_manifest_file(plugin_dir, Path("hooks/hooks.json"))
+
+    return create_plugin_manifests(mcp_result, hooks_result)
+
+
+def discover_installed_plugins(claude_dir: Path) -> list[dict[str, Any]]:
+    """Discover installed plugins from the Claude Code registry.
+
+    Args:
+        claude_dir: Path to the .claude directory (typically ~/.claude).
+
+    Returns:
+        List of plugin info dictionaries from installed_plugins.json.
+        Returns empty list if registry doesn't exist or is malformed.
+    """
+    registry_path = claude_dir / "plugins" / "installed_plugins.json"
+
+    if not registry_path.exists():
+        return []
+
+    try:
+        content = registry_path.read_text(encoding="utf-8")
+        data = json.loads(content)
+        items: list[dict[str, Any]] = data.get("items", [])
+        return items
+    except (PermissionError, OSError) as e:
+        logger.warning("Cannot read plugin registry: %s", e)
+        return []
+    except json.JSONDecodeError as e:
+        logger.warning("Plugin registry is malformed: %s", e)
+        return []
+
+
+def audit_plugin(plugin_info: dict[str, Any]) -> PluginAuditResult:
+    """Audit a single plugin based on its registry information.
+
+    Args:
+        plugin_info: Plugin info dictionary from installed_plugins.json.
+
+    Returns:
+        PluginAuditResult with manifest parsing results.
+    """
+    name = plugin_info.get("name", "unknown")
+    marketplace = plugin_info.get("marketplace", "unknown")
+    version = plugin_info.get("version", "unknown")
+    install_path_str = plugin_info.get("installPath", "")
+
+    plugin_id = f"{name}@{marketplace}"
+    # Type-safe path creation: only convert if it's a non-empty string
+    install_path = (
+        Path(install_path_str) if isinstance(install_path_str, str) and install_path_str else None
+    )
+
+    # Check if plugin directory exists
+    if install_path is None or not install_path.exists():
+        return PluginAuditResult(
+            plugin_id=plugin_id,
+            plugin_name=name,
+            marketplace=marketplace,
+            version=version,
+            install_path=install_path,
+            installed=False,
+            manifests=None,
+        )
+
+    # Read manifests from the plugin directory
+    manifests = read_plugin_manifests(install_path)
+
+    return PluginAuditResult(
+        plugin_id=plugin_id,
+        plugin_name=name,
+        marketplace=marketplace,
+        version=version,
+        install_path=install_path,
+        installed=True,
+        manifests=manifests,
+    )
+
+
+def audit_all_plugins(claude_dir: Path) -> AuditOutput:
+    """Audit all installed plugins.
+
+    Args:
+        claude_dir: Path to the .claude directory.
+
+    Returns:
+        AuditOutput with results for all plugins.
+    """
+    plugins = discover_installed_plugins(claude_dir)
+    results = [audit_plugin(plugin) for plugin in plugins]
+
+    return AuditOutput(
+        schema_version=1,
+        plugins=results,
+        warnings=[],
+    )

scc_cli/auth.py

@@ -0,0 +1,145 @@
+"""
+Resolve authentication from environment variables and commands.
+
+Consolidate auth logic from remote.py and claude_adapter.py.
+Use safe command execution (no shell=True).
+
+Trust Model:
+- User config auth: Trusted (local file, user controls)
+- Remote org config auth: Less trusted (org admin controls)
+  - command: requires explicit opt-in for remote sources
+
+Security Features:
+- shell=False to prevent shell injection
+- Platform-aware shlex.split() for command parsing
+- Binary validation with shutil.which()
+- Sanitized error messages (no secrets in errors)
+- Reduced timeout (10s instead of 30s)
+"""
+
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AuthResult:
+    """Result of resolving auth spec.
+
+    Attributes:
+        token: The resolved authentication token
+        source: Where the token came from ('env' or 'command')
+        env_name: The environment variable name (if source='env')
+    """
+
+    token: str
+    source: str  # 'env' or 'command'
+    env_name: str | None = None
+
+
+def resolve_auth(
+    auth_spec: str | None,
+    allow_command: bool = True,
+) -> AuthResult | None:
+    """Resolve auth spec to token.
+
+    Supports:
+    - env:VAR_NAME - read from environment variable (always allowed)
+    - command:CMD - execute command (requires allow_command=True)
+    - None or empty - no auth needed
+
+    Args:
+        auth_spec: Auth specification string
+        allow_command: Whether to allow command: specs (default True for
+            user config, should be False for remote org config unless
+            explicitly opted in)
+
+    Returns:
+        AuthResult with token and source, or None if no auth
+
+    Raises:
+        ValueError: Invalid auth spec format or command not allowed
+        RuntimeError: Auth command failed
+    """
+    if not auth_spec or not auth_spec.strip():
+        return None
+
+    auth_spec = auth_spec.strip()
+
+    if auth_spec.startswith("env:"):
+        return _resolve_env_auth(auth_spec)
+
+    if auth_spec.startswith("command:"):
+        if not allow_command:
+            raise ValueError(
+                "command: auth not allowed from remote config. "
+                "Use --allow-remote-commands or SCC_ALLOW_REMOTE_COMMANDS=1"
+            )
+        return _execute_auth_command(auth_spec[8:].strip())
+
+    raise ValueError(f"Invalid auth spec format: {auth_spec}")
+
+
+def _resolve_env_auth(auth_spec: str) -> AuthResult | None:
+    """Resolve env:VAR_NAME auth spec."""
+    var_name = auth_spec[4:].strip()
+    if not var_name:
+        return None
+
+    token = os.environ.get(var_name)
+    if token and token.strip():
+        return AuthResult(token=token.strip(), source="env", env_name=var_name)
+    return None
+
+
+def _execute_auth_command(cmd: str) -> AuthResult | None:
+    """Execute auth command safely (no shell injection).
+
+    SECURITY: Uses shell=False and shlex.split() to prevent shell injection.
+    """
+    if not cmd:
+        return None
+
+    try:
+        # Platform-aware splitting (Windows uses different escaping)
+        use_posix = sys.platform != "win32"
+        args = shlex.split(cmd, posix=use_posix)
+    except ValueError:
+        raise RuntimeError("Invalid auth command syntax") from None
+
+    if not args:
+        return None
+
+    # Validate executable exists (prevents PATH hijacking, clearer errors)
+    executable = shutil.which(args[0])
+    if not executable:
+        raise RuntimeError(f"Auth command executable not found: {args[0]}")
+
+    try:
+        result = subprocess.run(
+            [executable] + args[1:],  # Use resolved absolute path
+            shell=False,  # CRITICAL: No shell interpretation
+            capture_output=True,
+            text=True,
+            timeout=10,  # Reduced from 30s
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return AuthResult(token=result.stdout.strip(), source="command")
+        return None
+    except subprocess.TimeoutExpired:
+        raise RuntimeError("Auth command timed out after 10s")
+    except OSError:
+        # Don't leak command in error (might contain secrets)
+        raise RuntimeError("Auth command failed")
+
+
+def is_remote_command_allowed() -> bool:
+    """Check if command: auth is allowed from remote org config.
+
+    Returns True if SCC_ALLOW_REMOTE_COMMANDS is set to 1, true, or yes.
+    """
+    value = os.environ.get("SCC_ALLOW_REMOTE_COMMANDS", "").lower()
+    return value in ("1", "true", "yes")