@veda-hq/kavach 0.5.6 → 0.6.0

package/README.md

@@ -60,6 +60,10 @@ that cannot be read, is not JSON, or has an unknown key refuses every call.
   "worktree": {
     "trustedCommands": [
       { "script": "scripts/worktree.py", "pattern": "python3 scripts/worktree\\.py (?:status|retire --pr [1-9][0-9]*)" }
+    ],
+    "readOnlyCommands": [
+      { "pattern": "pnpm (?:health:check|(?:ls|list|why)(?: [A-Za-z0-9@][A-Za-z0-9@/._-]*)*(?: --depth [0-9]+)?)",
+        "env": { "AGENT_REMOTE": ["true"] }, "reason": "the script and pnpm's listing commands only read" }
     ]
   },
   "command": {
@@ -77,6 +81,14 @@ that cannot be read, is not JSON, or has an unknown key refuses every call.
   pattern must match the whole command; trust only command lines of plain
   words (a whole line with any shell metacharacter is never trusted by its
   pattern alone).
+- `readOnlyCommands`: a command line you reviewed as only reading, though
+  the guard cannot prove it (a package runner's script, say). It runs with no
+  owned worktree, from a checkout's root only, and only while the hook's own
+  environment holds one of the listed values for every variable in `env`,
+  which is required. The pattern is matched as a trusted command's is. Keep
+  the list to commands that write nothing however they are called, and
+  name each option a pattern allows: a runner's own options after the
+  subcommand (`pnpm ls -C elsewhere`, `--pnpmfile`) move or widen what runs.
 - `protectedVariables`: environment variables a command may not assign, declare or
   export.
 - `pairedChanges`: a commit that may record a path ending in `changes` must

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veda-hq/kavach",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "Guards for coding agents: refuses writes outside the agent's worktree, git-hook bypasses and history-destroying pushes, and runs a project's own rule checks on each tool call. Read-only commands pass.",
   "keywords": [
     "coding agents",

package/python/kavach/boundary.py

@@ -16,7 +16,7 @@ import stat
 import subprocess
 import sys
 from pathlib import Path
-from typing import Protocol, Sequence
+from typing import Mapping, Protocol, Sequence
 
 
 # Admission to this set means one thing: NO invocation of the command mutates
@@ -3246,22 +3246,10 @@ def trusted_request(
 
     if not trusted:
         return False
-    # A loose pattern (`.*`) must not trust a whole line that hides another
-    # command: the whole-line match holds only for plain words.
-    plain = TRUSTED_LINE_UNSAFE.search(command) is None
-    opening: tuple[str, list[list[str]]] | None = None
-    rest_is_inert: bool | None = None
+    line = ReviewedLine(command)
     for entry in trusted:
-        if not (plain and entry.pattern.fullmatch(command)):
-            if opening is None:
-                opening = trusted_opening(command)
-            first, rest = opening
-            if not first or not entry.pattern.fullmatch(first):
-                continue
-            if rest_is_inert is None:
-                rest_is_inert = all(segment_is_read_only(words) for words in rest)
-            if not rest_is_inert:
-                continue
+        if not line.matches(entry.pattern):
+            continue
         resolved = root.resolve()
         script = resolved / entry.script
         if cwd.resolve() == resolved and script.is_file() and script.resolve() == script:
@@ -3269,6 +3257,78 @@ def trusted_request(
     return False
 
 
+class ReviewedLine:
+    """One command line, as a consumer's reviewed pattern is matched to it.
+
+    A whole line of plain words matches when the pattern matches all of it. A
+    loose pattern (`.*`) must not admit a line that hides another command, so
+    any other line matches only by its first segment, as plain words, followed
+    by nothing but read-only segments (reviewed redirections included). The
+    parse is done once, for the first pattern that needs it.
+    """
+
+    def __init__(self, command: str) -> None:
+        self.command = command
+        self.plain = TRUSTED_LINE_UNSAFE.search(command) is None
+        self.opening: tuple[str, list[list[str]]] | None = None
+        self.rest_is_inert: bool | None = None
+
+    def matches(self, pattern: re.Pattern[str]) -> bool:
+        if self.plain and pattern.fullmatch(self.command):
+            return True
+        if self.opening is None:
+            self.opening = trusted_opening(self.command)
+        first, rest = self.opening
+        if not first or not pattern.fullmatch(first):
+            return False
+        if self.rest_is_inert is None:
+            self.rest_is_inert = all(segment_is_read_only(words) for words in rest)
+        return self.rest_is_inert
+
+
+class ReadOnlyEntry(Protocol):
+    """One reviewed read-only command, as `config.ReadOnlyCommand` carries it:
+    `pattern` must match the whole command line, and `env` pairs each
+    variable with the values the hook's environment may hold for it."""
+
+    pattern: re.Pattern[str]
+    env: tuple[tuple[str, tuple[str, ...]], ...]
+
+
+def read_only_request(
+    command: str,
+    cwd: Path,
+    root: Path,
+    entries: Sequence[ReadOnlyEntry],
+    environ: Mapping[str, str],
+) -> bool:
+    """Recognize a command line the consumer reviewed as only reading.
+
+    Such a command reads although this parser cannot prove it: a package
+    runner's script, say, whose writes are the consumer's to review, not
+    kavach's. It needs no owned worktree, so the match is held as tight as a
+    trusted command's (``ReviewedLine``), and two more conditions apply:
+
+    - It runs from the checkout's root (``root``), so a relative script or
+      a package manifest means the root's own, never a subfolder's.
+    - Every variable the entry names holds one of its listed values in
+      ``environ``, the hook's own environment, which the command line cannot
+      set.
+
+    No entries: nothing is admitted here.
+    """
+
+    if not entries or cwd.resolve() != root.resolve():
+        return False
+    line = ReviewedLine(command)
+    for entry in entries:
+        if all(environ.get(name) in values for name, values in entry.env) and line.matches(
+            entry.pattern
+        ):
+            return True
+    return False
+
+
 def trusted_opening(command: str) -> tuple[str, list[list[str]]]:
     """The first segment of ``command`` as plain words, and the segments after.
 

package/python/kavach/config.py

@@ -2,8 +2,8 @@
 the environment variable KAVACH_CONFIG.
 
 kavach knows no product. What one product trusts or requires (a script its
-agents may run from any checkout, environment variables an agent must leave
-alone, a file whose change needs another in the same commit) comes from this
+agents may run from any checkout, a command it reviewed as only reading and allows in one
+environment, environment variables an agent must leave alone, a file whose change needs another in the same commit) comes from this
 file, and with no file every such rule is off.
 
 A file that cannot be read, is not JSON, has a key this module does not know,
@@ -38,6 +38,18 @@ class TrustedCommand:
     pattern: re.Pattern[str]
 
 
+@dataclass(frozen=True)
+class ReadOnlyCommand:
+    """A command line the consumer reviewed as only reading, allowed from a
+    checkout's root without an owned worktree, and only where the hook's own
+    environment holds one of the listed values for every variable in `env`.
+    `pattern` must match the whole command; `reason` says what was checked."""
+
+    pattern: re.Pattern[str]
+    env: tuple[tuple[str, tuple[str, ...]], ...]
+    reason: str
+
+
 @dataclass(frozen=True)
 class PairedChange:
     """A commit that may record a path ending in `changes` must also certainly
@@ -54,13 +66,14 @@ class Config:
     protected_variables: tuple[str, ...] = ()
     protected_variables_reason: str = ""
     paired_changes: tuple[PairedChange, ...] = ()
+    read_only_commands: tuple[ReadOnlyCommand, ...] = ()
 
 
 DEFAULT = Config()
 
 SHAPE: dict[str, set[str]] = {
     "": {"worktree", "command"},
-    "worktree": {"trustedCommands"},
+    "worktree": {"trustedCommands", "readOnlyCommands"},
     "command": {"protectedVariables", "protectedVariablesReason", "pairedChanges"},
 }
 
@@ -100,6 +113,32 @@ def _trusted(value: Any, index: int) -> TrustedCommand:
     return TrustedCommand(script, pattern)
 
 
+def _read_only(value: Any, index: int) -> ReadOnlyCommand:
+    where = f"worktree.readOnlyCommands[{index}]"
+    entry = _object(value, where, {"pattern", "env", "reason"})
+    source = _text(entry.get("pattern"), f"{where}.pattern")
+    try:
+        pattern = re.compile(source)
+    except re.error as error:
+        raise ConfigError(f"{where}.pattern is not a regular expression: {error}") from None
+    # The environment is required: an entry with no condition would widen the
+    # guard on every machine, which is what kavach's own read-only list is
+    # kept narrow to avoid.
+    raw_env = entry.get("env")
+    if not isinstance(raw_env, dict) or not raw_env:
+        raise ConfigError(f"{where}.env must be a non-empty JSON object of variable names")
+    env: list[tuple[str, tuple[str, ...]]] = []
+    for name, values in raw_env.items():
+        if not VARIABLE_NAME.fullmatch(name):
+            raise ConfigError(f"{where}.env has a key that is not a variable name: {name!r}")
+        listed = _list(values, f"{where}.env.{name}")
+        if not listed:
+            raise ConfigError(f"{where}.env.{name} must list at least one value")
+        env.append((name, tuple(_text(item, f"{where}.env.{name}[{at}]") for at, item in enumerate(listed))))
+    reason = _text(entry.get("reason"), f"{where}.reason")
+    return ReadOnlyCommand(pattern, tuple(env), reason)
+
+
 def _paired(value: Any, index: int) -> PairedChange:
     where = f"command.pairedChanges[{index}]"
     entry = _object(value, where, {"changes", "requires", "reason"})
@@ -135,7 +174,11 @@ def parse(data: Any) -> Config:
         _paired(entry, index)
         for index, entry in enumerate(_list(command.get("pairedChanges", []), "command.pairedChanges"))
     )
-    return Config(trusted, variables, reason, paired)
+    read_only = tuple(
+        _read_only(entry, index)
+        for index, entry in enumerate(_list(worktree.get("readOnlyCommands", []), "worktree.readOnlyCommands"))
+    )
+    return Config(trusted, variables, reason, paired, read_only)
 
 
 def load(environ: Mapping[str, str] | None = None) -> Config:

package/python/kavach/worktree_guard.py

@@ -594,7 +594,8 @@ def refuse_during_push(tool: object, targets: list[Path], root: Path) -> None:
 def main() -> None:
     # First, so a misread settings file refuses every event, a read-only one
     # included.
-    trusted = settings().trusted_commands
+    loaded = settings()
+    trusted = loaded.trusted_commands
     data = boundary.read_input()
     cwd = Path(data.get("cwd") or Path.cwd()).resolve()
     state = boundary.checkout_state(cwd)
@@ -616,6 +617,13 @@ def main() -> None:
         command = boundary.tool_command(values)
         if command and boundary.shell_is_read_only(command):
             return
+        # A read the consumer reviewed (`worktree.readOnlyCommands`), from the
+        # checkout's root and only in the environment its entry names: like a
+        # proven read, it needs no owned worktree and waits for no push.
+        if command and boundary.read_only_request(
+            command, cwd, root, loaded.read_only_commands, os.environ
+        ):
+            return
     # Only the shell parser reads these (a file tool is never given them), and
     # finding them costs git starts, so an Edit or Write does not pay for them.
     read_namespaces = harness_state_roots(root, primary) if tool == "Bash" else ()