interlockd 0.1.0__py3-none-any.whl

interlockd/det/engine.py

@@ -0,0 +1,153 @@
+"""Deterministic engine entry point: route a normalized event through the packs the policy enables."""
+
+from __future__ import annotations
+
+from ..models import InterlockEvent
+from ..paths import is_protected, is_sensitive, is_under, normalize_path
+from ..policy import Policy
+from ..tiers import (
+    DESTRUCTIVE_TOOLS,
+    IN_WORKSPACE_WRITE_TOOLS,
+    NETWORK_TOOLS,
+    PATH_KEYS,
+    SHELL_TOOLS,
+    TierResult,
+)
+from . import DetResult
+from .mcp import check_mcp_policy
+from .packs import (
+    R_EGRESS_SHARE,
+    R_EGRESS_UNKNOWN,
+    R_SECRET_IN_RESULT,
+    R_SECRET_READ,
+    _host_allowed,
+    _host_of,
+    check_egress,
+    check_git,
+    check_packages,
+    check_persistence_file_op,
+    check_persistence_shell,
+    check_secrets_shell,
+    check_shell,
+    scan_secrets,
+)
+from .shellparse import parse
+
+HARM = {"read": 0, "harness": 0, "build_or_test": 0, "edit_in_workspace": 0, "edit_outside_workspace": 2, "edit_protected": 3,
+        "install_or_configure": 2, "vcs_history_or_remote": 2, "network_egress": 2, "destructive": 2, "credential_access": 3,
+        "shell": 1, "subagent": 1, "mcp": 1, "other": 1}
+
+
+def harm_for(res: DetResult) -> int:
+    """0 recoverable locally · 1 recoverable with effort · 2 hard to reverse · 3 irreversible or affects others."""
+    h = HARM.get(res.action_class, 1)
+    sev = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+    for f in res.findings:
+        h = max(h, sev.get(f.severity, 1))
+    return min(h, 3)
+
+
+def _command_of(event: InterlockEvent) -> str | None:
+    a = event.tool_call.arguments
+    for k in ("command", "cmd", "script", "commandLine"):
+        v = a.get(k)
+        if isinstance(v, str) and v.strip():
+            return v
+    if isinstance(a.get("args"), list) and a.get("args"):
+        return " ".join(str(x) for x in a["args"])
+    return None
+
+
+def evaluate(event: InterlockEvent, policy: Policy, tier: TierResult) -> DetResult:
+    res = DetResult(action_class=tier.action_class)
+    cwd = event.context.cwd
+    enabled = set(policy.packs.enabled)
+    name = event.tool_call.name
+    args = event.tool_call.arguments
+    roots = policy.trust.workspace_roots or ([cwd] if cwd else [])
+
+    if event.kind == "post_action":
+        if "secrets" in enabled and event.result is not None:
+            scan_secrets(event.result.content, "result.content", res, policy, R_SECRET_IN_RESULT)
+        res.harm = harm_for(res)
+        return res
+
+    if tier.action_class == "mcp" or event.context.mcp_server:
+        check_mcp_policy(event, res, policy)
+    # MCP and unrecognized tools that run commands (terminal servers, SDK tools named run_command / exec / terminal)
+    # get the same shell analysis as the agent's own shell; only explicit command keys count, since a generic `args`
+    # list means something else on most tools
+    mcp_cmd = next((args[k] for k in ("command", "cmd", "script", "commandLine")
+                    if isinstance(args.get(k), str) and args[k].strip()), None) if tier.action_class in ("mcp", "other") else None
+    if name in SHELL_TOOLS or mcp_cmd is not None:
+        cmd = _command_of(event) if mcp_cmd is None else mcp_cmd
+        if cmd is not None:
+            parsed = parse(cmd)
+            res.normalized["commands"] = parsed.commands()[:20]
+            if res.action_class == "shell":
+                res.action_class = "build_or_test" if parsed.commands() and all(
+                    c in BUILD_TOOLS for c in parsed.commands()) else "shell"
+            if "shell" in enabled:
+                check_shell(parsed, res, policy, cwd)
+            if "git" in enabled:
+                check_git(parsed, res, policy)
+            if "egress" in enabled:
+                check_egress(parsed, res, policy, cwd)
+            if "persistence" in enabled:
+                check_persistence_shell(parsed, res, policy, cwd)
+            if "secrets" in enabled:
+                check_secrets_shell(parsed, res, policy, cwd)
+            if "packages" in enabled:
+                check_packages(parsed, res, policy, cwd)
+    elif name in IN_WORKSPACE_WRITE_TOOLS or name in DESTRUCTIVE_TOOLS or tier.paths:
+        for p in tier.paths or [normalize_path(args[k], cwd) for k in PATH_KEYS if isinstance(args.get(k), str)]:
+            where = "tool_call.arguments.path"
+            if "persistence" in enabled and name in IN_WORKSPACE_WRITE_TOOLS:
+                check_persistence_file_op(p, res, policy, cwd, where)
+            if "secrets" in enabled and is_sensitive(p, policy.trust.sensitive_paths):
+                res.add(policy, R_SECRET_READ, path=where, subject=p)
+            if name in DESTRUCTIVE_TOOLS and roots and not is_under(p, roots):
+                from .packs import R_RM_OUTSIDE
+                res.add(policy, R_RM_OUTSIDE, path=where, subject=p)
+            if name in IN_WORKSPACE_WRITE_TOOLS and is_protected(p, roots, policy.trust.protected_paths) and not res.findings:
+                from .packs import R_PERSIST_AGENT_CONFIG
+                res.add(policy, R_PERSIST_AGENT_CONFIG, path=where, subject=p)
+        content = args.get("content") or args.get("new_str") or args.get("file_text") or args.get("new_string") or ""
+        if res.normalized.get("memory_write") and isinstance(content, str) and content:
+            from ..judges.local_probe import heuristic_score
+            from .memory import R_MEMORY_INJECTED
+
+            score, hits = heuristic_score(content)
+            if score >= 0.6:
+                res.add(policy, R_MEMORY_INJECTED, path="tool_call.arguments.content",
+                        subject=f"{res.normalized['memory_write']}: content reads as instructions to the agent ({score:.2f}: {', '.join(hits[:4])})")
+        if "secrets" in enabled and isinstance(content, str) and content:
+            from .packs import R_SECRET_IN_ARGS
+            scan_secrets(content, "tool_call.arguments.content", res, policy, R_SECRET_IN_ARGS)
+    elif name in NETWORK_TOOLS and "egress" in enabled:
+        url = args.get("url") or args.get("query") or ""
+        host = _host_of(str(url)) if url else None
+        if host:
+            # the same host checks, in the same order, as shell egress (packs.check_egress): web tools and the egress
+            # proxy reach the metadata endpoint just as well as curl does
+            from .packs import METADATA_HOSTS, R_EGRESS_METADATA, R_EGRESS_RAW_IP, SHARE_HOSTS, _is_ip
+
+            res.normalized["egress_hosts"] = [host]
+            where = "tool_call.arguments.url"
+            if host in METADATA_HOSTS or host.startswith("169.254."):
+                res.add(policy, R_EGRESS_METADATA, path=where, subject=host)
+            elif any(s in host for s in SHARE_HOSTS):
+                res.add(policy, R_EGRESS_SHARE, path=where, subject=host)
+            elif _is_ip(host) and not _host_allowed(host, policy.trust.allowed_hosts):
+                res.add(policy, R_EGRESS_RAW_IP, path=where, subject=host)
+            elif not _host_allowed(host, policy.trust.allowed_hosts):
+                res.add(policy, R_EGRESS_UNKNOWN, path=where, subject=host)
+
+    res.harm = harm_for(res)
+    return res
+
+
+BUILD_TOOLS = {"npm", "pnpm", "yarn", "bun", "node", "python", "python3", "pytest", "uv", "pip", "make", "cmake", "cargo", "go",
+               "mvn", "gradle", "./gradlew", "tsc", "eslint", "ruff", "black", "mypy", "prettier", "jest", "vitest", "ls", "cat",
+               "echo", "pwd", "which", "env", "head", "tail", "grep", "rg", "find", "wc", "sort", "uniq", "diff", "git", "sed", "awk",
+               "cd", "true", "test", "sleep", "date", "docker", "kubectl"}

interlockd/det/flow.py

@@ -0,0 +1,106 @@
+"""Toxic-flow detection: the "lethal trifecta" across one session.
+
+An agent that (1) has read private data, (2) has taken in untrusted content, and (3) now calls something that can send
+data out, is one injected instruction away from exfiltration. Each call alone looks fine, so per-call rules miss it.
+The session ledger keeps the first two legs with evidence; the third is checked on every pre-action call.
+
+  private    sensitive-path reads, secrets seen in a tool result, MCP tools matching `flow.private_sources`
+  untrusted  web / network tool results, MCP results matching `flow.untrusted_sources`, any result the injection probe
+             flagged
+  sink       network egress (shell or web tool), git push, MCP tools matching `flow.sinks`
+"""
+
+from __future__ import annotations
+
+from fnmatch import fnmatchcase
+from typing import Any
+
+from ..models import Finding, InterlockEvent
+from ..policy import Policy
+from ..tiers import NETWORK_TOOLS
+from . import DetResult, rule
+from .mcp import split_mcp_name
+
+R_FLOW_TRIFECTA = rule("flow.lethal_trifecta", "security.data_exfiltration", "high", "ask")
+R_FLOW_MEMORY = rule("flow.memory_poisoning", "security.memory_poisoning", "high", "ask")
+PRIVATE_RULES = {"secrets.read_sensitive_path", "secrets.dump_environment", "secrets.literal_in_result"}
+
+
+def _mcp_target(event: InterlockEvent) -> str | None:
+    st = split_mcp_name(event)
+    return f"{st[0]}/{st[1]}" if st else None
+
+
+def _matches(target: str | None, patterns: list[str]) -> bool:
+    return bool(target) and any(fnmatchcase(target, p) for p in patterns)
+
+
+def _legs(session: dict[str, Any]) -> dict[str, list[str]]:
+    return session.setdefault("flow", {"private": [], "untrusted": []})
+
+
+def _note(legs: dict, leg: str, evidence: str) -> None:
+    if evidence not in legs[leg]:
+        legs[leg] = (legs[leg] + [evidence])[-5:]
+
+
+def observe(event: InterlockEvent, session: dict[str, Any], policy: Policy, findings: list[Finding]) -> None:
+    """Update the session's private / untrusted legs from a decided event (pre or post)."""
+    if not policy.flow.enabled:
+        return
+    legs = _legs(session)
+    target = _mcp_target(event)
+    name = event.tool_call.name
+    for f in findings:
+        if f.rule in PRIVATE_RULES:
+            _note(legs, "private", f"{f.rule}: {(f.subject or '')[:80]}")
+    if event.kind == "post_action":
+        if _matches(target, policy.flow.private_sources):
+            _note(legs, "private", f"read from {target}")
+        if name in NETWORK_TOOLS:
+            _note(legs, "untrusted", f"{name} result")
+        if _matches(target, policy.flow.untrusted_sources):
+            _note(legs, "untrusted", f"result from {target}")
+        if any(f.category == "security.prompt_injection" for f in findings):
+            _note(legs, "untrusted", f"{name} result flagged as injected")
+
+
+def is_sink(event: InterlockEvent, res: DetResult, policy: Policy) -> str | None:
+    if res.normalized.get("egress_hosts"):
+        return "network egress to " + ", ".join(res.normalized["egress_hosts"][:3])
+    if event.tool_call.name in NETWORK_TOOLS:
+        return f"{event.tool_call.name} request"
+    cmds = res.normalized.get("commands") or []
+    if "git" in cmds and "push" in str(event.tool_call.arguments.get("command", "")):
+        return "git push"
+    target = _mcp_target(event)
+    if _matches(target, policy.flow.sinks):
+        return f"MCP {target}"
+    return None
+
+
+def check(event: InterlockEvent, res: DetResult, session: dict[str, Any], policy: Policy) -> None:
+    """Pre-action: fire when this call is a sink and both other legs are already present in the session."""
+    if not policy.flow.enabled or event.kind != "pre_action":
+        return
+    legs = _legs(session)
+    if legs["untrusted"]:
+        from .memory import is_memory_tool
+
+        target = _mcp_target(event)
+        mem = res.normalized.get("memory_write") or (f"MCP {target}" if is_memory_tool(target) else None)
+        if mem:
+            res.add(policy, R_FLOW_MEMORY, path="session",
+                    subject=f"this session took in untrusted content ({legs['untrusted'][-1]}); now writing persistent agent memory: {mem}")
+    if not (legs["private"] and legs["untrusted"]):
+        return
+    sink = is_sink(event, res, policy)
+    if not sink:
+        return
+    subject = (f"this session read private data ({legs['private'][-1]}) and took in untrusted content "
+               f"({legs['untrusted'][-1]}); now: {sink}")
+    if policy.rule_action(R_FLOW_TRIFECTA, policy.flow.action) is not None:
+        before = len(res.findings)
+        res.add(policy, R_FLOW_TRIFECTA, path="session", subject=subject)
+        if len(res.findings) > before and R_FLOW_TRIFECTA not in policy.packs.overrides:
+            res.actions[R_FLOW_TRIFECTA] = policy.flow.action      # flow.action unless an explicit rule override

interlockd/det/mandate.py

@@ -0,0 +1,108 @@
+"""Cedar mandate (design D8): the operator's authorization envelope, evaluated locally with cedarpy.
+
+Bindings map the deterministic engine's normalized structure onto Interlock::Action names and a context.
+Unbound actions are reported in `unjudged`, never silently permitted (OGR mandate semantics). Cedar's own
+default-deny applies only to bound actions when at least one policy exists.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ..models import Finding
+from ..policy import Policy
+from . import DetResult
+
+
+@dataclass
+class MandateResult:
+    evaluated: bool = False
+    decision: str | None = None          # "Allow" | "Deny" | None
+    action: str | None = None
+    reasons: list[str] = field(default_factory=list)
+    unjudged: list[str] = field(default_factory=list)
+    finding: Finding | None = None
+
+
+def bind_action(res: DetResult, tool_name: str) -> tuple[str | None, dict[str, Any]]:
+    """Return (Interlock::Action id, context.input) for the normalized structure, or (None, {}) if unbound."""
+    n = res.normalized
+    if "git_push" in n:
+        gp = n["git_push"]
+        return "git.push", {"remote": gp["remote"], "branch": gp["branch"], "force": bool(gp["force"]), "delete": bool(gp["delete"])}
+    if "git_remote_add" in n:
+        return "git.remote_add", {"url": n["git_remote_add"]["url"]}
+    if any(f.rule in ("git.history_rewrite", "git.reset_hard", "git.clean_force") for f in res.findings):
+        return "git.history_rewrite", {}
+    if res.action_class == "network_egress" and n.get("egress_hosts"):
+        return "net.egress", {"hosts": n["egress_hosts"]}
+    if res.action_class == "destructive":
+        return "destructive", {}
+    if res.action_class == "install_or_configure":
+        return "install", {"undeclared": n.get("undeclared_packages", [])}
+    if res.action_class == "credential_access":
+        return "fs.read_sensitive", {}
+    if res.action_class in ("edit_in_workspace",):
+        return "fs.write", {}
+    if res.action_class in ("edit_outside_workspace", "edit_protected"):
+        return "fs.write_outside", {}
+    if any(f.rule == "shell.sudo" for f in res.findings):
+        return "sys.privilege", {}
+    if res.action_class in ("build_or_test",):
+        return "shell.build_or_test", {}
+    return None, {}
+
+
+def evaluate_mandate(policy: Policy, res: DetResult, *, agent_id: str, workspace: str, session_counters: dict[str, Any]) -> MandateResult:
+    out = MandateResult()
+    m = policy.mandate
+    if m.mode == "off" or (not m.cedar and not m.inline):
+        return out
+    try:
+        import cedarpy  # lazy, optional dependency
+    except ImportError:
+        out.unjudged = ["mandate"]
+        return out
+    text = m.inline or ""
+    if m.cedar:
+        p = Path(m.cedar)
+        if not p.exists():
+            out.unjudged = ["mandate"]
+            return out
+        text = p.read_text() + "\n" + text
+    action, ctx_input = bind_action(res, "")
+    if action is None:
+        out.unjudged = ["mandate"]
+        return out
+    request = {
+        "principal": f'Interlock::Agent::"{agent_id or "agent"}"',
+        "action": f'Interlock::Action::"{action}"',
+        "resource": f'Interlock::Workspace::"{workspace or "workspace"}"',
+        "context": {"input": ctx_input, "session": {k.replace(":", "_"): v for k, v in session_counters.items() if isinstance(v, int)}},
+    }
+    try:
+        r = cedarpy.is_authorized(request, text, [])
+    except Exception as e:  # noqa: BLE001  a policy that fails to parse or evaluate is reported, not swallowed
+        out.unjudged = ["mandate"]
+        out.reasons = [f"cedar error: {type(e).__name__}: {e}"[:200]]
+        return out
+    out.evaluated, out.action = True, action
+    out.decision = "Allow" if str(r.decision).endswith("Allow") else "Deny"
+    try:
+        out.reasons = list(r.diagnostics.reasons)
+    except Exception:  # noqa: BLE001  diagnostics shape differs across cedarpy versions
+        out.reasons = []
+    if out.decision == "Deny":
+        dim = "capability"
+        if action == "git.push" and ctx_input.get("force"):
+            dim = "irreversible"
+        elif action in ("net.egress", "git.push", "git.remote_add"):
+            dim = "scope"
+        elif any(k.endswith("_count") or k.startswith("class_") for k in request["context"]["session"]) and "destructive" in action:
+            dim = "limit"
+        out.finding = Finding(category=f"security.mandate_violation.{dim}", severity="high", rule=f"mandate:{action}",
+                              detector="interlock.mandate", path="tool_call", score=1.0,
+                              subject=f"{action} denied by mandate" + (f" ({', '.join(out.reasons)})" if out.reasons else ""))
+    return out

interlockd/det/mcp.py

@@ -0,0 +1,70 @@
+"""MCP server / tool policy (`mcp.tools` in policy): which servers and tools an agent may use, from any harness.
+
+Tool names differ per harness: Claude Code / Codex and the gateway use `mcp__<server>__<tool>`, Gemini CLI
+`mcp_<server>_<tool>`, Cursor `MCP:<tool>` with the server in the payload. `split_mcp_name` recovers (server, tool).
+"""
+
+from __future__ import annotations
+
+from fnmatch import fnmatchcase
+
+from ..models import InterlockEvent
+from ..policy import Policy
+from . import DetResult, rule
+
+R_MCP_BLOCKED = rule("mcp.tool_blocked", "security.unauthorized_tool", "high", "block")
+R_MCP_ASK = rule("mcp.tool_requires_approval", "security.unauthorized_tool", "medium", "ask")
+
+
+def split_mcp_name(event: InterlockEvent, known_servers: list[str] = ()) -> tuple[str, str] | None:
+    name = event.tool_call.name
+    server_hint = (event.context.mcp_server or {}).get("name")
+    if name.startswith("mcp__"):
+        parts = name[5:].split("__", 1)
+        return (parts[0], parts[1]) if len(parts) == 2 else (parts[0], "")
+    if name.startswith("MCP:"):
+        return (server_hint or "*", name[4:])
+    if name.startswith("mcp_"):
+        rest = name[4:]
+        for s in sorted([*known_servers, *([server_hint] if server_hint else [])], key=len, reverse=True):
+            if rest.startswith(s + "_"):
+                return (s, rest[len(s) + 1:])
+        head, _, tail = rest.partition("_")             # ambiguous without a known server: first segment
+        return (head, tail)
+    if server_hint:
+        return (server_hint, name)
+    return None
+
+
+def _specificity(pattern: str) -> tuple[int, int, int]:
+    """Tool-level beats server-level, then exact beats glob, then longer beats shorter."""
+    return (1 if "/" in pattern else 0, 0 if any(c in pattern for c in "*?[") else 1, len(pattern.replace("*", "")))
+
+
+def resolve(policy: Policy, server: str, tool: str) -> tuple[str, str | None]:
+    """(action, matching pattern). Patterns without a `/` match the whole server; a pattern that names a tool always
+    outranks a server-wide one."""
+    best, best_key = None, None
+    for pat, action in policy.mcp.tools.items():
+        target = f"{server}/{tool}" if "/" in pat else server
+        matches = fnmatchcase(target, pat) or pat == server
+        if matches and (best_key is None or _specificity(pat) > _specificity(best_key)):
+            best, best_key = action, pat
+    return (best or policy.mcp.default, best_key)
+
+
+def check_mcp_policy(event: InterlockEvent, res: DetResult, policy: Policy) -> None:
+    if not policy.mcp.tools and policy.mcp.default == "allow":
+        return
+    known = sorted({p.split("/", 1)[0] for p in policy.mcp.tools if not any(c in p.split("/", 1)[0] for c in "*?[")})
+    st = split_mcp_name(event, known)
+    if st is None:
+        return
+    server, tool = st
+    action, pat = resolve(policy, server, tool)
+    res.normalized["mcp"] = {"server": server, "tool": tool, "policy": pat or "default", "action": action}
+    why = f"{server}/{tool} ({'mcp.tools[' + repr(pat) + ']' if pat else 'mcp.default'}: {action})"
+    if action == "block":
+        res.add(policy, R_MCP_BLOCKED, path="tool_call.name", subject=why)
+    elif action == "ask":
+        res.add(policy, R_MCP_ASK, path="tool_call.name", subject=why)

interlockd/det/memory.py

@@ -0,0 +1,50 @@
+"""Memory poisoning: writes that persist into every future agent session.
+
+Agent instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, Copilot instructions, Kiro steering, ...) and
+MCP memory servers are read back into the model's context in later sessions, so an agent that was tricked into
+writing to them keeps an injected instruction alive indefinitely. Writing them is normal when the user asks, so:
+
+  memory.instruction_file_write   any write to an instruction file is recorded (flag)
+  memory.injected_instructions    the written content reads as instructions aimed at the agent (ask)
+  flow.memory_poisoning           the session already took in untrusted content (see flow.py) (ask)
+"""
+
+from __future__ import annotations
+
+from fnmatch import fnmatchcase
+
+from ..judges.local_probe import heuristic_score
+from ..policy import Policy
+from . import DetResult, rule
+
+R_MEMORY_WRITE = rule("memory.instruction_file_write", "security.memory_poisoning", "medium", "flag")
+R_MEMORY_INJECTED = rule("memory.injected_instructions", "security.memory_poisoning", "high", "ask")
+
+INSTRUCTION_NAMES = ("CLAUDE.md", "CLAUDE.local.md", "AGENTS.md", "GEMINI.md", ".cursorrules", ".windsurfrules",
+                     ".clinerules", "copilot-instructions.md", "CONVENTIONS.md")
+INSTRUCTION_DIRS = ("/.kiro/steering/", "/.cursor/rules/", "/.github/instructions/", "/.clinerules/", "/.windsurf/rules/")
+MEMORY_TOOLS = ("*memory*/create*", "*memory*/add*", "*memory*/save*", "*memory*/store*", "*memory*/update*",
+                "*memory*/write*", "*memory*/remember*", "*/remember*", "*/save_memory*", "*/add_observations*")
+
+
+def is_instruction_file(path: str) -> bool:
+    name = path.rsplit("/", 1)[-1]
+    return name in INSTRUCTION_NAMES or any(d in path for d in INSTRUCTION_DIRS)
+
+
+def is_memory_tool(target: str | None) -> bool:
+    return bool(target) and any(fnmatchcase(target, p) for p in MEMORY_TOOLS)
+
+
+def check_instruction_write(path: str, content: str | None, res: DetResult, policy: Policy, where: str) -> bool:
+    """Record an instruction-file write and ask when its content reads as injected instructions. True if it matched."""
+    if not is_instruction_file(path):
+        return False
+    res.add(policy, R_MEMORY_WRITE, path=where, subject=path)
+    if content:
+        score, hits = heuristic_score(content, assume_addressed=False)
+        if score >= 0.6:
+            res.add(policy, R_MEMORY_INJECTED, path="tool_call.arguments.content",
+                    subject=f"{path}: content reads as instructions to the agent ({score:.2f}: {', '.join(hits[:4])})")
+    res.normalized["memory_write"] = path
+    return True