mcp-capdiff 0.1.1__tar.gz → 0.1.3__tar.gz

mcp_capdiff-0.1.3/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes follow Keep a Changelog. Releases use semantic versioning for the CLI package; rules and output schemas are versioned independently.
+
+## [Unreleased]
+
+## [0.1.3] - 2026-10-01
+
+### Fixed
+
+- Stop ordinary string, datetime, and other object `.replace()` calls from being classified as filesystem writes; retain detection for `os.replace(...)` and statically known `Path.replace(...)` calls.
+- Detect model-controlled interactive process execution through `pexpect.spawn(...)` and `pexpect.spawnu(...)`.
+- Require action verbs for semantic external-write inference so nouns such as `email` and `message` do not turn list/read tools into writes.
+- Prefer read-only tool names and explicit negation over incidental destructive words in descriptions while retaining destructive SQL detection for execution tools.
+
+### Verified
+
+- 71 automated tests, including positive controls for shell execution, filesystem replacement, destructive actions, and external writes.
+- `metabase-mcp` and `mcp_agent_mail`: string and datetime replacement no longer produce MCP002 findings.
+- `interactive-terminal-mcp`: `spawn_process` is classified as shell execution and produces MCP001 evidence at `pexpect.spawn(...)`.
+- `MCP-PostgreSQL-Ops` and `winremote-mcp`: the read-only statistics tool and GUI `Type` tool no longer produce MCP004/MCP010 findings.
+- The 14-repository benchmark covered 888 discovered tools; interprocedural network propagation remains deferred for a later release.
+
+## [0.1.2] - 2026-10-01
+
+### Fixed
+
+- Discover tools registered with `mcp.tool()(function)`, including functions imported from scanned project modules; unresolved static registrations now fail closed.
+- Require a concrete outbound network destination before MCP005 can classify a tool as an exfiltration sink.
+- Propagate approved-root guarantees from path-validation helpers such as `_resolve(path)` to later filesystem operations.
+- Classify `open(..., "w")`, directory creation, and local filesystem mutations as local writes instead of reads or external writes.
+
+### Verified
+
+- `python-fastmcp-server`: 3 programmatically registered tools discovered instead of a zero-tool result.
+- `sqlite-explorer-fastmcp-mcp-server`: 3 read-only tools, 0 side-effect or MCP005 findings.
+- `obsidian-mcp`: helper-scoped filesystem tools recognized as allowlisted; only 3 findings remain.
+- `smart_terminal_mcp`: critical execution findings preserved, write-mode evidence corrected, and no MCP005 paths remain.
+
+## [0.1.1] - 2026-10-01
+
+### Added
+
+- Dedicated PyPI Trusted Publishing workflow with tag-pinned builds and OIDC authentication.
+
+### Changed
+
+- Rename the PyPI distribution to `mcp-capdiff` while preserving the MCP Audit product name, `mcp_audit` import package, and `mcp-audit` command.
+- Prepare version `0.1.1` so the public `v0.1.0` tag remains immutable.
+
+## [0.1.0] - 2026-10-01
+
+### Fixed
+
+- Prevent `PostgreSQL` from being misclassified as an HTTP `POST` side effect.
+- Attach destructive semantic evidence to MCP004 and MCP010 instead of unrelated database-read evidence.
+- Fail closed on inaccessible source trees and zero-tool scans instead of reporting a false PASS.
+
+### Added
+
+- Discovery benchmark for async `@mcp.tool()` functions with FastMCP `ToolAnnotations`.
+- Explicit `--allow-empty` escape hatch for intentional zero-tool scans.
+- Python/FastMCP source discovery and capability extraction.
+- Nine security and regression rules in ruleset `0.1`.
+- Cross-tool sensitive-data path detection with MCP-context isolation.
+- Terminal, JSON, SARIF, manifest, and Git security-diff output.
+- Versioned report and manifest schema `1.0`.
+- Policy thresholds and reasoned, expiring suppressions.
+- Composite GitHub Action with Code Scanning upload.
+
+### Verified
+
+- External PostgreSQL MCP benchmark: 20 tools discovered, 6 legitimate findings, no known false positives from `PostgreSQL` token matching, and no false PASS.

{mcp_capdiff-0.1.1/src/mcp_capdiff.egg-info → mcp_capdiff-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-capdiff
-Version: 0.1.1
+Version: 0.1.3
 Summary: Security regression scanner for Model Context Protocol servers.
 Author: MCP Audit contributors
 License-Expression: MIT

{mcp_capdiff-0.1.1 → mcp_capdiff-0.1.3}/docs/precision-matrix.md

@@ -4,8 +4,8 @@ The release gate requires positive, negative, guarded, and edge coverage for the
 
 | Rule | True positive | True negative | Guarded safe | Tricky edge |
 | --- | --- | --- | --- | --- |
-| MCP001 | `shell_direct` | `safe_server` | `shell_safe_allowlist` | `shell_dynamic_no_shell` detects a dynamic executable without `shell=True` |
-| MCP002 | `filesystem_unrestricted` | `sensitive_read_only` | `filesystem_restricted` | `filesystem_guard_after_read` rejects a late guard |
+| MCP001 | `shell_direct` | `safe_server` | `shell_safe_allowlist` | `shell_dynamic_no_shell` and `benchmark_semantics` detect dynamic subprocess and pexpect execution |
+| MCP002 | `filesystem_unrestricted` | `sensitive_read_only` | `filesystem_restricted` | `filesystem_guard_after_read` rejects a late guard while generic `.replace()` calls remain non-filesystem operations |
 | MCP003 | `url_arbitrary` | fixed URL in demo baseline | `url_allowlisted` | hostname mention and guard-after-request remain findings |
 | MCP005 | `sensitive_to_network` | `sensitive_read_only` | constrained source-only server | root corpus proves independent MCP contexts are isolated |
 | MCP016 | network expansion diff | unchanged diff | allowlist-added demo resolves risk | a new high-impact tool is an escalation |
@@ -16,3 +16,5 @@ MCP004, MCP007, and MCP010 also have paired approved/bounded and unapproved/unbo
 `postgresql_read_only` protects the semantic classifier from matching `post` inside `PostgreSQL`; `sql_destructive` proves that actual `DELETE`/`DROP` semantics still produce MCP004 and MCP010 with relevant evidence.
 
 Discovery is separately benchmarked by `fastmcp_async_annotations`, which must find both plain async `@mcp.tool()` and `@mcp.tool(annotations=ToolAnnotations(...))` decorators. Missing targets, unreadable trees, parse failures, and unexpected zero-tool scans fail closed.
+
+Real-world regression fixtures also cover imported `mcp.tool()(function)` registration, helper-based path containment, SQLite reads, local file modes, local directory creation, `pexpect.spawn`, typed `Path.replace`, and ordinary string/datetime `.replace()` calls. MCP005 requires an actual outbound network destination; local writes and semantic-only action names cannot become exfiltration sinks. Read/list/status tools and incidental destructive words in documentation are negative cases for side-effect inference.

{mcp_capdiff-0.1.1 → mcp_capdiff-0.1.3}/docs/releasing.md

@@ -19,7 +19,7 @@ Install the wheel into a clean environment and verify `mcp-audit --version`, a p
 
 ## Publish
 
-1. Create and push the matching Git tag, such as `v0.1.1`.
+1. Create and push the matching Git tag, such as `v0.1.3`.
 2. Publish the matching GitHub Release. This automatically runs `release.yml`.
 3. Verify `pipx install mcp-capdiff` in a clean environment.
 4. Run the tagged Action from the demo repository and confirm SARIF appears in Code Scanning.

{mcp_capdiff-0.1.1 → mcp_capdiff-0.1.3}/docs/versioning.md

@@ -4,7 +4,7 @@ MCP Audit maintains four independent versions:
 
 | Contract | Current | Change policy |
 | --- | --- | --- |
-| CLI/package | `0.1.1` | Semantic versioning; pre-1.0 minor releases may change CLI behavior |
+| CLI/package | `0.1.3` | Semantic versioning; pre-1.0 minor releases may change CLI behavior |
 | Ruleset | `0.1` | Minor adds or materially changes rules; patch corrects implementation without intended semantic change |
 | JSON report schema | `1.0` | Minor changes are additive; major changes may remove fields or change meaning |
 | Manifest schema | `1.0` | Minor changes are additive; major changes may remove fields or change meaning |

mcp_capdiff-0.1.3/fixtures/benchmark_semantics/server.py

@@ -0,0 +1,88 @@
+from datetime import datetime, timezone
+from pathlib import Path
+
+import os
+import pexpect
+from fastmcp import FastMCP
+
+
+mcp = FastMCP("benchmark-semantics")
+
+
+@mcp.tool()
+def list_tables(description: str) -> str:
+    """List database tables without modifying them."""
+    return description.replace("|", "\\|")
+
+
+@mcp.tool()
+def get_message_time() -> str:
+    """Read the current message timestamp."""
+    return datetime.now(timezone.utc).replace(tzinfo=None).isoformat()
+
+
+@mcp.tool()
+def spawn_process(command: str) -> str:
+    """Spawn an interactive command."""
+    return str(pexpect.spawn(command))
+
+
+@mcp.tool()
+def spawn_unicode_process(command: str) -> str:
+    """Spawn an interactive Unicode command."""
+    return str(pexpect.spawnu(command))
+
+
+@mcp.tool()
+def get_vacuum_analyze_stats() -> str:
+    """Retrieve read-only delete and revoke statistics; does not execute destructive operations."""
+    return "stats"
+
+
+@mcp.tool(name="Type")
+def type_text(text: str) -> str:
+    """Type text into the GUI. Clear existing content first with Ctrl+A, Delete."""
+    return text
+
+
+@mcp.tool()
+def list_email_tags() -> list[str]:
+    """List email tags without changing them."""
+    return []
+
+
+@mcp.tool()
+def delete_comment(comment_id: str) -> str:
+    """Delete a remote comment."""
+    return comment_id
+
+
+@mcp.tool()
+def send_email(message: str) -> str:
+    """Send an email message."""
+    return message
+
+
+@mcp.tool()
+def send_status(status: str) -> str:
+    """Send a status notification."""
+    return status
+
+
+@mcp.tool()
+def delete_history(history_id: str) -> str:
+    """Delete remote history."""
+    return history_id
+
+
+@mcp.tool()
+def replace_path(source: str, destination: str) -> str:
+    path = Path(source)
+    path.replace(destination)
+    return destination
+
+
+@mcp.tool()
+def replace_path_with_os(source: str, destination: str) -> str:
+    os.replace(source, destination)
+    return destination

mcp_capdiff-0.1.3/fixtures/filesystem_helper_restricted/server.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+
+ROOT = Path("vault").resolve()
+mcp = FastMCP("filesystem-helper-restricted")
+
+
+def _resolve(relative_path: str) -> Path:
+    candidate = (ROOT / relative_path).resolve()
+    try:
+        candidate.relative_to(ROOT)
+    except ValueError as exc:
+        raise ValueError("path escapes the approved root") from exc
+    return candidate
+
+
+@mcp.tool()
+def read_note(path: str) -> str:
+    return _resolve(path).read_text(encoding="utf-8")
+
+
+@mcp.tool()
+def search_content(folder: str) -> list[str]:
+    base = _resolve(folder)
+    return [path.read_text(encoding="utf-8") for path in base.rglob("*.md")]
+
+
+@mcp.tool()
+def delete_note(path: str) -> None:
+    _resolve(path).unlink()

mcp_capdiff-0.1.3/fixtures/local_filesystem_operations/server.py

@@ -0,0 +1,31 @@
+import os
+
+from fastmcp import FastMCP
+
+
+mcp = FastMCP("local-filesystem-operations")
+
+
+@mcp.tool()
+def read_file(file: str) -> str:
+    with open(file, "r") as handle:
+        return handle.read()
+
+
+@mcp.tool()
+def write_file(file: str, content: str) -> str:
+    with open(file, "w") as handle:
+        handle.write(content)
+    return file
+
+
+@mcp.tool()
+def create_folder(folder: str) -> str:
+    os.makedirs(folder)
+    return folder
+
+
+@mcp.tool()
+def send_message(message: str) -> str:
+    """Prepare a message locally without any network destination."""
+    return message

mcp_capdiff-0.1.3/fixtures/programmatic_registration/fixture_tools/__init__.py

@@ -0,0 +1 @@
+"""Functions registered as MCP tools by the fixture server."""

mcp_capdiff-0.1.3/fixtures/programmatic_registration/fixture_tools/filesystem.py

@@ -0,0 +1,23 @@
+import os
+from pathlib import Path
+from typing import Literal
+
+
+ALLOWED_ROOTS = [str(Path("data").resolve())]
+
+
+def _validate_path(path: str) -> str:
+    resolved = os.path.realpath(path)
+    for root in ALLOWED_ROOTS:
+        prefix = root if root.endswith(os.sep) else root + os.sep
+        if resolved == root or resolved.startswith(prefix):
+            return resolved
+    raise ValueError("path is outside allowed roots")
+
+
+def read_write_file(path: str, operation: Literal["read", "write"], content: str = "") -> str:
+    resolved = _validate_path(path)
+    if operation == "read":
+        return Path(resolved).read_text(encoding="utf-8")
+    Path(resolved).write_text(content, encoding="utf-8")
+    return resolved

mcp_capdiff-0.1.3/fixtures/programmatic_registration/fixture_tools/state.py

@@ -0,0 +1,3 @@
+def get_state() -> dict:
+    """Return read-only server state."""
+    return {"status": "ready"}

mcp_capdiff-0.1.3/fixtures/programmatic_registration/server.py

@@ -0,0 +1,10 @@
+from fastmcp import FastMCP
+
+from fixture_tools.filesystem import read_write_file
+from fixture_tools.state import get_state
+
+
+mcp = FastMCP("programmatic-registration")
+
+mcp.tool()(read_write_file)
+mcp.tool(name="state")(get_state)

mcp_capdiff-0.1.3/fixtures/sqlite_read_only/server.py

@@ -0,0 +1,18 @@
+from fastmcp import FastMCP
+
+
+mcp = FastMCP("sqlite-read-only")
+
+
+@mcp.tool()
+def read_query(query: str) -> list[dict]:
+    """Execute a read-only query on the Messages database."""
+    cursor.execute(query)
+    return cursor.fetchall()
+
+
+@mcp.tool()
+def list_tables() -> list[str]:
+    """List tables from the Messages database."""
+    cursor.execute("SELECT name FROM sqlite_master WHERE type='table'")
+    return [row[0] for row in cursor.fetchall()]

{mcp_capdiff-0.1.1 → mcp_capdiff-0.1.3}/src/mcp_audit/__init__.py

@@ -1,6 +1,6 @@
 """MCP Audit public package and independently evolving contract versions."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.3"
 RULESET_VERSION = "0.1"
 REPORT_SCHEMA_VERSION = "1.0"
 MANIFEST_SCHEMA_VERSION = "1.0"

{mcp_capdiff-0.1.1 → mcp_capdiff-0.1.3}/src/mcp_audit/rules/engine.py

@@ -115,11 +115,7 @@ def _tool_findings(tool: Tool) -> list[Finding]:
 def _cross_tool_findings(tools: list[Tool]) -> list[Finding]:
     findings: list[Finding] = []
     sensitive_sources = [tool for tool in tools if tool.capability.data_access and tool.capability.sensitivity != "public"]
-    external_sinks = [
-        tool
-        for tool in tools
-        if tool.capability.network == "unrestricted_outbound" or tool.capability.side_effect in {"external_write", "public_action"}
-    ]
+    external_sinks = [tool for tool in tools if _has_external_destination(tool)]
     for source in sensitive_sources:
         for sink in external_sinks:
             if source.name == sink.name or source.context != sink.context:
@@ -152,12 +148,17 @@ def _cross_tool_findings(tools: list[Tool]) -> list[Finding]:
                     ],
                     path=[source.name, "agent_context", sink.name],
                     data_classification=data_classes,
-                    destination=sink.capability.network_destination or sink.capability.network,
+                    destination=sink.capability.network_destination,
                 )
             )
     return findings
 
 
+def _has_external_destination(tool: Tool) -> bool:
+    destination = tool.capability.network_destination
+    return tool.capability.network != "none" and bool(destination and destination != "none")
+
+
 def _evidence(tool: Tool, kinds: set[str]) -> list[Evidence]:
     return [item for item in tool.evidence if item.kind in kinds]