damage-control-dev 0.1.0__py3-none-any.whl

damage_control/groups.py

@@ -0,0 +1,114 @@
+"""Rule groups and packs: which bundled rule/tooldef files belong to what (#1141).
+
+Every bundled rules file (generic ``rules/*`` or a host layer such as AgentWire's) and
+every ``tooldefs/*`` belongs to exactly one entry here (entries name the authored ``.yaml``;
+the JSON a hook reads shares its stem). File names must be unique across the rules dirs.
+``kind="group"`` entries are default-on ("os-focused"); a human may opt one out. ``kernel`` groups can never be opted out. ``kind="pack"`` entries are vendor/tool
+sets a human enables (``skipped_stems`` says what an undecided policy loads: no packs but the host's defaults).
+
+The generic registry lives here; what the HOST adds (its own groups, its layer files
+attached to generic groups, the packs it turns on) comes from the installed profile
+(#1209 M3), so the registry has no host names in its logic.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, FrozenSet, List, Optional, Tuple
+
+from damage_control import engine
+from damage_control.profile import GroupSpec as Entry
+
+_GENERIC_ENTRIES = (
+    # --- default groups -----------------------------------------------------
+    Entry("control-plane", "group", "Protected damage-control/agent config paths", ("control-plane.yaml",), kernel=True),
+    Entry("core", "group", "Filesystem, process and history destruction", ("core.yaml",), kernel=True),
+    Entry("git", "group", "Destructive git operations, gh repo delete + git/gh tooldefs", ("git.yaml",), ("git.yaml", "gh.yaml")),
+    Entry("uv", "group", "uv run/publish ask-tier (own group: opting out of git must not drop it)", (), ("uv.yaml",)),
+    Entry("registry", "group", "npm unpublish + npm publish ask-tier", ("registry.yaml",), ("npm.yaml",)),
+    Entry("payloads", "group", "Rules scanning payloads wrapped in other commands", ("payloads.yaml",)),
+    Entry("remote", "group", "ssh-only remote hazards (reboot, service stop)", ("remote.yaml",)),
+    Entry("mcp-tools", "group", "Per-tool policy for MCP tool calls", ("mcp-tools.yaml",)),
+    Entry("outbound", "group", "Outward-facing sends (email, SMS, push)", ("outbound.yaml",)),
+    # --- packs --------------------------------------------------------------
+    Entry("aws", "pack", "AWS CLI", ("aws.yaml",), ("aws.yaml",), binaries=("aws",)),
+    Entry("gcp", "pack", "gcloud", ("gcp.yaml",), ("gcp.yaml",), binaries=("gcloud",)),
+    Entry("firebase", "pack", "Firebase CLI", ("firebase.yaml",), binaries=("firebase",)),
+    Entry("cloud-hosting", "pack", "Vercel, Netlify, Cloudflare, Heroku, Fly, DO, Supabase", ("cloud-hosting.yaml",), binaries=("vercel", "netlify", "wrangler", "heroku", "flyctl", "doctl", "supabase")),
+    Entry("databases", "pack", "Database CLIs and SQL", ("databases.yaml",), binaries=("psql", "mysql", "mongosh", "redis-cli", "prisma", "rails", "alembic", "flyway", "knex", "sequelize")),
+    Entry("containers", "pack", "Docker and Kubernetes", ("containers.yaml",), ("docker.yaml", "kubectl.yaml"), binaries=("docker", "kubectl")),
+    Entry("infrastructure", "pack", "Terraform, Pulumi, Serverless, SAM", ("infrastructure.yaml",), ("terraform.yaml",), binaries=("terraform", "pulumi", "serverless", "sam")),
+    Entry("tmux", "pack", "tmux kill-server / kill-session -a", ("tmux.yaml",), binaries=("tmux",)),
+    Entry("publish", "pack", "cargo/poetry/twine/pnpm/yarn/gem/mvn publish", ("publish.yaml",), binaries=("cargo", "poetry", "twine", "pnpm", "yarn", "gem", "mvn")),
+)
+
+
+def _with_profile(generic: Tuple[Entry, ...], profile) -> Tuple[Entry, ...]:
+    """``generic`` plus what ``profile`` adds: layer files on generic groups, then its own groups."""
+    layers = dict(profile.group_layer_rules)
+    unknown = sorted(set(layers) - {e.name for e in generic})
+    if unknown:
+        raise ValueError(f"profile {profile.name!r} adds rule files to unknown groups: {unknown}")
+    attached = tuple(e._replace(layer_rules=e.layer_rules + layers.get(e.name, ())) for e in generic)
+    return attached + tuple(profile.groups)
+
+
+def entries() -> Tuple[Entry, ...]:
+    """Every group and pack of THIS process: the generic registry plus what its profile adds."""
+    return _with_profile(_GENERIC_ENTRIES, engine.PROFILE)
+
+
+def registry() -> Dict[str, Entry]:
+    return {e.name: e for e in entries()}
+
+
+def default_packs() -> Tuple[str, ...]:
+    """Packs the host turns on for itself."""
+    return tuple(engine.PROFILE.default_packs)
+
+
+def skipped_stems(packs: Optional[List[str]], disabled_groups: List[str]) -> Tuple[FrozenSet[str], FrozenSet[str]]:
+    """``(rules stems, tooldef stems)`` of the bundled files switched off by the policy.
+
+    ``packs`` None means the policy has no ``packs:`` key (undecided; an unreadable policy never gets here, the loader supplies every pack): the
+    default groups are on and only the HOST's default packs load (none for the generic profile),
+    never "everything off" (#1209 M5, section 4.5). A machine that has decided lists its packs.
+    A kernel group is never skipped.
+    """
+    if packs is None:
+        packs = list(default_packs())
+    rules: set = set()
+    tooldefs: set = set()
+    for e in entries():
+        if e.kind == "pack":
+            active = e.name in packs
+        else:
+            active = e.kernel or e.name not in disabled_groups
+        if not active:
+            rules.update(Path(f).stem for f in e.files("rules"))
+            tooldefs.update(Path(f).stem for f in e.files("tooldefs"))
+    return frozenset(rules), frozenset(tooldefs)
+
+
+def bundled_files() -> Dict[str, set]:
+    """The ``{"rules": {...}, "tooldefs": {...}}`` file stems actually bundled (generic + profile layers)."""
+    return {
+        "rules": {p.stem for d in engine.bundled_rule_sources() for p in engine._data_files(d)},
+        "tooldefs": {p.stem for p in engine._data_files(engine.bundled_tooldefs_dir())},
+    }
+
+
+def unclassified() -> Dict[str, list]:
+    """Bundled files owned by no entry, or by more than one, per section."""
+    bundled = bundled_files()
+    out: Dict[str, list] = {}
+    for section in ("rules", "tooldefs"):
+        owners: Dict[str, list] = {}
+        for e in entries():
+            for f in e.files(section):
+                owners.setdefault(Path(f).stem, []).append(e.name)
+        bad = [f"{f}: owned by {owners.get(f, [])}" for f in sorted(bundled[section] | set(owners))
+               if f not in bundled[section] or len(owners.get(f, [])) != 1]
+        if bad:
+            out[section] = bad
+    return out

damage_control/harness_config.py

@@ -0,0 +1,205 @@
+"""The one read-modify-write path for a harness's JSON settings file (#1209 M5, section 5).
+
+Generalizes what #1220 fixed in agentwire. The file belongs to the user and to other tools,
+never to us, so every edit goes through :func:`edit_json_config`:
+
+* **Unparseable input is a refusal, never a rewrite** (:class:`ConfigError`). Replacing a file
+  we could not read with ``{}`` deletes every other setting the user has.
+* **Structural merge.** The caller's ``mutate`` edits the parsed dict in place and returns True
+  when it changed something; nothing here knows what a hook is.
+* **The user's formatting survives**: BOM, CRLF, indent width and a missing trailing newline are
+  detected and re-applied, so an edit changes the lines it means to change.
+* **Atomic write**: temp file in the same directory, ``fsync``, ``os.replace``, ``fsync`` of the
+  directory. A crash (or ``kill -9``) leaves the old file or the new one, never a partial one.
+* **Concurrent-writer detection**: the bytes are re-read just before the replace and again
+  after it. If another writer got in between, the edit is recomputed from the new bytes once,
+  then refused.
+* **Backup** of the original, once, never overwritten.
+
+Standard library only.
+"""
+
+import contextlib
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any, Callable, Dict, NamedTuple, Optional, Tuple
+
+_ATTEMPTS = 2
+
+
+class ConfigError(RuntimeError):
+    """The config file could not be safely edited; nothing was written."""
+
+
+class EditResult(NamedTuple):
+    changed: bool
+    created: bool  # the file did not exist before this edit
+    sha256: Optional[str]  # of the bytes now on disk (None if the file is absent)
+
+
+class Style(NamedTuple):
+    bom: bool = False
+    crlf: bool = False
+    indent: int = 2
+    trailing_newline: bool = True
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def resolve(path: Path) -> Path:
+    """Edit through a symlink (dotfile managers) instead of replacing it."""
+    return path.resolve() if path.is_symlink() else path
+
+
+def read_bytes(path: Path) -> Optional[bytes]:
+    try:
+        return path.read_bytes()
+    except FileNotFoundError:
+        return None
+    except OSError as e:
+        raise ConfigError(f"cannot read {path}: {e}") from e
+
+
+def _strict_constant(name: str) -> Any:
+    raise ValueError(f"{name} is not valid JSON")
+
+
+def parse(raw: Optional[bytes], path: Path) -> Dict[str, Any]:
+    """The JSON object in ``raw`` ({} for absent or empty). Anything else is a refusal."""
+    if raw is None or not raw.strip():
+        return {}
+    try:
+        parsed = json.loads(raw.decode("utf-8-sig"), parse_constant=_strict_constant)
+    except ValueError as e:  # JSONDecodeError and UnicodeDecodeError
+        raise ConfigError(f"{path} is not valid JSON ({e}); left untouched. Fix the file and re-run.") from e
+    if not isinstance(parsed, dict):
+        raise ConfigError(f"{path} is not a JSON object; left untouched. Fix the file and re-run.")
+    return parsed
+
+
+def read_config(path: Path) -> Tuple[Optional[bytes], Dict[str, Any]]:
+    """``(raw bytes or None if absent, parsed object)``. Read-only; refuses what it cannot parse."""
+    raw = read_bytes(resolve(path))
+    return raw, parse(raw, path)
+
+
+def detect_style(raw: Optional[bytes]) -> Style:
+    if not raw or not raw.strip():
+        return Style()
+    bom = raw.startswith(b"\xef\xbb\xbf")
+    text = raw.decode("utf-8-sig", errors="replace")
+    crlf = "\r\n" in text
+    indent = 2
+    for line in text.splitlines()[1:]:
+        stripped = line.lstrip(" ")
+        if stripped and stripped != line:
+            indent = len(line) - len(stripped)
+            break
+    return Style(bom=bom, crlf=crlf, indent=indent, trailing_newline=text.endswith("\n"))
+
+
+def render(settings: Dict[str, Any], style: Style) -> bytes:
+    text = json.dumps(settings, indent=style.indent, ensure_ascii=False)
+    if style.trailing_newline:
+        text += "\n"
+    if style.crlf:
+        text = text.replace("\n", "\r\n")
+    data = text.encode("utf-8")
+    return b"\xef\xbb\xbf" + data if style.bom else data
+
+
+def atomic_replace(path: Path, data: bytes, expected: Optional[bytes]) -> bool:
+    """Write ``data`` over ``path`` atomically iff its bytes are still ``expected``.
+
+    Returns False (writing nothing) when the file changed since it was read. Preserves the
+    existing file's mode. The temp file never outlives the call.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        if path.exists():
+            shutil.copymode(path, tmp)
+        if read_bytes(path) != expected:
+            return False
+        os.replace(tmp, path)
+        _fsync_dir(path.parent)
+        return True
+    finally:
+        tmp.unlink(missing_ok=True)
+
+
+def _fsync_dir(directory: Path) -> None:
+    with contextlib.suppress(OSError):
+        fd = os.open(directory, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+
+
+def _backup_once(path: Path, raw: Optional[bytes], backup: Optional[Path]) -> None:
+    if backup is None or raw is None or backup.exists():
+        return
+    backup.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(path, backup)
+
+
+def edit_json_config(
+    path: Path,
+    mutate: Callable[[Dict[str, Any]], bool],
+    backup: Optional[Path] = None,
+) -> EditResult:
+    """Apply ``mutate`` to the parsed config at ``path`` and persist it if it reports a change.
+
+    Raises :class:`ConfigError` (writing nothing) for unparseable input, a read-only file,
+    or a file that keeps changing underneath the edit. A write is re-read and verified.
+    """
+    path = resolve(Path(path))
+    for _ in range(_ATTEMPTS):
+        raw = read_bytes(path)
+        settings = parse(raw, path)
+        if raw is not None and not os.access(path, os.W_OK):
+            raise ConfigError(f"{path} is not writable; left untouched.")
+        if not mutate(settings):
+            return EditResult(False, False, None if raw is None else sha256_hex(raw))
+        data = render(settings, detect_style(raw))
+        _backup_once(path, raw, backup)
+        try:
+            replaced = atomic_replace(path, data, raw)
+        except OSError as e:
+            raise ConfigError(f"cannot write {path}: {e}; nothing written.") from e
+        if not replaced:
+            continue  # changed since we read it: recompute from the new bytes
+        if read_bytes(path) != data:
+            raise ConfigError(f"{path} was changed by another writer right after the edit; re-run to verify.")
+        return EditResult(True, raw is None, sha256_hex(data))
+    raise ConfigError(f"{path} kept changing while it was being edited; nothing written. Re-run.")
+
+
+def restore_bytes(path: Path, data: Optional[bytes], expected_sha256: str) -> bool:
+    """Put ``data`` back (or delete the file if ``data`` is None) iff the file is still what we wrote.
+
+    The byte-exact half of uninstall. Returns False when the file has changed since
+    ``expected_sha256``, so the caller falls back to a structural removal.
+    """
+    path = resolve(Path(path))
+    current = read_bytes(path)
+    if current is None or sha256_hex(current) != expected_sha256:
+        return False
+    if data is None:
+        if read_bytes(path) != current:
+            return False
+        path.unlink()
+        return True
+    return atomic_replace(path, data, current)

damage_control/hook.py

@@ -0,0 +1,54 @@
+"""The Claude Code hook entry: ``python -I -m damage_control.hook <kind> [--profile PATH]``.
+
+This file is the bootstrap wrapper, and it imports nothing but ``os`` and ``sys`` at module
+level. Python exits 1 when an import fails or an exception escapes, and Claude Code treats
+exit 1 as "no decision" (the tool call RUNS). The only exit that stops a call is 2, so every
+way this process can fail before the real hook is running is caught here and turned into 2:
+an unimportable engine, a half-upgraded install, a syntax error in a rules module.
+
+What it cannot catch is a failure BEFORE this file runs (no interpreter, no ``damage_control``
+package). That is what ``"onFailure": "block"`` in the registration is for.
+
+``-I`` is mandatory, not a tidy-up: ``python -m`` puts the working directory first on
+``sys.path``, and that tree is writable by the agent being policed, so a planted ``json.py``
+would be imported as the hook's own ``json``. ``-I`` also drops ``PYTHON*`` variables and the
+user site directory.
+"""
+
+import os
+import sys
+
+
+def _block(reason: str) -> None:
+    """Exit 2 whatever state stderr is in."""
+    try:
+        sys.stderr.write(f"SECURITY: Blocked: damage-control hook could not start ({reason}) — failing closed\n")
+        sys.stderr.flush()
+    finally:
+        os._exit(2)
+
+
+def _excepthook(exc_type, exc, tb) -> None:
+    try:
+        import traceback
+
+        traceback.print_exception(exc_type, exc, tb)
+    except BaseException:
+        pass
+    _block(f"{exc_type.__name__}: {exc}")
+
+
+sys.excepthook = _excepthook
+
+
+def main(argv) -> None:
+    try:
+        from damage_control.adapter import run_hook
+    except BaseException as e:  # SystemExit and KeyboardInterrupt included: nothing may exit 0 or 1 here
+        _block(f"import failed: {type(e).__name__}: {e}")
+        return
+    run_hook(argv)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])