cmdscope 0.1.0__py3-none-any.whl

cmdscope/core/registry.py

@@ -0,0 +1,33 @@
+"""Thread-safe registry of PIDs observed for the current session."""
+
+from __future__ import annotations
+
+from threading import Lock
+
+
+class ProcessRegistry:
+    """Share the observed process set between process and network collectors.
+
+    Network attribution depends on this registry. A PID that was never observed
+    is never attributed to the session, even if it holds a connection.
+    """
+
+    def __init__(self) -> None:
+        self._lock = Lock()
+        self._names: dict[int, str] = {}
+
+    def add(self, pid: int, name: str) -> None:
+        with self._lock:
+            self._names[pid] = name
+
+    def remove(self, pid: int) -> None:
+        with self._lock:
+            self._names.pop(pid, None)
+
+    def snapshot(self) -> dict[int, str]:
+        with self._lock:
+            return dict(self._names)
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._names)

cmdscope/core/session.py

@@ -0,0 +1,81 @@
+"""Session and summary models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from cmdscope.core.events import CollectorStatus, JSONValue, SessionStatus
+
+
+def session_ref(session_id: int) -> str:
+    """Format a database session id for humans (``S000001``)."""
+
+    if session_id <= 0:
+        raise ValueError("session id must be positive")
+    return f"S{session_id:06d}"
+
+
+def parse_session_ref(value: str) -> int:
+    """Accept ``1``, ``S1``, or ``S000001`` and return the numeric id."""
+
+    text = value.strip()
+    if text[:1].lower() == "s":
+        text = text[1:]
+    if not text.isdigit() or int(text) <= 0:
+        raise ValueError(f"invalid session reference: {value!r}")
+    return int(text)
+
+
+@dataclass(frozen=True, slots=True)
+class Session:
+    """Persisted metadata for one monitored execution."""
+
+    id: int
+    status: SessionStatus
+    command: tuple[str, ...]
+    command_display: str
+    cwd: str
+    platform_name: str
+    created_at: datetime
+    started_at: datetime | None
+    ended_at: datetime | None
+    duration_s: float | None
+    exit_code: int | None
+    interrupted: bool
+    error: str | None
+    env_diff: dict[str, JSONValue]
+    options: dict[str, JSONValue]
+    collectors: tuple[CollectorStatus, ...] = ()
+
+    @property
+    def ref(self) -> str:
+        return session_ref(self.id)
+
+
+@dataclass(frozen=True, slots=True)
+class SessionSummary:
+    """Counts derived exclusively from stored events and collector status."""
+
+    session: Session
+    events_total: int
+    filesystem_created: int
+    filesystem_modified: int
+    filesystem_deleted: int
+    processes_started: int
+    processes_finished: int
+    processes_still_running: int
+    network_connections: int
+    warnings: tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True, slots=True)
+class RunResult:
+    """Result returned by the session runner."""
+
+    session_id: int
+    exit_code: int
+    interrupted: bool
+    event_count: int
+    events_truncated: bool
+    summary: SessionSummary

cmdscope/diagnostics.py

@@ -0,0 +1,183 @@
+"""Read-only environment diagnostics for ``cmdscope doctor``."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import psutil
+
+from cmdscope import __version__
+from cmdscope.config import Config
+from cmdscope.core.session import session_ref
+from cmdscope.errors import StorageError
+from cmdscope.platforms import current_platform_info, is_elevated
+from cmdscope.storage.sqlite import Storage
+
+
+def _package_version(name: str) -> str:
+    try:
+        return importlib.metadata.version(name)
+    except importlib.metadata.PackageNotFoundError:
+        return "not installed"
+
+
+def _watchdog_info() -> dict[str, Any]:
+    try:
+        from watchdog.observers import Observer
+
+        observer = Observer()
+        return {
+            "available": True,
+            "observer": type(observer).__name__,
+            "error": None,
+        }
+    except Exception as exc:
+        return {"available": False, "observer": None, "error": str(exc)}
+
+
+def _network_sample() -> dict[str, Any]:
+    try:
+        connections = psutil.net_connections(kind="inet")
+    except (psutil.AccessDenied, PermissionError) as exc:
+        return {"available": False, "count": None, "error": str(exc)}
+    except OSError as exc:
+        return {"available": False, "count": None, "error": str(exc)}
+    attributed = sum(1 for connection in connections if getattr(connection, "pid", None))
+    return {"available": True, "count": len(connections), "with_pid": attributed, "error": None}
+
+
+def _database_info(path: Path) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "path": str(path),
+        "parent_writable": os.access(path.parent, os.W_OK),
+        "opened": False,
+        "schema_version": None,
+        "quick_check": None,
+        "size_bytes": None,
+        "error": None,
+    }
+    try:
+        with Storage(path) as storage:
+            result["opened"] = True
+            result["schema_version"] = storage.schema_version()
+            result["quick_check"] = storage.quick_check()
+            result["size_bytes"] = storage.storage_size_bytes()
+    except StorageError as exc:
+        result["error"] = str(exc)
+    return result
+
+
+def collect_diagnostics(config: Config, database: Path) -> dict[str, Any]:
+    """Collect diagnostics without changing machine configuration."""
+
+    info = current_platform_info()
+    inotify_limit: int | None = None
+    if info.name == "linux":
+        try:
+            inotify_limit = int(Path("/proc/sys/fs/inotify/max_user_watches").read_text().strip())
+        except (OSError, ValueError):
+            inotify_limit = None
+
+    diagnostics: dict[str, Any] = {
+        "cmdscope_version": __version__,
+        "python_version": sys.version.split()[0],
+        "executable": sys.executable,
+        "platform": {
+            "name": info.name,
+            "display_name": info.display_name,
+            "filesystem_backend": info.fs_backend,
+            "native_filesystem_events": info.native_filesystem_events,
+            "data_dir": str(info.default_data_dir),
+            "config_dir": str(info.default_config_dir),
+            "default_database": str(info.default_database_path),
+        },
+        "user": {
+            "elevated": is_elevated(),
+            "note": "CmdScope never elevates privileges automatically.",
+        },
+        "dependencies": {
+            "psutil": _package_version("psutil"),
+            "watchdog": _package_version("watchdog"),
+        },
+        "watchdog": _watchdog_info(),
+        "network": _network_sample(),
+        "database": _database_info(database),
+        "configuration": {
+            "source_path": str(config.source_path) if config.source_path else None,
+            "warnings": list(config.warnings),
+        },
+        "inotify_max_user_watches": inotify_limit,
+        "limitations": list(info.notes),
+    }
+    return diagnostics
+
+
+def render_diagnostics(data: dict[str, Any]) -> str:
+    """Render diagnostics as a readable terminal report."""
+
+    platform = data.get("platform", {})
+    user = data.get("user", {})
+    dependencies = data.get("dependencies", {})
+    watchdog = data.get("watchdog", {})
+    network = data.get("network", {})
+    database = data.get("database", {})
+    configuration = data.get("configuration", {})
+    lines = [
+        f"CMDSCOPE - DIAGNOSTICS (v{data.get('cmdscope_version')})",
+        "=" * 70,
+        f"Python:          {data.get('python_version')} ({data.get('executable')})",
+        f"Platform:        {platform.get('display_name')} [{platform.get('name')}]",
+        f"Filesystem:      {platform.get('filesystem_backend')}",
+        f"Data directory:  {platform.get('data_dir')}",
+        f"Config directory:{platform.get('config_dir')}",
+        "",
+        f"psutil:          {dependencies.get('psutil')}",
+        f"watchdog:        {dependencies.get('watchdog')}",
+        f"Observer:        {watchdog.get('observer') or watchdog.get('error')}",
+        f"Elevated:        {'yes' if user.get('elevated') else 'no'}",
+        "",
+        f"Database:        {database.get('path')}",
+        f"  opened:        {database.get('opened')}",
+        f"  schema:        {database.get('schema_version')}",
+        f"  quick check:   {database.get('quick_check')}",
+        f"  size (bytes):  {database.get('size_bytes')}",
+        f"  parent writable: {database.get('parent_writable')}",
+    ]
+    if database.get("error"):
+        lines.append(f"  error:         {database['error']}")
+    lines.extend(
+        [
+            "",
+            f"Network sample:  {network.get('count')} inet sockets "
+            f"({network.get('with_pid')} with a PID)",
+            f"  available:     {network.get('available')}",
+        ]
+    )
+    if network.get("error"):
+        lines.append(f"  error:         {network['error']}")
+    if data.get("inotify_max_user_watches") is not None:
+        lines.append(f"inotify watches: {data['inotify_max_user_watches']}")
+    lines.extend(
+        [
+            "",
+            f"Config source:   {configuration.get('source_path') or 'none (defaults)'}",
+        ]
+    )
+    for warning in configuration.get("warnings", []):
+        lines.append(f"  warning:       {warning}")
+    lines.extend(["", "LIMITATIONS"])
+    for note in data.get("limitations", []):
+        lines.append(f"  - {note}")
+    lines.append("")
+    lines.append("No changes were made to the system. No data was transmitted.")
+    return "\n".join(lines)
+
+
+def session_label(session_id: int) -> str:
+    """Convenience for diagnostics callers; kept tiny and tested."""
+
+    return session_ref(session_id)

cmdscope/errors.py

@@ -0,0 +1,36 @@
+"""Domain exceptions with messages suitable for CLI users."""
+
+from __future__ import annotations
+
+
+class CmdScopeError(Exception):
+    """Base class for expected CmdScope failures."""
+
+
+class ConfigurationError(CmdScopeError):
+    """The configuration file or command-line configuration is invalid."""
+
+
+class StorageError(CmdScopeError):
+    """The local session database cannot be opened or updated."""
+
+
+class SessionNotFoundError(CmdScopeError):
+    """A requested session does not exist."""
+
+
+class ReportExistsError(CmdScopeError):
+    """A report output path already exists and was not explicitly overwritten."""
+
+
+class CommandLaunchError(CmdScopeError):
+    """The monitored command could not be started."""
+
+    def __init__(self, message: str, *, exit_code: int = 1, session_id: int | None = None) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.session_id = session_id
+
+
+class EventLimitReached(Exception):
+    """Internal signal used by the event writer when a session reaches its limit."""

cmdscope/platforms/__init__.py

@@ -0,0 +1,57 @@
+"""Platform selection.
+
+Only Windows is manually validated for the 0.1 series. Linux and macOS use
+the same portable collectors and are exercised by CI.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+
+from cmdscope.platforms import base
+from cmdscope.platforms.base import PlatformInfo
+
+__all__ = [
+    "PlatformInfo",
+    "config_dir",
+    "current_platform_info",
+    "data_dir",
+    "fallback_info",
+    "is_elevated",
+    "prepare_command",
+]
+
+
+def current_platform_info(environment: Mapping[str, str] | None = None) -> PlatformInfo:
+    """Return capabilities for the host running CmdScope."""
+
+    env = os.environ if environment is None else environment
+    platform_key = _platform_key()
+    if platform_key.startswith("win"):
+        from cmdscope.platforms import windows
+
+        return windows.info(env)
+    if platform_key == "darwin":
+        from cmdscope.platforms import macos
+
+        return macos.info(env)
+    if platform_key.startswith("linux"):
+        from cmdscope.platforms import linux
+
+        return linux.info(env)
+    return base.fallback_info(env)
+
+
+def _platform_key() -> str:
+    """Indirection keeps static analyzers from folding platform branches."""
+
+    return sys.platform
+
+
+config_dir = base.config_dir
+data_dir = base.data_dir
+fallback_info = base.fallback_info
+is_elevated = base.is_elevated
+prepare_command = base.prepare_command

cmdscope/platforms/base.py

@@ -0,0 +1,140 @@
+"""Platform-neutral capability and path helpers."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class PlatformInfo:
+    """Static, honest description of what the current platform can observe."""
+
+    name: str
+    display_name: str
+    fs_backend: str
+    native_filesystem_events: bool
+    default_data_dir: Path
+    default_config_dir: Path
+    notes: tuple[str, ...]
+
+    @property
+    def default_database_path(self) -> Path:
+        return self.default_data_dir / "cmdscope.db"
+
+
+def _home(environment: Mapping[str, str], platform_name: str) -> Path:
+    keys = ("USERPROFILE", "HOME") if platform_name == "windows" else ("HOME", "USERPROFILE")
+    for key in keys:
+        value = environment.get(key)
+        if value:
+            return Path(value).expanduser()
+    return Path.home()
+
+
+def data_dir(platform_name: str, environment: Mapping[str, str] | None = None) -> Path:
+    """Return the per-user data directory for *platform_name*.
+
+    The functions accept an environment mapping so tests can validate path
+    behavior on any host without touching the real user profile.
+    """
+
+    env = os.environ if environment is None else environment
+    home = _home(env, platform_name)
+    if platform_name == "windows":
+        base = env.get("LOCALAPPDATA")
+        return (
+            Path(base).expanduser() / "cmdscope"
+            if base
+            else home / "AppData" / "Local" / "cmdscope"
+        )
+    if platform_name == "macos":
+        return home / "Library" / "Application Support" / "cmdscope"
+    base = env.get("XDG_DATA_HOME")
+    return Path(base).expanduser() / "cmdscope" if base else home / ".local" / "share" / "cmdscope"
+
+
+def config_dir(platform_name: str, environment: Mapping[str, str] | None = None) -> Path:
+    """Return the per-user configuration directory for *platform_name*."""
+
+    env = os.environ if environment is None else environment
+    home = _home(env, platform_name)
+    if platform_name == "windows":
+        base = env.get("APPDATA")
+        return (
+            Path(base).expanduser() / "cmdscope"
+            if base
+            else home / "AppData" / "Roaming" / "cmdscope"
+        )
+    if platform_name == "macos":
+        return home / "Library" / "Application Support" / "cmdscope"
+    base = env.get("XDG_CONFIG_HOME")
+    return Path(base).expanduser() / "cmdscope" if base else home / ".config" / "cmdscope"
+
+
+def fallback_info(environment: Mapping[str, str] | None = None) -> PlatformInfo:
+    """Conservative capabilities for an unrecognized POSIX-like platform."""
+
+    env = os.environ if environment is None else environment
+    return PlatformInfo(
+        name="unknown",
+        display_name=f"Unknown ({sys.platform})",
+        fs_backend="polling",
+        native_filesystem_events=False,
+        default_data_dir=data_dir("linux", env),
+        default_config_dir=config_dir("linux", env),
+        notes=(
+            "This platform is not officially supported. CmdScope uses portable polling.",
+            "Only filesystem snapshots inside watch roots are available.",
+        ),
+    )
+
+
+def prepare_command(
+    argv: Sequence[str],
+    environment: Mapping[str, str] | None = None,
+) -> list[str]:
+    """Prepare *argv* for ``subprocess.Popen`` without using ``shell=True``.
+
+    Windows batch shims (``.cmd``/``.bat``) are not directly executable by
+    ``CreateProcess``. For those, CmdScope intentionally launches the user's
+    command through ``cmd.exe /c`` using ``subprocess.list2cmdline`` quoting.
+    This is the only shell indirection in the project and it is documented.
+    """
+
+    if not argv:
+        raise ValueError("command must not be empty")
+
+    env = os.environ if environment is None else environment
+    if os.name != "nt":
+        return list(argv)
+
+    executable = shutil.which(argv[0], path=env.get("PATH")) or argv[0]
+    if executable.lower().endswith((".cmd", ".bat")):
+        comspec = env.get("COMSPEC") or "cmd.exe"
+        return [comspec, "/d", "/s", "/c", subprocess.list2cmdline(list(argv))]
+    return list(argv)
+
+
+def is_elevated() -> bool:
+    """Return whether the current process is elevated. Never attempts elevation."""
+
+    if os.name == "nt":
+        try:
+            ctypes = importlib.import_module("ctypes")
+            windll = getattr(ctypes, "windll", None)
+            if windll is None:  # pragma: no cover - non-Windows typeshed
+                return False
+            return bool(windll.shell32.IsUserAnAdmin())
+        except (AttributeError, OSError):
+            return False
+    geteuid = getattr(os, "geteuid", None)
+    if geteuid is None:  # pragma: no cover - non-POSIX non-Windows host
+        return False
+    return geteuid() == 0

cmdscope/platforms/linux.py

@@ -0,0 +1,28 @@
+"""Linux platform capabilities."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from cmdscope.platforms.base import PlatformInfo, config_dir, data_dir
+
+
+def info(environment: Mapping[str, str] | None = None) -> PlatformInfo:
+    env = os.environ if environment is None else environment
+    return PlatformInfo(
+        name="linux",
+        display_name="Linux",
+        fs_backend="inotify (watchdog)",
+        native_filesystem_events=True,
+        default_data_dir=data_dir("linux", env),
+        default_config_dir=config_dir("linux", env),
+        notes=(
+            "Filesystem events cover only the configured watch roots, recursively.",
+            "inotify watch limits can reduce coverage; CmdScope reports the degraded state.",
+            "Processes are discovered by polling; very short-lived children can be missed.",
+            "Network endpoint ownership for other users may require root privileges.",
+            "eBPF, auditd, and ptrace-based syscall tracing are intentionally not used.",
+            "CmdScope is not a sandbox and does not restrict the monitored command.",
+        ),
+    )

cmdscope/platforms/macos.py

@@ -0,0 +1,26 @@
+"""macOS platform capabilities."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from cmdscope.platforms.base import PlatformInfo, config_dir, data_dir
+
+
+def info(environment: Mapping[str, str] | None = None) -> PlatformInfo:
+    env = os.environ if environment is None else environment
+    return PlatformInfo(
+        name="macos",
+        display_name="macOS",
+        fs_backend="FSEvents/kqueue (watchdog)",
+        native_filesystem_events=True,
+        default_data_dir=data_dir("macos", env),
+        default_config_dir=config_dir("macos", env),
+        notes=(
+            "Filesystem events cover only the configured watch roots, recursively.",
+            "Processes are discovered by polling; very short-lived children can be missed.",
+            "Network endpoint ownership for other users may require root privileges.",
+            "CmdScope is not a sandbox and does not restrict the monitored command.",
+        ),
+    )

cmdscope/platforms/windows.py

@@ -0,0 +1,28 @@
+"""Windows platform capabilities."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from cmdscope.platforms.base import PlatformInfo, config_dir, data_dir
+
+
+def info(environment: Mapping[str, str] | None = None) -> PlatformInfo:
+    env = os.environ if environment is None else environment
+    return PlatformInfo(
+        name="windows",
+        display_name="Windows",
+        fs_backend="ReadDirectoryChangesW (watchdog)",
+        native_filesystem_events=True,
+        default_data_dir=data_dir("windows", env),
+        default_config_dir=config_dir("windows", env),
+        notes=(
+            "Filesystem events cover only the configured watch roots, recursively.",
+            "Processes are discovered by polling; very short-lived children can be missed.",
+            "Network endpoints come from psutil polling; ownership may be incomplete for "
+            "processes owned by other users.",
+            "Environment mutations inside a running process cannot be observed externally.",
+            "CmdScope is not a sandbox and does not restrict the monitored command.",
+        ),
+    )