cmdscope 0.1.0__py3-none-any.whl

cmdscope/privacy.py

@@ -0,0 +1,143 @@
+"""Sanitization and environment-diff helpers.
+
+CmdScope stores metadata, never file contents. Command arguments and environment
+values are still potentially sensitive, so every value passes through this module
+before it reaches SQLite, a report, or a log.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import subprocess
+from collections.abc import Mapping
+
+from cmdscope.core.events import JSONValue
+
+REDACTED = "[REDACTED]"
+
+# Normalized names are compared without punctuation, so AWS_SECRET_ACCESS_KEY,
+# --api-key and clientSecret all match.
+SENSITIVE_MARKERS: tuple[str, ...] = (
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "credential",
+    "apikey",
+    "accesskey",
+    "privatekey",
+    "clientsecret",
+    "authorization",
+    "cookie",
+    "session",
+)
+
+_SENSITIVE_FLAG_RE = re.compile(r"^[-/]{1,2}[A-Za-z0-9_.-]+$")
+_URL_CREDENTIALS_RE = re.compile(r"(://[^/\s:@]+:)([^/\s@]+)(@)")
+_AUTHORIZATION_RE = re.compile(r"(?i)(authorization\s*:\s*(?:bearer|basic|token)?\s*)\S+")
+_BEARER_RE = re.compile(r"(?i)\b(bearer)\s+[A-Za-z0-9._~+/-]+=*")
+_SENSITIVE_QUERY_RE = re.compile(
+    r"(?i)([?&](?:token|api_key|apikey|access_token|secret|password)=)[^&\s]+"
+)
+
+
+def is_sensitive_name(name: str) -> bool:
+    """Return whether a flag or environment-variable name looks sensitive."""
+
+    normalized = re.sub(r"[^a-z0-9]", "", name.lower())
+    return any(marker in normalized for marker in SENSITIVE_MARKERS)
+
+
+def sanitize_env_value(name: str, value: str) -> str:
+    """Redact a value when its variable name is sensitive."""
+
+    return REDACTED if is_sensitive_name(name) else value
+
+
+def sanitize_environment(environment: Mapping[str, str]) -> dict[str, str]:
+    """Return a copy with sensitive values redacted."""
+
+    return {key: sanitize_env_value(key, value) for key, value in environment.items()}
+
+
+def environment_diff(
+    parent: Mapping[str, str],
+    child: Mapping[str, str],
+) -> dict[str, JSONValue]:
+    """Describe added, removed, and changed variables with sanitized values.
+
+    Runtime mutation of an environment block is not observable without native
+    tracing. This diff only compares the environment CmdScope was asked to use
+    for the child with the environment of the CmdScope process.
+    """
+
+    added: dict[str, JSONValue] = {
+        key: sanitize_env_value(key, child[key]) for key in sorted(child.keys() - parent.keys())
+    }
+    removed: list[JSONValue] = [key for key in sorted(parent.keys() - child.keys())]
+    changed: dict[str, JSONValue] = {}
+    for key in sorted(parent.keys() & child.keys()):
+        if parent[key] == child[key]:
+            continue
+        changed[key] = {
+            "before": sanitize_env_value(key, parent[key]),
+            "after": sanitize_env_value(key, child[key]),
+        }
+    return {"added": added, "removed": removed, "changed": changed}
+
+
+def _sanitize_embedded(value: str) -> str:
+    """Redact credentials embedded inside an argument (URLs, headers, queries)."""
+
+    sanitized = _URL_CREDENTIALS_RE.sub(rf"\1{REDACTED}\3", value)
+    sanitized = _AUTHORIZATION_RE.sub(rf"\1{REDACTED}", sanitized)
+    sanitized = _BEARER_RE.sub(rf"\1 {REDACTED}", sanitized)
+    return _SENSITIVE_QUERY_RE.sub(rf"\1{REDACTED}", sanitized)
+
+
+def sanitize_command(argv: tuple[str, ...] | list[str]) -> tuple[str, ...]:
+    """Redact values of sensitive flags, assignments, URLs, and headers."""
+
+    sanitized: list[str] = []
+    redact_next = False
+    for argument in argv:
+        if redact_next:
+            sanitized.append(REDACTED)
+            redact_next = False
+            continue
+
+        handled = False
+        if argument.startswith(("-", "/")):
+            for separator in ("=", ":"):
+                if separator not in argument:
+                    continue
+                flag, _, _value = argument.partition(separator)
+                if is_sensitive_name(flag.lstrip("-/")):
+                    sanitized.append(f"{flag}{separator}{REDACTED}")
+                    handled = True
+                break
+            if handled:
+                continue
+            if _SENSITIVE_FLAG_RE.match(argument) and is_sensitive_name(argument.lstrip("-/")):
+                sanitized.append(argument)
+                redact_next = True
+                continue
+        elif "=" in argument:
+            name, _, _value = argument.partition("=")
+            if is_sensitive_name(name):
+                sanitized.append(f"{name}={REDACTED}")
+                continue
+
+        sanitized.append(_sanitize_embedded(argument))
+    return tuple(sanitized)
+
+
+def format_command(argv: tuple[str, ...] | list[str]) -> str:
+    """Render a sanitized command for display and storage."""
+
+    sanitized = sanitize_command(argv)
+    if os.name == "nt":
+        return subprocess.list2cmdline(list(sanitized))
+    return shlex.join(sanitized)

cmdscope/reports/__init__.py

@@ -0,0 +1 @@
+"""Report renderers."""

cmdscope/reports/html.py

@@ -0,0 +1,279 @@
+"""Self-contained HTML reports with no external assets or scripts."""
+
+from __future__ import annotations
+
+import html
+import json
+from typing import Any
+
+_CSS = """
+:root { color-scheme: light dark; --bg:#f7f8fa; --panel:#fff; --text:#1c2430;
+  --muted:#5b6878; --line:#dfe4ea; --accent:#0b7285; --ok:#2b8a3e; --warn:#b36b00;
+  --fail:#c92a2a; --code:#f1f3f5; }
+@media (prefers-color-scheme: dark) {
+  :root { --bg:#101418; --panel:#171d24; --text:#e7edf3; --muted:#9aa8b6;
+    --line:#2b3540; --accent:#4dabf7; --ok:#69db7c; --warn:#ffc078; --fail:#ff8787;
+    --code:#0d1116; }
+}
+* { box-sizing: border-box; }
+body { margin:0; padding:2rem; background:var(--bg); color:var(--text);
+  font:15px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Arial,sans-serif; }
+main { max-width:1100px; margin:0 auto; }
+h1 { margin:0 0 .2rem; font-size:1.7rem; letter-spacing:-.02em; }
+h2 { margin:2rem 0 .7rem; font-size:1.05rem; text-transform:uppercase;
+  letter-spacing:.08em; color:var(--muted); }
+.sub { color:var(--muted); margin:0 0 1.5rem; }
+.panel { background:var(--panel); border:1px solid var(--line); border-radius:10px;
+  padding:1rem 1.2rem; margin:.8rem 0; }
+.cards { display:grid; grid-template-columns:repeat(auto-fit,minmax(150px,1fr));
+  gap:.7rem; margin:1rem 0; }
+.card { background:var(--panel); border:1px solid var(--line); border-radius:10px;
+  padding:.8rem 1rem; }
+.card .num { font-size:1.5rem; font-weight:650; }
+.card .label { color:var(--muted); font-size:.82rem; text-transform:uppercase;
+  letter-spacing:.06em; }
+table { width:100%; border-collapse:collapse; font-size:.9rem; }
+th,td { text-align:left; padding:.45rem .55rem; border-bottom:1px solid var(--line);
+  vertical-align:top; }
+th { color:var(--muted); font-weight:600; font-size:.78rem; text-transform:uppercase;
+  letter-spacing:.05em; }
+tr:last-child td { border-bottom:none; }
+code,pre { font-family:ui-monospace,SFMono-Regular,Consolas,"Liberation Mono",monospace; }
+code { background:var(--code); padding:.08rem .3rem; border-radius:4px; }
+pre { background:var(--code); border:1px solid var(--line); border-radius:8px;
+  padding:.8rem; overflow:auto; font-size:.82rem; }
+.badge { display:inline-block; padding:.08rem .45rem; border-radius:999px;
+  border:1px solid var(--line); font-size:.75rem; font-weight:600; }
+.ok { color:var(--ok); border-color:var(--ok); }
+.warn { color:var(--warn); border-color:var(--warn); }
+.fail { color:var(--fail); border-color:var(--fail); }
+.muted { color:var(--muted); }
+.empty { color:var(--muted); font-style:italic; }
+ul { margin:.3rem 0 .3rem 1.2rem; padding:0; }
+li { margin:.18rem 0; }
+footer { margin-top:2rem; padding-top:1rem; border-top:1px solid var(--line);
+  color:var(--muted); font-size:.82rem; }
+"""
+
+
+def _e(value: object) -> str:
+    return html.escape("" if value is None else str(value), quote=True)
+
+
+def _iso(value: object) -> str:
+    text = str(value) if value is not None else "-"
+    return text.replace("T", " ").replace("+00:00", " UTC")
+
+
+def _duration(value: object) -> str:
+    if not isinstance(value, (int, float)):
+        return "-"
+    return f"{value * 1000:.0f} ms" if value < 1 else f"{value:.2f} s"
+
+
+def _size(value: object) -> str:
+    if not isinstance(value, int):
+        return "-"
+    size = float(value)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if size < 1024 or unit == "TB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} TB"
+
+
+def _badge(state: str) -> str:
+    css = {"ok": "ok", "degraded": "warn", "failed": "fail", "disabled": "muted"}.get(
+        state, "muted"
+    )
+    return f'<span class="badge {css}">{_e(state)}</span>'
+
+
+def _event_detail(event: dict[str, Any]) -> str:
+    payload = event.get("payload")
+    if not isinstance(payload, dict):
+        return ""
+    kind = str(event.get("kind", ""))
+    if kind.startswith("filesystem."):
+        path = _e(payload.get("path", ""))
+        suffix = " (directory)" if payload.get("is_dir") else f" ({_size(payload.get('size'))})"
+        return f"<code>{path}</code>{suffix}"
+    if kind.startswith("process."):
+        pid = _e(payload.get("pid", "?"))
+        name = _e(payload.get("name", "unknown"))
+        command = _e(payload.get("command", ""))
+        extra = _e(payload.get("reason", ""))
+        lifetime = payload.get("observed_lifetime_s")
+        suffix = f" · {_duration(lifetime)}" if isinstance(lifetime, (int, float)) else ""
+        reason = f" · {extra}" if extra else ""
+        command_html = f" <code>{command}</code>" if command else ""
+        return f"pid {pid} · {name}{command_html}{reason}{suffix}"
+    if kind == "network.connection":
+        process = _e(payload.get("process_name", "unknown"))
+        pid = _e(payload.get("pid", "?"))
+        local = _e(payload.get("local_address") or "-")
+        remote = _e(payload.get("remote_address") or "listening")
+        protocol = _e(payload.get("protocol", "TCP"))
+        status = _e(payload.get("status", "UNKNOWN"))
+        return (
+            f"{process} (pid {pid}) · <code>{local}</code> → <code>{remote}</code> "
+            f"· {protocol} · {status}"
+        )
+    return ""
+
+
+def _event_table(events: list[dict[str, Any]]) -> str:
+    if not events:
+        return '<p class="empty">No events observed in this category.</p>'
+    rows = []
+    for event in events:
+        rows.append(
+            "<tr>"
+            f"<td><code>{_e(event.get('kind'))}</code></td>"
+            f'<td class="muted">{_iso(event.get("occurred_at"))}</td>'
+            f"<td>{_event_detail(event)}</td>"
+            "</tr>"
+        )
+    return (
+        "<table><thead><tr><th>Event</th><th>Observed at</th><th>Details</th></tr></thead>"
+        f"<tbody>{''.join(rows)}</tbody></table>"
+    )
+
+
+def render_html(report: dict[str, Any]) -> str:
+    """Render a report dictionary as a standalone HTML document."""
+
+    session = report.get("session", {})
+    summary = report.get("summary", {})
+    collectors = report.get("collectors", [])
+    events = report.get("events", [])
+    warnings = report.get("warnings", [])
+    limitations = report.get("limitations", [])
+    if not isinstance(session, dict):
+        session = {}
+    if not isinstance(summary, dict):
+        summary = {}
+    if not isinstance(events, list):
+        events = []
+    if not isinstance(collectors, list):
+        collectors = []
+
+    filesystem = [
+        event
+        for event in events
+        if isinstance(event, dict) and str(event.get("kind", "")).startswith("filesystem.")
+    ]
+    processes = [
+        event
+        for event in events
+        if isinstance(event, dict) and str(event.get("kind", "")).startswith("process.")
+    ]
+    network = [
+        event
+        for event in events
+        if isinstance(event, dict) and str(event.get("kind", "")).startswith("network.")
+    ]
+
+    collector_rows = []
+    for collector in collectors:
+        if not isinstance(collector, dict):
+            continue
+        collector_rows.append(
+            "<tr>"
+            f"<td>{_e(collector.get('name'))}</td>"
+            f"<td>{_badge(str(collector.get('state', 'unknown')))}</td>"
+            f"<td>{_e(collector.get('message') or '')}</td>"
+            "</tr>"
+        )
+    collectors_html = (
+        "<table><thead><tr><th>Collector</th><th>State</th><th>Message</th></tr></thead>"
+        f"<tbody>{''.join(collector_rows)}</tbody></table>"
+        if collector_rows
+        else '<p class="empty">No collector status recorded.</p>'
+    )
+
+    warning_html = "".join(f"<li>{_e(item)}</li>" for item in warnings)
+    limitation_html = "".join(f"<li>{_e(item)}</li>" for item in limitations)
+    events_total = summary.get("events_total", len(events))
+    shown_note = ""
+    if report.get("events_shown") is not None and len(events) < int(events_total or 0):
+        shown_note = (
+            f'<p class="muted">Showing {len(events)} of {_e(events_total)} events. '
+            "Use --all to include every event.</p>"
+        )
+
+    environment_html = ""
+    if "environment_diff" in session:
+        environment_html = (
+            "<h2>Environment (initial child diff, sanitized)</h2>"
+            f"<pre>{_e(json.dumps(session.get('environment_diff'), indent=2, ensure_ascii=False))}</pre>"
+        )
+
+    options = session.get("options")
+    watch_roots = "-"
+    if isinstance(options, dict) and isinstance(options.get("watch_roots"), list):
+        watch_roots = ", ".join(str(item) for item in options["watch_roots"])
+
+    title = f"CmdScope report {session.get('ref', '')}".strip()
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{_e(title)}</title>
+<style>{_CSS}</style>
+</head>
+<body>
+<main>
+  <h1>CmdScope execution report</h1>
+  <p class="sub">Session {_e(session.get("ref"))} · generated {_iso(report.get("generated_at"))}</p>
+
+  <div class="cards">
+    <div class="card"><div class="num">{_e(summary.get("filesystem_created"))}</div><div class="label">Files created</div></div>
+    <div class="card"><div class="num">{_e(summary.get("filesystem_modified"))}</div><div class="label">Files modified</div></div>
+    <div class="card"><div class="num">{_e(summary.get("filesystem_deleted"))}</div><div class="label">Files deleted</div></div>
+    <div class="card"><div class="num">{_e(summary.get("processes_started"))}</div><div class="label">Processes started</div></div>
+    <div class="card"><div class="num">{_e(summary.get("network_connections"))}</div><div class="label">Network endpoints</div></div>
+  </div>
+
+  <h2>Session</h2>
+  <div class="panel">
+    <table>
+      <tr><th>Command</th><td><code>{_e(session.get("command_display"))}</code></td></tr>
+      <tr><th>Status</th><td>{_badge(str(session.get("status", "unknown")))}</td></tr>
+      <tr><th>Exit status</th><td>{_e(session.get("exit_code") if session.get("exit_code") is not None else "-")}</td></tr>
+      <tr><th>Directory</th><td><code>{_e(session.get("cwd"))}</code></td></tr>
+      <tr><th>Platform</th><td>{_e(session.get("platform"))}</td></tr>
+      <tr><th>Started</th><td>{_iso(session.get("started_at") or session.get("created_at"))}</td></tr>
+      <tr><th>Duration</th><td>{_duration(session.get("duration_s"))}</td></tr>
+      <tr><th>Watch roots</th><td><code>{_e(watch_roots)}</code></td></tr>
+      {"<tr><th>Error</th><td><code>" + _e(session.get("error")) + "</code></td></tr>" if session.get("error") else ""}
+    </table>
+  </div>
+
+  <h2>Filesystem</h2>
+  <div class="panel">{_event_table(filesystem)}</div>
+
+  <h2>Processes</h2>
+  <div class="panel">{_event_table(processes)}</div>
+
+  <h2>Network</h2>
+  <div class="panel">{_event_table(network)}</div>
+
+  <h2>Collectors</h2>
+  <div class="panel">{collectors_html}</div>
+
+  {environment_html}
+
+  <h2>Limitations</h2>
+  <div class="panel"><ul>{limitation_html}</ul></div>
+
+  <h2>Warnings</h2>
+  <div class="panel"><ul>{warning_html or "<li>None recorded.</li>"}</ul></div>
+
+  {shown_note}
+  <footer>Generated locally by CmdScope. No data was transmitted. CmdScope observes; it does not sandbox.</footer>
+</main>
+</body>
+</html>
+"""

cmdscope/reports/json_report.py

@@ -0,0 +1,133 @@
+"""JSON report builder."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from typing import Any
+
+from cmdscope.analysis.comparison import ComparisonResult
+from cmdscope.core.events import EventKind, StoredEvent
+from cmdscope.core.session import Session, SessionSummary
+
+REPORT_SCHEMA = "cmdscope.report/v1"
+
+
+def _session_dict(session: Session, *, include_environment: bool) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "id": session.id,
+        "ref": session.ref,
+        "status": str(session.status),
+        "command": list(session.command),
+        "command_display": session.command_display,
+        "cwd": session.cwd,
+        "platform": session.platform_name,
+        "created_at": session.created_at.isoformat(),
+        "started_at": session.started_at.isoformat() if session.started_at else None,
+        "ended_at": session.ended_at.isoformat() if session.ended_at else None,
+        "duration_s": session.duration_s,
+        "exit_code": session.exit_code,
+        "interrupted": session.interrupted,
+        "error": session.error,
+        "options": session.options,
+    }
+    if include_environment:
+        result["environment_diff"] = session.env_diff
+    return result
+
+
+def _event_dict(event: StoredEvent) -> dict[str, Any]:
+    return {
+        "id": event.id,
+        "kind": str(event.kind),
+        "occurred_at": event.occurred_at.isoformat(),
+        "source": event.source,
+        "payload": event.payload,
+    }
+
+
+def build_report(
+    session: Session,
+    summary: SessionSummary,
+    events: Sequence[StoredEvent],
+    *,
+    include_environment: bool = False,
+    event_limit: int | None = None,
+    generated_at: datetime | None = None,
+) -> dict[str, Any]:
+    """Build a stable JSON-friendly report document."""
+
+    selected = list(events if event_limit is None else events[:event_limit])
+    return {
+        "schema": REPORT_SCHEMA,
+        "generated_at": (generated_at or datetime.now(UTC)).isoformat(),
+        "session": _session_dict(session, include_environment=include_environment),
+        "summary": {
+            "events_total": summary.events_total,
+            "filesystem_created": summary.filesystem_created,
+            "filesystem_modified": summary.filesystem_modified,
+            "filesystem_deleted": summary.filesystem_deleted,
+            "processes_started": summary.processes_started,
+            "processes_finished": summary.processes_finished,
+            "processes_still_running": summary.processes_still_running,
+            "network_connections": summary.network_connections,
+        },
+        "collectors": [collector.to_dict() for collector in session.collectors],
+        "events": [_event_dict(event) for event in selected],
+        "events_shown": len(selected),
+        "limitations": [
+            "Only changes under the configured watch roots are observed.",
+            "Processes and network sockets are sampled; short-lived ones can be missed.",
+            "File contents are never captured.",
+            "CmdScope is an observability tool, not a sandbox or isolation boundary.",
+            "Runtime environment mutations are not observable externally.",
+        ],
+        "warnings": list(summary.warnings),
+    }
+
+
+def render_json(report: dict[str, Any]) -> str:
+    """Serialize a report deterministically for terminals and files."""
+
+    return json.dumps(report, indent=2, ensure_ascii=False, sort_keys=False) + "\n"
+
+
+def build_comparison_report(result: ComparisonResult) -> dict[str, Any]:
+    """Build the JSON document used by ``cmdscope compare --format json``."""
+
+    def item_dict(item: Any) -> dict[str, str]:
+        return {
+            "category": item.category,
+            "action": item.action,
+            "label": item.label,
+        }
+
+    return {
+        "schema": "cmdscope.comparison/v1",
+        "generated_at": datetime.now(UTC).isoformat(),
+        "session_a": {
+            "id": result.session_a.id,
+            "ref": result.session_a.ref,
+            "command": result.session_a.command_display,
+            "events_total": result.events_a,
+        },
+        "session_b": {
+            "id": result.session_b.id,
+            "ref": result.session_b.ref,
+            "command": result.session_b.command_display,
+            "events_total": result.events_b,
+        },
+        "common_count": result.common_count,
+        "only_in_a": [item_dict(item) for item in result.only_in_a],
+        "only_in_b": [item_dict(item) for item in result.only_in_b],
+        "note": "Comparison uses normalized paths and event signatures; timestamps are ignored.",
+    }
+
+
+def render_comparison_json(result: ComparisonResult) -> str:
+    return json.dumps(build_comparison_report(result), indent=2, ensure_ascii=False) + "\n"
+
+
+def is_network_event(event: StoredEvent) -> bool:
+    return event.kind == EventKind.NETWORK_CONNECTION