copysec 0.9.9__py3-none-any.whl

copysec/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

copysec/__main__.py

@@ -0,0 +1,6 @@
+from copysec.cli import main
+
+__all__ = ["main"]
+
+if __name__ == "__main__":
+    raise SystemExit(main())

copysec/audit.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import time
+from pathlib import Path
+
+
+class Audit:
+    MIN_INTERVAL = 1.0
+    MAX_FILE_BYTES = 1_000_000
+    MAX_DIR_BYTES = 10_000_000
+    TARGET_DIR_BYTES = 5_000_000
+
+    def __init__(self, log_dir: Path, log_allows: bool = False, verbose: bool = False):
+        import os
+
+        self.log_allows = log_allows
+        self.verbose = verbose
+        self.debug = os.environ.get("COPYSEC_DEBUG") == "1"
+        if self.debug:
+            self.log_allows = True
+        self._log_dir = Path(log_dir)
+        try:
+            self._log_dir.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            self._log_dir = None
+        self._last: dict[tuple, float] = {}
+        self._dropped: dict[tuple, int] = {}
+        self._prune()
+
+    def _prune(self) -> None:
+        if self._log_dir is None:
+            return
+        try:
+            sized = []
+            total = 0
+            for path in sorted(self._log_dir.glob("audit-*.jsonl")):
+                try:
+                    st = path.stat()
+                except OSError:
+                    continue
+                sized.append((st.st_mtime, path.name, st.st_size, path))
+                total += st.st_size
+            if total <= self.MAX_DIR_BYTES:
+                return
+            freed = 0
+            removed = 0
+            for _, _, size, path in sorted(sized):
+                if total - freed <= self.TARGET_DIR_BYTES:
+                    break
+                try:
+                    path.unlink()
+                except OSError:
+                    continue
+                freed += size
+                removed += 1
+            if removed:
+                self.event("logs_pruned", removed=removed, freed_bytes=freed)
+        except OSError:
+            pass
+
+    def _path(self) -> Path | None:
+        if self._log_dir is None:
+            return None
+        day = _dt.datetime.now().astimezone().date().strftime("%Y%m%d")
+        base = f"audit-{day}"
+        path = self._log_dir / f"{base}.jsonl"
+        seq = 0
+        try:
+            while path.exists() and path.stat().st_size >= self.MAX_FILE_BYTES:
+                seq += 1
+                path = self._log_dir / f"{base}.{seq}.jsonl"
+        except OSError:
+            return None
+        return path
+
+    def _write(self, record: dict) -> None:
+        record.setdefault("ts", _dt.datetime.now().astimezone().isoformat(timespec="milliseconds"))
+        line = json.dumps(record, ensure_ascii=False)
+        path = self._path()
+        if path is not None:
+            try:
+                with open(path, "a", encoding="utf-8") as fh:
+                    fh.write(line + "\n")
+            except OSError:
+                pass
+        if self.verbose:
+            try:
+                print(line, flush=True)
+            except (OSError, UnicodeEncodeError):
+                pass
+
+    def _rate_ok(self, key: tuple) -> bool:
+        now = time.monotonic()
+        last = self._last.get(key)
+        if last is not None and now - last < self.MIN_INTERVAL:
+            self._dropped[key] = self._dropped.get(key, 0) + 1
+            return False
+        self._last[key] = now
+        return True
+
+    @staticmethod
+    def _proc_dict(info) -> dict | None:
+        if info is None:
+            return None
+        record = {"pid": info.pid, "exe": info.exe}
+        if getattr(info, "host_pid", None):
+            record["host_pid"] = info.host_pid
+        return record
+
+    def access(
+        self,
+        allowed: bool,
+        rule: str,
+        fmt: int,
+        fmt_name: str,
+        requester=None,
+        foreground=None,
+    ) -> None:
+        if allowed and not self.log_allows:
+            return
+        key = ("access", allowed, getattr(requester, "pid", None), fmt)
+        if not self._rate_ok(key):
+            return
+        record = {
+            "event": "allow" if allowed else "deny",
+            "rule": rule,
+            "fmt": fmt,
+            "fmt_name": fmt_name,
+            "requester": self._proc_dict(requester),
+            "foreground": self._proc_dict(foreground),
+        }
+        dropped = self._dropped.pop(key, None)
+        if dropped:
+            record["suppressed_repeats"] = dropped
+        self._write(record)
+
+    def event(self, name: str, rate_key: str | None = None, **fields) -> None:
+        if rate_key is not None:
+            key = ("event", rate_key)
+            if not self._rate_ok(key):
+                return
+            dropped = self._dropped.pop(key, None)
+            if dropped:
+                fields["suppressed_repeats"] = dropped
+        self._write({"event": name, **fields})
+
+    def probe(self, **fields) -> None:
+        if self.debug:
+            self._write({"event": "probe", **fields})

copysec/cli.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+
+from .audit import Audit
+from .config import default_config_path, load_or_create
+from .guard import ClipboardGuard
+from .policy import Policy
+from .proctree import PsutilProcTree
+from .store import ContentStore
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="copysec",
+        description="Clipboard guard: only the active application and its process tree can access the clipboard.",
+    )
+    parser.add_argument("--no-tray", action="store_true", help="Run without the tray icon")
+    parser.add_argument("--verbose", action="store_true", help="Also echo log records to the console")
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        help="Path to config.json (default: %%LOCALAPPDATA%%\\CopySec\\config.json)",
+    )
+    parser.add_argument(
+        "--smoke-seconds",
+        type=float,
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    return parser
+
+
+def main(argv=None) -> int:
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, OSError):
+        pass
+
+    args = _build_parser().parse_args(argv)
+    config_path = args.config or default_config_path()
+    cfg = load_or_create(config_path)
+    log_dir = config_path.parent / "logs"
+
+    audit = Audit(log_dir, log_allows=cfg.log_allows, verbose=args.verbose)
+    tree = PsutilProcTree()
+
+    def resolve_name(pid):
+        info = tree.resolve(pid)
+        return info.exe if info else None
+
+    policy = Policy(
+        tree,
+        allowlist=set(cfg.allowlist),
+        allow_uwp_frame_host=cfg.allow_uwp_frame_host,
+        deny_unknown_requester=cfg.deny_unknown_requester,
+    )
+    store = ContentStore(audit, resolve_name)
+    guard = ClipboardGuard(policy, store, audit)
+
+    audit.event(
+        "started",
+        pid=os.getpid(),
+        python=sys.version.split()[0],
+        config=str(config_path),
+    )
+    guard.start()
+    if not guard.hwnd:
+        print("[copysec] Failed to create guard window. See logs for details.", file=sys.stderr)
+        return 1
+    guard.request_adopt()
+
+    print(f"[copysec] protection active | pid={os.getpid()}", flush=True)
+    print(f"[copysec] config : {config_path}", flush=True)
+    print(f"[copysec] logs   : {log_dir}", flush=True)
+    print("[copysec] to stop: Ctrl+C (console) or tray > Exit", flush=True)
+
+    exit_code = 0
+    try:
+        if args.no_tray or args.smoke_seconds is not None:
+            deadline = (
+                time.monotonic() + args.smoke_seconds
+                if args.smoke_seconds is not None
+                else None
+            )
+            while guard.is_alive:
+                if deadline is not None and time.monotonic() >= deadline:
+                    break
+                time.sleep(0.2)
+        else:
+            from .tray import TrayApp
+
+            TrayApp(guard, log_dir).run()
+    except KeyboardInterrupt:
+        print("\n[copysec] shutting down...", flush=True)
+    finally:
+        guard.stop()
+        if guard.thread:
+            guard.thread.join(timeout=5)
+        audit.event("stopped")
+    return exit_code

copysec/config.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Config:
+    allowlist: list[str] = field(default_factory=lambda: ["svchost.exe"])
+    allow_uwp_frame_host: bool = False
+    deny_unknown_requester: bool = True
+    log_allows: bool = False
+
+    def apply_dict(self, data: dict) -> None:
+        if not isinstance(data, dict):
+            return
+        if isinstance(data.get("allowlist"), list):
+            self.allowlist = [str(x) for x in data["allowlist"]]
+        for key in ("allow_uwp_frame_host", "deny_unknown_requester", "log_allows"):
+            if key in data and isinstance(data[key], bool):
+                setattr(self, key, data[key])
+
+
+def default_config_path() -> Path:
+    local = os.environ.get("LOCALAPPDATA")
+    base = Path(local) if local else Path.home() / "AppData" / "Local"
+    return base / "CopySec" / "config.json"
+
+
+def load_or_create(path: Path) -> Config:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    cfg = Config()
+    if path.exists():
+        try:
+            cfg.apply_dict(json.loads(path.read_text(encoding="utf-8-sig")))
+        except (OSError, json.JSONDecodeError):
+            pass
+    else:
+        try:
+            path.write_text(
+                json.dumps(asdict(cfg), indent=2) + "\n", encoding="utf-8"
+            )
+        except OSError:
+            pass
+    return cfg

copysec/guard.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import threading
+import time
+import traceback
+
+from . import winapi
+from .stats import RollingStats
+from .winapi import (
+    MSG,
+    WM_APP,
+    WM_CLIPBOARDUPDATE,
+    WM_DESTROY,
+    WM_QUIT,
+    WM_RENDERALLFORMATS,
+    WM_RENDERFORMAT,
+    WM_TIMER,
+    WNDCLASSW,
+    byref,
+    c_wchar_p,
+)
+
+
+class ClipboardGuard:
+    CMD_PAUSE = WM_APP + 1
+    CMD_RESUME = WM_APP + 2
+    CMD_ADOPT = WM_APP + 3
+    CMD_REARM = WM_APP + 4
+
+    WINDOW_CLASS = "CopySecGuardWindowClass"
+    TIMER_ID = 1
+    TIMER_INTERVAL_MS = 2000
+    REARM_TIMER_ID = 2
+    REARM_RETRY_MS = 500
+
+    def __init__(self, policy, store, audit):
+        self.policy = policy
+        self.store = store
+        self.audit = audit
+        self.paused = False
+        self.hwnd = None
+        self.thread = None
+        self._tid = 0
+        self._ready = threading.Event()
+        self._rearm_fail_streak = 0
+        self.rearm_stats = RollingStats()
+        self._fail_started: float | None = None
+        self._proc = winapi.WNDPROC(self._dispatch)
+
+    @property
+    def is_alive(self) -> bool:
+        return bool(self.thread and self.thread.is_alive())
+
+    def start(self) -> threading.Thread:
+        self.thread = threading.Thread(target=self._run, name="copysec-guard", daemon=True)
+        self.thread.start()
+        self._ready.wait(timeout=5.0)
+        return self.thread
+
+    def stop(self) -> None:
+        if self._tid:
+            winapi.user32.PostThreadMessageW(self._tid, WM_QUIT, 0, 0)
+
+    def pause(self) -> None:
+        self._post(self.CMD_PAUSE)
+
+    def resume(self) -> None:
+        self._post(self.CMD_RESUME)
+
+    def request_adopt(self) -> None:
+        self._post(self.CMD_ADOPT)
+
+    def _post(self, cmd: int) -> bool:
+        if not self.hwnd:
+            return False
+        return bool(winapi.user32.PostMessageW(self.hwnd, cmd, 0, 0))
+
+    def _run(self) -> None:
+        self._tid = winapi.kernel32.GetCurrentThreadId()
+        instance = winapi.kernel32.GetModuleHandleW(None)
+        wc = WNDCLASSW()
+        wc.lpfnWndProc = self._proc
+        wc.hInstance = instance
+        wc.lpszClassName = c_wchar_p(self.WINDOW_CLASS)
+        if not winapi.user32.RegisterClassW(byref(wc)):
+            self.audit.event("fatal", reason="register-class-failed")
+            self._ready.set()
+            return
+        hwnd = winapi.user32.CreateWindowExW(
+            0,
+            c_wchar_p(self.WINDOW_CLASS),
+            c_wchar_p("CopySec"),
+            0,
+            0,
+            0,
+            0,
+            0,
+            None,
+            None,
+            instance,
+            None,
+        )
+        if not hwnd:
+            self.audit.event("fatal", reason="create-window-failed")
+            self._ready.set()
+            return
+        self.hwnd = hwnd
+        if not winapi.user32.AddClipboardFormatListener(hwnd):
+            self.audit.event("fatal", reason="listener-failed")
+            self._ready.set()
+            return
+        winapi.user32.SetTimer(hwnd, self.TIMER_ID, self.TIMER_INTERVAL_MS, None)
+        self._ready.set()
+        msg = MSG()
+        try:
+            while True:
+                if winapi.user32.GetMessageW(byref(msg), None, 0, 0) <= 0:
+                    break
+                winapi.user32.TranslateMessage(byref(msg))
+                winapi.user32.DispatchMessageW(byref(msg))
+        except BaseException as exc:  # noqa: BLE001
+            try:
+                self.audit.event("fatal", reason="pump-crash", error=repr(exc))
+            except Exception:  # noqa: BLE001, S110
+                pass
+        finally:
+            winapi.user32.KillTimer(hwnd, self.TIMER_ID)
+            winapi.user32.KillTimer(hwnd, self.REARM_TIMER_ID)
+            winapi.user32.RemoveClipboardFormatListener(hwnd)
+            if not winapi.user32.DestroyWindow(hwnd) and self.store.active:
+                self.store.flush_back()
+        self.hwnd = None
+
+    def _dispatch(self, hwnd, msg, wparam, lparam) -> int:
+        try:
+            if msg == WM_CLIPBOARDUPDATE:
+                self._on_update()
+                return 0
+            if msg == WM_RENDERFORMAT:
+                self._on_render(int(wparam))
+                return 0
+            if msg == WM_RENDERALLFORMATS:
+                self._on_renderall()
+                return 0
+            if msg == WM_TIMER:
+                if wparam == self.TIMER_ID:
+                    self._on_timer()
+                    return 0
+                if wparam == self.REARM_TIMER_ID:
+                    winapi.user32.KillTimer(hwnd, self.REARM_TIMER_ID)
+                    self._on_rearm()
+                    return 0
+            if msg == WM_DESTROY:
+                self._on_destroy()
+                return 0
+            if msg == self.CMD_PAUSE:
+                self._on_pause()
+                return 0
+            if msg == self.CMD_RESUME:
+                self._on_resume()
+                return 0
+            if msg == self.CMD_ADOPT:
+                self._on_update(force=True)
+                return 0
+            if msg == self.CMD_REARM:
+                self._on_rearm()
+                return 0
+        except Exception as exc:  # noqa: BLE001
+            traceback.print_exc()
+            try:
+                self.audit.event("handler_error", msg=hex(msg), error=repr(exc))
+            except Exception:  # noqa: BLE001, S110
+                pass
+        return winapi.user32.DefWindowProcW(hwnd, msg, wparam, lparam)
+
+    def _owner_is_us(self) -> bool:
+        return self.hwnd is not None and winapi.clipboard_owner_hwnd() == self.hwnd
+
+    def _on_update(self, force: bool = False) -> None:
+        if self.paused and not force:
+            return
+        if self._owner_is_us():
+            return
+        if not self.store.adopt(self.hwnd):
+            self.audit.event("adopt_failed", rate_key="adopt_failed")
+
+    def _on_timer(self) -> None:
+        if self.paused:
+            return
+        if self.store.pending_rearm:
+            self._post(self.CMD_REARM)
+            return
+        if not self._owner_is_us():
+            self._on_update()
+
+    def _on_rearm(self) -> None:
+        if self.paused:
+            self._fail_started = None
+            return
+        if winapi.open_clipboard_window_hwnd() is not None:
+            self._rearm_retry("clipboard-busy")
+            return
+        t0 = time.perf_counter()
+        ok = self.store.rearm_delayed(self.hwnd)
+        dur_ms = (time.perf_counter() - t0) * 1000.0
+        if ok:
+            fails = self._rearm_fail_streak
+            self._rearm_fail_streak = 0
+            settle_ms = None
+            if self._fail_started is not None:
+                settle_ms = round((time.monotonic() - self._fail_started) * 1000.0, 1)
+                self._fail_started = None
+            if self.hwnd:
+                winapi.user32.KillTimer(self.hwnd, self.REARM_TIMER_ID)
+            last_ms, avg_ms = self.rearm_stats.add(dur_ms)
+            fields = {
+                "failed_attempts": fails,
+                "dur_ms": last_ms,
+                "avg_ms": avg_ms,
+                "samples": self.rearm_stats.count(),
+            }
+            if settle_ms is not None:
+                fields["settle_ms"] = settle_ms
+            self.audit.event("rearmed", rate_key="rearmed", **fields)
+        else:
+            self._rearm_retry("open-failed")
+
+    def _rearm_retry(self, reason: str) -> None:
+        self._rearm_fail_streak += 1
+        if self._fail_started is None:
+            self._fail_started = time.monotonic()
+        n = self._rearm_fail_streak
+        if n == 1 or n % 20 == 0:
+            self.audit.event(
+                "rearm_failed", rate_key="rearm_failed", consecutive=n, reason=reason
+            )
+        if self.hwnd:
+            winapi.user32.SetTimer(self.hwnd, self.REARM_TIMER_ID, self.REARM_RETRY_MS, None)
+
+    def _on_render(self, fmt: int) -> None:
+        self.audit.probe(stage="render-start", fmt=fmt)
+        requester_hwnd = winapi.open_clipboard_window_hwnd()
+        requester_pid = winapi.window_pid(requester_hwnd)
+        decision = self.policy.decide(requester_pid)
+        name = winapi.format_name(fmt)
+        rendered = None
+        if decision.allowed:
+            rendered = self.store.render(fmt)
+            if not rendered:
+                self.audit.event(
+                    "unsupported_format",
+                    fmt=fmt,
+                    fmt_name=name,
+                    rule=decision.rule,
+                )
+            else:
+                self._post(self.CMD_REARM)
+        self.audit.probe(
+            stage="render-done",
+            fmt=fmt,
+            requester_pid=requester_pid,
+            rule=decision.rule,
+            allowed=decision.allowed,
+            rendered=rendered,
+        )
+        self.audit.access(
+            allowed=decision.allowed,
+            rule=decision.rule,
+            fmt=fmt,
+            fmt_name=name,
+            requester=decision.requester,
+            foreground=decision.foreground,
+        )
+
+    def _on_renderall(self) -> None:
+        self.audit.probe(stage="renderall")
+        if self.store.active:
+            self.store.flush_back(self.hwnd)
+
+    def _on_destroy(self) -> None:
+        self.audit.probe(stage="destroy")
+        if not self.paused and self._owner_is_us() and self.store.active:
+            self.store.flush_back(self.hwnd)
+
+    def _on_pause(self) -> None:
+        self.paused = True
+        if self._owner_is_us() and self.store.active:
+            self.store.flush_back(self.hwnd)
+        self.audit.event("paused")
+
+    def _on_resume(self) -> None:
+        self.paused = False
+        self.audit.event("resumed")
+        if not self._owner_is_us():
+            self._on_update()

copysec/policy.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ProcInfo:
+    pid: int
+    exe: str
+    host_pid: int | None = None
+
+    @property
+    def exe_lower(self) -> str:
+        return self.exe.lower()
+
+
+@dataclass(frozen=True)
+class Decision:
+    allowed: bool
+    rule: str
+    requester: ProcInfo | None
+    foreground: ProcInfo | None
+
+
+class Policy:
+    def __init__(
+        self,
+        tree,
+        allowlist: set[str] | None = None,
+        allow_uwp_frame_host: bool = False,
+        deny_unknown_requester: bool = True,
+        self_pid: int | None = None,
+    ):
+        self.tree = tree
+        self.allowlist = {a.lower() for a in (allowlist or set())}
+        self.allow_uwp_frame_host = allow_uwp_frame_host
+        self.deny_unknown_requester = deny_unknown_requester
+        self.self_pid = os.getpid() if self_pid is None else self_pid
+
+    def decide(self, requester_pid: int | None) -> Decision:
+        fg = self.tree.foreground()
+        if requester_pid is None:
+            if self.deny_unknown_requester:
+                return Decision(False, "unknown-requester", None, fg)
+            return Decision(True, "unknown-requester-allowed", None, fg)
+        if requester_pid == self.self_pid:
+            return Decision(True, "self", None, fg)
+        req = self.tree.resolve(requester_pid)
+        if req is None:
+            return Decision(False, "unresolvable-requester", None, fg)
+        if req.exe_lower in self.allowlist:
+            return Decision(True, "allowlist", req, fg)
+        if fg is not None:
+            if requester_pid == fg.pid:
+                return Decision(True, "foreground-window", req, fg)
+            if fg.pid in self.tree.ancestors(requester_pid):
+                return Decision(True, "descendant-of-foreground", req, fg)
+        if self.allow_uwp_frame_host and req.exe_lower == "applicationframehost.exe":
+            return Decision(True, "uwp-frame-host", req, fg)
+        return Decision(False, "no-match", req, fg)