toolgovern-cli 0.1.4__tar.gz → 0.2.0__tar.gz

{toolgovern_cli-0.1.4 → toolgovern_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: toolgovern-cli
-Version: 0.1.4
+Version: 0.2.0
 Summary: Runtime governance middleware for AI agent tool calls -- gate shell, filesystem, network, and credential access before a tool executes.
 Project-URL: Homepage, https://github.com/RudrenduPaul/toolgovern
 Project-URL: Repository, https://github.com/RudrenduPaul/toolgovern
@@ -27,7 +27,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
-Requires-Dist: cryptography<49,>=48.0.1
+Requires-Dist: cryptography<51,>=48.0.1
 Requires-Dist: pyyaml<7,>=6.0
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.0; extra == 'dev'
@@ -38,6 +38,7 @@ Requires-Dist: mcp[cli]>=2.0.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.RudrenduPaul/toolgovern -->
+
 # toolgovern (Python)
 
 Gate every tool call an AI agent makes -- shell, filesystem, network, credential access -- before
@@ -339,7 +340,7 @@ run(args=["validate", "./toolgovern.policy.yml", "--json"])
 This is a generic subprocess wrapper around the real CLI (not a second implementation of each
 subcommand), so it stays in sync with `validate`, `audit`, and any future subcommand
 automatically. This is distinct from toolgovern's `mcp_trust` module, which is a client-side
-tool for verifying the trustworthiness of *other* MCP servers an agent connects to -- this
+tool for verifying the trustworthiness of _other_ MCP servers an agent connects to -- this
 section is about toolgovern-cli exposing its own MCP server for agents to call.
 
 ## The signed audit trail

{toolgovern_cli-0.1.4 → toolgovern_cli-0.2.0}/README.md

@@ -1,4 +1,5 @@
 <!-- mcp-name: io.github.RudrenduPaul/toolgovern -->
+
 # toolgovern (Python)
 
 Gate every tool call an AI agent makes -- shell, filesystem, network, credential access -- before
@@ -300,7 +301,7 @@ run(args=["validate", "./toolgovern.policy.yml", "--json"])
 This is a generic subprocess wrapper around the real CLI (not a second implementation of each
 subcommand), so it stays in sync with `validate`, `audit`, and any future subcommand
 automatically. This is distinct from toolgovern's `mcp_trust` module, which is a client-side
-tool for verifying the trustworthiness of *other* MCP servers an agent connects to -- this
+tool for verifying the trustworthiness of _other_ MCP servers an agent connects to -- this
 section is about toolgovern-cli exposing its own MCP server for agents to call.
 
 ## The signed audit trail

{toolgovern_cli-0.1.4 → toolgovern_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "toolgovern-cli"
-version = "0.1.4"
+version = "0.2.0"
 description = "Runtime governance middleware for AI agent tool calls -- gate shell, filesystem, network, and credential access before a tool executes."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -31,7 +31,7 @@ classifiers = [
 ]
 dependencies = [
   "PyYAML>=6.0,<7",
-  "cryptography>=48.0.1,<49",
+  "cryptography>=48.0.1,<51",
 ]
 
 [project.optional-dependencies]

toolgovern_cli-0.2.0/src/toolgovern/mcp_server.py

@@ -0,0 +1,127 @@
+"""MCP server (Python): exposes the toolgovern-cli command-line tool to agent
+runtimes over stdio.
+
+Requires the `mcp` extra (`pip install "toolgovern-cli[mcp]"`). Started via
+the `toolgovern-mcp` console script (installed by `python/pyproject.toml`'s
+`[project.scripts]`).
+
+This is a generic subprocess wrapper, not a per-subcommand tool set: a
+single `run` tool shells out to `python -m toolgovern.cli <args>` (invoked by
+module rather than by looking up the `toolgovern-cli` binary on PATH, so it
+works the same whether or not the console script entry point is installed)
+and returns the result. Wrapping the CLI this way means the tool stays in
+sync with `validate`, `audit`, and any future subcommand without a matching
+MCP tool hand-written for each one.
+
+Every failure path (the subprocess never starting, timing out, exiting
+non-zero, or printing non-JSON stdout) is caught and returned as a
+`{"error": ...}` dict. This tool handler must never raise -- an uncaught
+exception here would surface as a raw MCP protocol error instead of a
+readable result.
+
+Uses `mcp.server.MCPServer`, the official SDK's current high-level server
+class (`mcp` 2.0.0+) -- earlier `mcp` 1.x releases exposed the same
+`.tool()`/`.run()` pattern under `mcp.server.fastmcp.FastMCP`, which was
+removed in the 2.0.0 release.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from typing import Any
+
+from mcp.server import MCPServer
+
+_TIMEOUT_SECONDS = 60
+
+_RUN_TOOL_DESCRIPTION = (
+    "Executes one toolgovern-cli subcommand (validate, audit, or init) and returns its "
+    "structured result. Call this to check a governance policy file for errors before "
+    "deploying it, to forensically inspect a signed trace log of the allow/deny/"
+    "require-approval decisions toolgovern's runtime tool-call gate already made for an "
+    "agent run, or to scaffold a starter policy/integration file for a detected framework "
+    "(open-multi-agent or LangGraph). This tool does not itself gate live tool calls -- that "
+    "happens inside the governed agent process via the toolgovern library -- it only "
+    "validates, audits, and scaffolds around that gate.\n\n"
+    "No API key or network access is required; everything runs locally against files you "
+    "supply. 'validate' and 'audit' are strictly read-only (they only read the policy or "
+    "trace file given). 'init' writes a new integration file to disk and will refuse to "
+    "overwrite an existing one unless '--force' is passed. 'audit --verify-chain' "
+    "cryptographically checks the trace file's hash chain for tampering; if the trace was "
+    "written with a TraceWriter secretKey, pass '--key-file <path>' to verify the "
+    "hmac-sha256 signatures, otherwise unkeyed sha256 entries verify without it. This "
+    "handler never raises -- a launch failure, timeout, non-zero exit, or non-JSON stdout is "
+    "always returned as {\"error\": ...} instead of an exception.\n\n"
+    "Parameter `args` is the literal argv you would type after `toolgovern-cli` on the "
+    "command line, as a list of strings. Real examples: run(args=[\"validate\", "
+    "\"./toolgovern.policy.yml\", \"--json\"]) to check a policy file is well-formed; "
+    "run(args=[\"audit\", \"./toolgovern-trace.jsonl\", \"--decision\", \"deny\", "
+    "\"--json\"]) to list every denied tool call in a trace log; run(args=[\"audit\", "
+    "\"./toolgovern-trace.jsonl\", \"--agent\", \"research-sub\", \"--since\", \"24h\", "
+    "\"--verify-chain\", \"--json\"]) to audit one agent's recent decisions with tamper "
+    "verification; run(args=[\"init\", \"langgraph\", \"--policy\", "
+    "\"./toolgovern.policy.yml\", \"--json\"]) to scaffold a LangGraph integration. Always "
+    "include '--json' -- without it the CLI prints human-formatted text instead of a "
+    "parseable object.\n\n"
+    "With '--json', the CLI emits exactly one JSON object to stdout (never split across "
+    "stdout/stderr): {\"ok\": true, \"command\": ..., \"data\": {...}} on success, where "
+    "'data' holds the full result (e.g. matched/total counts and TraceEntry rows for "
+    "'audit'), or {\"ok\": false, \"command\": ..., \"error\": ...} on failure. This Python "
+    "wrapper further normalizes that into {\"result\": <parsed JSON>} on a zero exit, or "
+    "{\"returncode\", \"stdout\", \"stderr\"} if stdout wasn't valid JSON (e.g. '--json' was "
+    "omitted), or {\"error\": ..., \"returncode\": ...} on a non-zero exit. Pass "
+    "run(args=[\"--help\"]) or run(args=[\"<subcommand>\", \"--help\"]) for the CLI's own "
+    "current usage text."
+)
+
+
+def build_app() -> MCPServer:
+    app = MCPServer("toolgovern")
+
+    @app.tool(description=_RUN_TOOL_DESCRIPTION)
+    def run(args: list[str]) -> dict[str, Any]:
+        try:
+            result = subprocess.run(
+                [sys.executable, "-m", "toolgovern.cli", *args],
+                capture_output=True,
+                text=True,
+                timeout=_TIMEOUT_SECONDS,
+            )
+        except OSError as error:
+            return {"error": f"failed to launch the toolgovern-cli CLI: {error}"}
+        except subprocess.TimeoutExpired:
+            return {"error": f"toolgovern-cli timed out after {_TIMEOUT_SECONDS}s"}
+
+        stdout = result.stdout.strip()
+        stderr = result.stderr.strip()
+
+        if result.returncode != 0:
+            return {
+                "error": stderr or stdout or f"toolgovern-cli exited with code {result.returncode}",
+                "returncode": result.returncode,
+            }
+
+        if not stdout:
+            return {"returncode": result.returncode, "stdout": "", "stderr": stderr}
+
+        try:
+            return {"result": json.loads(stdout)}
+        except json.JSONDecodeError:
+            # Not every subcommand supports --json (or the caller didn't
+            # pass it) -- return the raw text rather than treating this as
+            # an error.
+            return {"returncode": result.returncode, "stdout": stdout, "stderr": stderr}
+
+    return app
+
+
+def main() -> None:
+    """Entry point for the `toolgovern-mcp` console script."""
+    app = build_app()
+    app.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

{toolgovern_cli-0.1.4 → toolgovern_cli-0.2.0}/src/toolgovern/shared/paths.py

@@ -15,8 +15,18 @@ _BRACKETED_HOST_PATTERN = re.compile(r"^\[([^\]]+)\]")
 
 
 def normalize_path(raw_path: str) -> str:
-    """Collapses ``./``, trailing slashes, and duplicate slashes for stable prefix comparison."""
+    """Collapses ``./``, trailing slashes, and duplicate slashes for stable prefix comparison.
+
+    Backslashes are treated as path separators too -- the same as forward slashes -- regardless
+    of the host OS this code happens to run on. A declared scope must hold whether the target
+    path is destined for a Windows filesystem (where ``\\`` is the native separator) or is simply
+    an attacker-supplied string mixing separators to dodge a ``/``-only prefix check; without
+    this, a path like ``/allowed/sub\\..\\..\\..\\secrets`` compares as a literal child of
+    ``/allowed`` even though it resolves outside it once backslashes are treated as separators
+    downstream.
+    """
     path = raw_path.strip()
+    path = path.replace("\\", "/")
     if path.startswith("./"):
         path = path[2:]
     path = re.sub(r"/+", "/", path)
@@ -37,8 +47,13 @@ def is_path_within(candidate: str, prefix: str) -> bool:
 
 
 def contains_path_traversal(raw_path: str) -> bool:
-    """True if the path contains a ``..`` segment that could escape a scoped prefix via traversal."""
-    return ".." in raw_path.split("/")
+    """True if the path contains a ``..`` segment that could escape a scoped prefix via traversal.
+
+    Splits on both ``/`` and ``\\`` (see ``normalize_path`` above for why backslash must count as
+    a separator here too) so ``sub\\..\\..\\..\\secrets`` is caught exactly like
+    ``sub/../../../secrets``.
+    """
+    return ".." in re.split(r"[/\\]", raw_path)
 
 
 def normalize_host(host_like: str) -> str:

{toolgovern_cli-0.1.4 → toolgovern_cli-0.2.0}/tests/test_classifier_filesystem_scope.py

@@ -121,6 +121,37 @@ class TestPathTraversal:
         decision, ids = _fired(ctx)
         assert "TG02-path-traversal" in ids
 
+    # 2026-08-24 security fix: `contains_path_traversal`/`is_path_within`
+    # (python/src/toolgovern/shared/paths.py) used to split only on "/", so a backslash-delimited
+    # ".." segment (e.g. "sub\..\..\..\secrets") was never recognized as traversal -- the same
+    # string compared as a literal in-scope child of the declared prefix because it happened to
+    # start with the right characters, letting a sub-agent escape its declared filesystem scope
+    # undetected. Identical bug in the TypeScript and .NET ports; all three share this fix.
+    def test_fires_on_backslash_delimited_dotdot(self, ctx_factory):
+        ctx = ctx_factory(
+            {"path": "/workspace/sub\\..\\..\\..\\secrets", "operation": "write"},
+            scope=ScopeDeclaration(filesystem=["/workspace"]),
+        )
+        decision, ids = _fired(ctx)
+        assert decision == "deny"
+        assert "TG02-path-traversal" in ids
+
+    def test_fires_on_bare_backslash_traversal(self, ctx_factory):
+        ctx = ctx_factory(
+            {"path": "..\\..\\secrets", "operation": "read"},
+            scope=ScopeDeclaration(filesystem=["/workspace"]),
+        )
+        decision, ids = _fired(ctx)
+        assert "TG02-path-traversal" in ids
+
+    def test_fires_on_mixed_separator_traversal(self, ctx_factory):
+        ctx = ctx_factory(
+            {"path": "/workspace/sub/..\\../etc/passwd", "operation": "write"},
+            scope=ScopeDeclaration(filesystem=["/workspace"]),
+        )
+        decision, ids = _fired(ctx)
+        assert "TG02-path-traversal" in ids
+
 
 class TestSymlinkEscape:
     def test_fires_outside_scope(self, ctx_factory):

toolgovern_cli-0.2.0/tests/test_shared_paths.py

@@ -0,0 +1,43 @@
+"""Unit tests for toolgovern.shared.paths -- 2026-08-24 security fix.
+
+Previously ``normalize_path``/``contains_path_traversal`` only split on "/", so a backslash-
+delimited ".." segment was invisible to traversal detection, and a scope prefix like "/allowed"
+would treat any candidate that merely started with the literal string "/allowed/" as in-scope even
+when the remainder was pure backslash-delimited traversal
+(``/allowed/sub\\..\\..\\..\\secrets``). This undercut the "sub-agent can't reach outside its
+declared scope" guarantee identically across the TypeScript, Python, and .NET ports.
+"""
+
+from toolgovern.shared.paths import contains_path_traversal, is_path_within, normalize_path
+
+
+def test_normalize_path_converts_backslashes_to_forward_slashes():
+    assert normalize_path("workspace\\sub\\file.txt") == "workspace/sub/file.txt"
+
+
+def test_normalize_path_collapses_mixed_separators_consistently():
+    assert normalize_path("./workspace\\sub/../file.txt") == "workspace/sub/../file.txt"
+
+
+def test_contains_path_traversal_detects_backslash_delimited_dotdot():
+    assert contains_path_traversal("sub\\..\\..\\..\\secrets") is True
+
+
+def test_contains_path_traversal_detects_mixed_separator_dotdot():
+    assert contains_path_traversal("sub/..\\../secrets") is True
+
+
+def test_contains_path_traversal_false_for_clean_backslash_path():
+    assert contains_path_traversal("workspace\\sub\\file.txt") is False
+
+
+def test_contains_path_traversal_still_detects_forward_slash_case():
+    assert contains_path_traversal("../../etc/passwd") is True
+
+
+def test_is_path_within_still_recognizes_nested_path_as_in_scope():
+    assert is_path_within("/allowed/sub/dir/file.txt", "/allowed") is True
+
+
+def test_is_path_within_still_rejects_unrelated_path():
+    assert is_path_within("/other/dir/file.txt", "/allowed") is False

toolgovern_cli-0.1.4/src/toolgovern/mcp_server.py

@@ -1,129 +0,0 @@
-"""MCP server (Python): exposes the toolgovern-cli command-line tool to agent
-runtimes over stdio.
-
-Requires the `mcp` extra (`pip install "toolgovern-cli[mcp]"`). Started via
-the `toolgovern-mcp` console script (installed by `python/pyproject.toml`'s
-`[project.scripts]`).
-
-This is a generic subprocess wrapper, not a per-subcommand tool set: a
-single `run` tool shells out to `python -m toolgovern.cli <args>` (invoked by
-module rather than by looking up the `toolgovern-cli` binary on PATH, so it
-works the same whether or not the console script entry point is installed)
-and returns the result. Wrapping the CLI this way means the tool stays in
-sync with `validate`, `audit`, and any future subcommand without a matching
-MCP tool hand-written for each one.
-
-Every failure path (the subprocess never starting, timing out, exiting
-non-zero, or printing non-JSON stdout) is caught and returned as a
-`{"error": ...}` dict. This tool handler must never raise -- an uncaught
-exception here would surface as a raw MCP protocol error instead of a
-readable result.
-
-Uses `mcp.server.MCPServer`, the official SDK's current high-level server
-class (`mcp` 2.0.0+) -- earlier `mcp` 1.x releases exposed the same
-`.tool()`/`.run()` pattern under `mcp.server.fastmcp.FastMCP`, which was
-removed in the 2.0.0 release.
-"""
-
-from __future__ import annotations
-
-import json
-import subprocess
-import sys
-from typing import Any
-
-from mcp.server import MCPServer
-
-_TIMEOUT_SECONDS = 60
-
-_STATIC_FALLBACK_DESCRIPTION = (
-    "Run the toolgovern-cli command-line tool with the given argument list "
-    "and return its output. toolgovern-cli validates governance policy "
-    "files and audits signed local trace logs of allow/deny/require-"
-    "approval decisions made by toolgovern's runtime tool-call gate. Pass "
-    "the same arguments you would give the `toolgovern-cli` command on the "
-    'command line, e.g. run(args=["validate", "./toolgovern.policy.yml", '
-    '"--json"]).'
-)
-
-
-def _get_cli_help() -> str:
-    """Runs `python -m toolgovern.cli --help` to source the tool
-    description from the CLI's real, current `--help` text. Returns "" on
-    any failure so the caller can fall back to the static description
-    instead of crashing at import time."""
-    try:
-        result = subprocess.run(
-            [sys.executable, "-m", "toolgovern.cli", "--help"],
-            capture_output=True,
-            text=True,
-            timeout=_TIMEOUT_SECONDS,
-        )
-    except (OSError, subprocess.TimeoutExpired):
-        return ""
-    return (result.stdout or result.stderr).strip()
-
-
-def _build_run_description() -> str:
-    help_text = _get_cli_help()
-    if not help_text:
-        return _STATIC_FALLBACK_DESCRIPTION
-    return (
-        "Run the toolgovern-cli command-line tool with the given argument "
-        f"list and return its output.\n\n{help_text}"
-    )
-
-
-# Populated once at import time from the real, installed CLI -- not
-# hand-maintained, so it can't silently drift from actual `--help` output.
-_RUN_TOOL_DESCRIPTION = _build_run_description()
-
-
-def build_app() -> MCPServer:
-    app = MCPServer("toolgovern")
-
-    @app.tool(description=_RUN_TOOL_DESCRIPTION)
-    def run(args: list[str]) -> dict[str, Any]:
-        try:
-            result = subprocess.run(
-                [sys.executable, "-m", "toolgovern.cli", *args],
-                capture_output=True,
-                text=True,
-                timeout=_TIMEOUT_SECONDS,
-            )
-        except OSError as error:
-            return {"error": f"failed to launch the toolgovern-cli CLI: {error}"}
-        except subprocess.TimeoutExpired:
-            return {"error": f"toolgovern-cli timed out after {_TIMEOUT_SECONDS}s"}
-
-        stdout = result.stdout.strip()
-        stderr = result.stderr.strip()
-
-        if result.returncode != 0:
-            return {
-                "error": stderr or stdout or f"toolgovern-cli exited with code {result.returncode}",
-                "returncode": result.returncode,
-            }
-
-        if not stdout:
-            return {"returncode": result.returncode, "stdout": "", "stderr": stderr}
-
-        try:
-            return {"result": json.loads(stdout)}
-        except json.JSONDecodeError:
-            # Not every subcommand supports --json (or the caller didn't
-            # pass it) -- return the raw text rather than treating this as
-            # an error.
-            return {"returncode": result.returncode, "stdout": stdout, "stderr": stderr}
-
-    return app
-
-
-def main() -> None:
-    """Entry point for the `toolgovern-mcp` console script."""
-    app = build_app()
-    app.run(transport="stdio")
-
-
-if __name__ == "__main__":
-    main()