clean-room-skill 0.1.0

package/hooks/check-artifact-leakage.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Scan clean-room artifacts for high-risk leakage markers."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+from clean_room_paths import checked_write_paths, load_payload
+
+
+MAX_SCAN_BYTES = 1_000_000
+MAX_DENYLIST_BYTES = 1_000_000
+MAX_DENYLIST_TERMS = 20_000
+MAX_DENYLIST_TERM_LENGTH = 512
+PRIVATE_IDENTIFIER_DENYLIST_ENV = "CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST"
+PUBLIC_NAME_KEYS = {"name", "kind", "compatibility_reason", "visibility"}
+PUBLIC_NAME_VISIBILITIES = {"public", "destination", "protocol", "user-required"}
+NEVER_SCAN_JSON_STRING_KEYS = {
+    "$schema",
+    "allowed_artifacts",
+    "artifact_type",
+    "blocked_material_type",
+    "category",
+    "compatibility_level",
+    "confidence",
+    "coverage",
+    "coverage_status",
+    "created_at",
+    "created_by_role",
+    "domain",
+    "evidence_status",
+    "final_status",
+    "from_domain",
+    "kind",
+    "leakage_risk",
+    "leakage_status",
+    "producer_role",
+    "reviewed_at",
+    "reviewer_role",
+    "role",
+    "schema_status",
+    "schema_validator_version",
+    "selection_basis",
+    "severity",
+    "status",
+    "target_profile",
+    "to_domain",
+    "trust_domain",
+    "visibility",
+}
+DENYLIST_ONLY_JSON_STRING_KEYS = {
+    "affected_artifacts",
+    "artifact",
+    "artifact_hashes",
+    "artifact_id",
+    "artifact_paths",
+    "audit_log_refs",
+    "behavior_spec_refs",
+    "contaminated_artifact_roots",
+    "contaminated_artifacts",
+    "contract_id",
+    "decision_id",
+    "evidence_location_ref",
+    "evidence_refs",
+    "expected_artifacts",
+    "incident_id",
+    "manifest_id",
+    "native_artifacts",
+    "owner",
+    "package_id",
+    "path",
+    "profile_id",
+    "report_id",
+    "reviewed_artifacts",
+    "scenario_id",
+    "sha256",
+    "source_hash",
+    "source_index_ref",
+    "source_index_refs",
+    "source_spec_id",
+    "source_unit_refs",
+    "spec_id",
+    "task_id",
+    "test_id",
+    "ticket_id",
+    "unit_id",
+    "workspace_id",
+}
+SCAN_LIGHT_JSON_STRING_KEYS = {
+    "action",
+    "formatting_rules",
+}
+BLOCKED_PATTERNS = {
+    "raw_diff": re.compile(r"(?m)^(diff --git|@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@)"),
+    "source_fence": re.compile(
+        r"(?m)^```\s*(?:$|(?:c|cc|cpp|go|java|javascript|js|jsx|kotlin|kt|m|mm|objective-c|py|python|rs|rust|swift|ts|tsx|typescript)\b)",
+        re.I,
+    ),
+    "decompiled_marker": re.compile(r"\b(decompiled|jadx|apktool|asar extraction|source excerpt)\b", re.I),
+    "stack_source_line": re.compile(r"\bFile \"[^\"]+\", line \d+|\bat [\w.$<>]+\([^)]*:\d+:\d+\)"),
+}
+IDENTIFIER_PATTERNS = {
+    "package_or_module_identifier": re.compile(r"\b[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*){2,}\b"),
+    "source_like_call": re.compile(r"\b[A-Za-z_][A-Za-z0-9_]{2,}\s*\("),
+    "source_like_scoped_identifier": re.compile(
+        r"\b[A-Za-z_][A-Za-z0-9_]{1,}(?:(?:->|::|#)[A-Za-z_][A-Za-z0-9_]{1,}|(?:\.[A-Za-z_][A-Za-z0-9_]{1,}){2,})\b"
+    ),
+}
+URL_PATTERN = re.compile(r"\b[a-z][a-z0-9+.-]*://[^\s\"')]+", re.I)
+
+
+def is_clean_artifact(path: Path) -> bool:
+    clean_roots = [Path(p).expanduser().resolve() for p in os.environ.get("CLEAN_ROOM_CLEAN_ROOTS", "").split(os.pathsep) if p]
+    if clean_roots and not any(path == root or root in path.parents for root in clean_roots):
+        return False
+    return path.suffix.lower() in {".json", ".md", ".yaml", ".yml", ".txt"}
+
+
+def load_private_identifier_terms() -> tuple[list[str], list[str]]:
+    configured = os.environ.get(PRIVATE_IDENTIFIER_DENYLIST_ENV, "")
+    terms: list[str] = []
+    errors: list[str] = []
+    for item in configured.split(os.pathsep):
+        if not item:
+            continue
+        path = Path(item).expanduser()
+        try:
+            data = path.read_bytes()
+        except OSError as exc:
+            errors.append(f"could not read {PRIVATE_IDENTIFIER_DENYLIST_ENV} file {path}: {exc}")
+            continue
+        if len(data) > MAX_DENYLIST_BYTES:
+            errors.append(f"{PRIVATE_IDENTIFIER_DENYLIST_ENV} file {path} exceeds {MAX_DENYLIST_BYTES} bytes")
+            continue
+        raw_terms = data.decode("utf-8", errors="replace").splitlines()
+        for raw_term in raw_terms:
+            if len(terms) >= MAX_DENYLIST_TERMS:
+                errors.append(f"{PRIVATE_IDENTIFIER_DENYLIST_ENV} exceeds {MAX_DENYLIST_TERMS} terms")
+                return terms, errors
+            term = raw_term.strip()
+            if not term or term.startswith("#") or len(term) < 3:
+                continue
+            if len(term) > MAX_DENYLIST_TERM_LENGTH:
+                errors.append(
+                    f"{PRIVATE_IDENTIFIER_DENYLIST_ENV} term exceeds {MAX_DENYLIST_TERM_LENGTH} characters"
+                )
+                return terms, errors
+            terms.append(term)
+    return terms, errors
+
+
+def private_identifier_pattern(term: str) -> re.Pattern[str]:
+    escaped = re.escape(term)
+    if re.fullmatch(r"\w+", term):
+        return re.compile(rf"\b{escaped}\b")
+    return re.compile(rf"(?<![\w.]){escaped}(?![\w-]|\.[A-Za-z_])")
+
+
+def public_names(value: object, path: tuple[str | int, ...] = ()) -> set[str]:
+    names: set[str] = set()
+    if isinstance(value, dict):
+        is_public_record = (
+            len(path) == 2
+            and path[0] in {"public_surface", "public_contracts"}
+            and isinstance(path[1], int)
+            and PUBLIC_NAME_KEYS <= set(value)
+            and value.get("visibility") in PUBLIC_NAME_VISIBILITIES
+            and isinstance(value.get("name"), str)
+            and value["name"].strip()
+        )
+        if is_public_record:
+            names.add(value["name"])
+        for key, item in value.items():
+            names.update(public_names(item, path + (key,)))
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            names.update(public_names(item, path + (index,)))
+    return names
+
+
+def strip_allowed_text(text: str, allowed_names: set[str]) -> str:
+    stripped = URL_PATTERN.sub(" ", text)
+    for name in sorted(allowed_names, key=len, reverse=True):
+        if not name:
+            continue
+        stripped = re.sub(rf"(?<![\w.]){re.escape(name)}(?![\w]|\.[A-Za-z_])", " ", stripped)
+    return stripped
+
+
+def json_scan_strings(
+    value: object,
+    allowed_names: set[str],
+    path: tuple[str | int, ...] = (),
+) -> tuple[list[str], list[str], list[str]]:
+    full_scan: list[str] = []
+    light_scan: list[str] = []
+    denylist_scan: list[str] = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            child_full, child_light, child_denylist = json_scan_strings(item, allowed_names, path + (key,))
+            full_scan.extend(child_full)
+            light_scan.extend(child_light)
+            denylist_scan.extend(child_denylist)
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            child_full, child_light, child_denylist = json_scan_strings(item, allowed_names, path + (index,))
+            full_scan.extend(child_full)
+            light_scan.extend(child_light)
+            denylist_scan.extend(child_denylist)
+    elif isinstance(value, str):
+        keys = {item for item in path if isinstance(item, str)}
+        leaf_key = next((item for item in reversed(path) if isinstance(item, str)), None)
+        if leaf_key in NEVER_SCAN_JSON_STRING_KEYS:
+            return full_scan, light_scan, denylist_scan
+        stripped = strip_allowed_text(value, allowed_names)
+        if keys & DENYLIST_ONLY_JSON_STRING_KEYS:
+            denylist_scan.append(stripped)
+        elif leaf_key in SCAN_LIGHT_JSON_STRING_KEYS:
+            light_scan.append(stripped)
+        else:
+            full_scan.append(stripped)
+    return full_scan, light_scan, denylist_scan
+
+
+def scan_private_identifier_denylist(texts: list[str], private_terms: list[str]) -> list[str]:
+    findings: set[str] = set()
+    for text in texts:
+        for term in private_terms:
+            if private_identifier_pattern(term).search(text):
+                findings.add("private_identifier_denylist")
+                break
+    return sorted(findings)
+
+
+def scan_identifier_patterns(
+    texts: list[str],
+    private_terms: list[str],
+    skipped_patterns: set[str] | None = None,
+) -> list[str]:
+    findings: set[str] = set()
+    skipped_patterns = skipped_patterns or set()
+    for text in texts:
+        for term in private_terms:
+            if private_identifier_pattern(term).search(text):
+                findings.add("private_identifier_denylist")
+                break
+        for name, pattern in IDENTIFIER_PATTERNS.items():
+            if name in skipped_patterns:
+                continue
+            if pattern.search(text):
+                findings.add(name)
+    return sorted(findings)
+
+
+def identifier_scan_texts(path: Path, text: str) -> tuple[list[str], list[str], list[str]]:
+    if path.suffix.lower() != ".json":
+        return [strip_allowed_text(text, set())], [], []
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return [strip_allowed_text(text, set())], [], []
+    allowed_names = public_names(data)
+    return json_scan_strings(data, allowed_names)
+
+
+def main() -> int:
+    payload, payload_error = load_payload()
+    if payload_error:
+        print(f"clean-room leakage scan failed: {payload_error}", file=sys.stderr)
+        return 1
+    paths, path_errors = checked_write_paths(payload, "clean-room leakage scan")
+    if path_errors:
+        for error in path_errors:
+            print(f"clean-room leakage scan failed: {error}", file=sys.stderr)
+        return 1
+    private_terms, load_errors = load_private_identifier_terms()
+    if load_errors:
+        for error in load_errors:
+            print(f"clean-room leakage scan failed: {error}", file=sys.stderr)
+        return 1
+    for path in paths:
+        if not is_clean_artifact(path):
+            continue
+        if path.stat().st_size > MAX_SCAN_BYTES:
+            print(
+                f"clean-room leakage scan failed for {path}: artifact exceeds scan cap of {MAX_SCAN_BYTES} bytes",
+                file=sys.stderr,
+            )
+            return 1
+        data = path.read_bytes()
+        text = data.decode("utf-8", errors="replace")
+        findings = [name for name, pattern in BLOCKED_PATTERNS.items() if pattern.search(text)]
+        full_scan_texts, light_scan_texts, denylist_scan_texts = identifier_scan_texts(path, text)
+        findings.extend(scan_identifier_patterns(full_scan_texts, private_terms))
+        findings.extend(
+            scan_identifier_patterns(
+                light_scan_texts,
+                private_terms,
+                skipped_patterns={"source_like_call"},
+            )
+        )
+        findings.extend(scan_private_identifier_denylist(denylist_scan_texts, private_terms))
+        if findings:
+            print(
+                f"clean-room leakage scan failed for {path}: {', '.join(sorted(set(findings)))}",
+                file=sys.stderr,
+            )
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/clean-room-hook.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Dispatch clean-room hook checks behind safe opt-in enforcement."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+TRUTHY = {"1", "true", "yes", "on", "strict"}
+CLEAN_ROOM_ENV_NAMES = {
+    "CLEAN_ROOM_ROLE",
+    "CLEAN_ROOM_SOURCE_ROOTS",
+    "CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS",
+    "CLEAN_ROOM_CLEAN_ROOTS",
+    "CLEAN_ROOM_SCHEMA_DIR",
+    "CLEAN_ROOM_ALLOWED_READ_ROOTS",
+    "CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST",
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--mode",
+        choices=("safe", "strict"),
+        default=os.environ.get("CLEAN_ROOM_HOOK_MODE", "safe"),
+    )
+    parser.add_argument(
+        "--check",
+        action="append",
+        default=[],
+        help="Hook script basename in the hooks directory. Repeat for multiple checks.",
+    )
+    return parser.parse_args()
+
+
+def should_enforce(mode: str) -> bool:
+    if mode == "strict":
+        return True
+    if os.environ.get("CLEAN_ROOM_HOOK_ENFORCE", "").lower() in TRUTHY:
+        return True
+    return any(os.environ.get(name) for name in CLEAN_ROOM_ENV_NAMES)
+
+
+def resolve_check(script_dir: Path, check: str) -> Path:
+    path = Path(check)
+    if path.name != check or path.is_absolute() or check in {"", ".", ".."}:
+        raise ValueError(f"invalid hook check name: {check!r}")
+    resolved = script_dir / check
+    if not resolved.is_file():
+        raise FileNotFoundError(f"hook check does not exist: {resolved}")
+    return resolved
+
+
+def main() -> int:
+    args = parse_args()
+    if not should_enforce(args.mode):
+        return 0
+    if not args.check:
+        print("clean-room hook wrapper has no checks configured", file=sys.stderr)
+        return 1
+
+    payload = sys.stdin.buffer.read()
+    script_dir = Path(__file__).resolve().parent
+    for check in args.check:
+        try:
+            script = resolve_check(script_dir, check)
+        except (FileNotFoundError, ValueError) as exc:
+            print(f"clean-room hook configuration failed: {exc}", file=sys.stderr)
+            return 1
+        result = subprocess.run(
+            [sys.executable, str(script)],
+            input=payload,
+            stdout=sys.stdout,
+            stderr=sys.stderr,
+            check=False,
+        )
+        if result.returncode != 0:
+            return result.returncode
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/clean_room_paths.py

@@ -0,0 +1,130 @@
+"""Shared path and payload helpers for clean-room hook scripts."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+
+ROLES = {
+    "contaminated-manager-verifier",
+    "contaminated-source-analyst",
+    "clean-architect",
+    "clean-qa-editor",
+}
+CLEAN_ROLES = {"clean-architect", "clean-qa-editor"}
+WRITE_TOOL_NAMES = {"Write", "Edit", "MultiEdit"}
+PATH_KEYS = {
+    "file_path",
+    "filePath",
+    "path",
+    "output_path",
+    "outputPath",
+}
+
+
+def path_is_under(path: Path, root: Path) -> bool:
+    return path == root or root in path.parents
+
+
+def paths_overlap(left: Path, right: Path) -> bool:
+    return path_is_under(left, right) or path_is_under(right, left)
+
+
+def split_paths(value: str) -> list[Path]:
+    paths: list[Path] = []
+    for item in value.split(os.pathsep):
+        if not item:
+            continue
+        paths.append(Path(item).expanduser().resolve())
+    return paths
+
+
+def env_roots(name: str) -> list[Path]:
+    try:
+        return split_paths(os.environ.get(name, ""))
+    except OSError:
+        return []
+
+
+def path_under_env(path: Path, name: str) -> bool:
+    roots = env_roots(name)
+    return bool(roots) and any(path_is_under(path, root) for root in roots)
+
+
+def active_clean_room_role() -> str:
+    role = os.environ.get("CLEAN_ROOM_ROLE", "")
+    return role if role in ROLES else ""
+
+
+def load_payload() -> tuple[dict[str, Any], str | None]:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return {}, None
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return {}, f"malformed hook JSON payload: {exc}"
+    if not isinstance(data, dict):
+        return {}, "hook payload must be a JSON object"
+    return data, None
+
+
+def tool_name(payload: dict[str, Any]) -> str:
+    for key in ("tool_name", "tool", "name"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value
+    return ""
+
+
+def should_fail_closed_for_write(payload: dict[str, Any]) -> bool:
+    if not active_clean_room_role():
+        return False
+    name = tool_name(payload)
+    return not name or name in WRITE_TOOL_NAMES
+
+
+def _path_values(value: Any) -> list[str]:
+    paths: list[str] = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if key in PATH_KEYS and isinstance(item, str):
+                paths.append(item)
+            elif isinstance(item, (dict, list)):
+                paths.extend(_path_values(item))
+    elif isinstance(value, list):
+        for item in value:
+            paths.extend(_path_values(item))
+    return paths
+
+
+def candidate_paths(payload: dict[str, Any]) -> tuple[list[Path], list[str]]:
+    paths: list[Path] = []
+    errors: list[str] = []
+    seen: set[Path] = set()
+    for value in _path_values(payload):
+        try:
+            path = Path(value).expanduser().resolve()
+        except OSError as exc:
+            errors.append(f"invalid hook path {value!r}: {exc}")
+            continue
+        if path in seen:
+            continue
+        seen.add(path)
+        paths.append(path)
+    return paths, errors
+
+
+def checked_write_paths(payload: dict[str, Any], hook_name: str) -> tuple[list[Path], list[str]]:
+    paths, errors = candidate_paths(payload)
+    if should_fail_closed_for_write(payload):
+        if not paths:
+            errors.append(f"{hook_name} could not determine the written path from the hook payload")
+        for path in paths:
+            if not path.is_file():
+                errors.append(f"{hook_name} could not read written file: {path}")
+    return paths, errors

package/hooks/deny-clean-room-shell.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Block shell-style tools for clean-room role sessions."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+ROLES = {
+    "contaminated-manager-verifier",
+    "contaminated-source-analyst",
+    "clean-architect",
+    "clean-qa-editor",
+}
+
+
+def main() -> int:
+    role = os.environ.get("CLEAN_ROOM_ROLE", "")
+    if role in ROLES:
+        print(
+            f"clean-room policy denied shell tool use for role {role}",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/deny-clean-source-read.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Deny clean-role reads outside explicitly configured clean roots."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+CLEAN_ROLES = {"clean-architect", "clean-qa-editor"}
+ADDITIONAL_CLEAN_READ_ROOTS = "CLEAN_ROOM_ALLOWED_READ_ROOTS"
+
+
+def load_payload() -> dict:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return {}
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def configured_roots(name: str) -> list[Path]:
+    value = os.environ.get(name, "")
+    roots = []
+    for item in value.split(os.pathsep):
+        if item:
+            roots.append(Path(item).expanduser().resolve())
+    return roots
+
+
+def append_path_value(paths: list[Path], value: str) -> None:
+    try:
+        paths.append(Path(value).expanduser().resolve())
+    except OSError:
+        return
+
+
+def candidate_paths(payload: dict) -> list[Path]:
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    tool_name = str(payload.get("tool_name") or payload.get("tool") or "").lower()
+    paths = []
+    for key in ("file_path", "path", "cwd"):
+        value = tool_input.get(key) or payload.get(key)
+        if isinstance(value, str):
+            append_path_value(paths, value)
+    glob_value = tool_input.get("glob") or payload.get("glob")
+    if isinstance(glob_value, str) and (glob_value.startswith(("/", "~")) or "/" in glob_value):
+        append_path_value(paths, glob_value)
+    pattern_value = tool_input.get("pattern") or payload.get("pattern")
+    if "glob" in tool_name and isinstance(pattern_value, str) and (
+        pattern_value.startswith(("/", "~")) or "/" in pattern_value
+    ):
+        append_path_value(paths, pattern_value)
+    return paths
+
+
+def is_under(path: Path, root: Path) -> bool:
+    return path == root or root in path.parents
+
+
+def main() -> int:
+    role = os.environ.get("CLEAN_ROOM_ROLE", "")
+    if role not in CLEAN_ROLES:
+        return 0
+    source_roots = configured_roots("CLEAN_ROOM_SOURCE_ROOTS")
+    allowed_roots = configured_roots("CLEAN_ROOM_CLEAN_ROOTS") + configured_roots(ADDITIONAL_CLEAN_READ_ROOTS)
+    paths = candidate_paths(load_payload())
+    if not paths:
+        print(
+            f"clean-room policy denied clean role {role} read with no resolved path",
+            file=sys.stderr,
+        )
+        return 1
+    for path in paths:
+        if any(is_under(path, root) for root in source_roots):
+            print(
+                f"clean-room policy denied clean role {role} reading source path {path}",
+                file=sys.stderr,
+            )
+            return 1
+        if not allowed_roots:
+            print(
+                f"clean-room policy denied clean role {role} reading {path}: no clean read roots configured",
+                file=sys.stderr,
+            )
+            return 1
+        if not any(is_under(path, root) for root in allowed_roots):
+            print(
+                f"clean-room policy denied clean role {role} reading outside allowed clean roots: {path}",
+                file=sys.stderr,
+            )
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())