ghostmode 0.1.0__tar.gz

ghostmode-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghostmode-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: ghostmode
+Version: 0.1.0
+Summary: See what your AI agent would do, without letting it do anything. Zero-config dry-run proxy for MCP servers.
+Author: David Russell
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/unwind-mcp/ghostmode
+Project-URL: Repository, https://github.com/unwind-mcp/ghostmode
+Project-URL: Full Security Suite, https://github.com/unwind-mcp/unwind
+Keywords: mcp,ai-agents,ghost-mode,dry-run,proxy,safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# Ghost Mode
+
+**See what your AI agent would do, without letting it do anything.**
+
+Ghost Mode is a safe first step before giving an AI agent real authority.
+
+It's a zero-config dry-run layer for AI agents. It intercepts every write and lets reads through. Think of it as a flight simulator for AI agents — nothing gets modified, but you see everything the agent tried to do.
+
+Requires Python 3.9+.
+
+## Quick Start
+
+### MCP Client Users (Claude Desktop, Cursor, etc.)
+
+```bash
+pip install ghostmode
+ghostmode -- npx @modelcontextprotocol/server-filesystem ~/Documents
+```
+
+Point your agent at Ghost Mode instead of the real server. When the session ends, a summary is written to `ghostmode-summary.txt` in your working directory and printed to stderr.
+
+### OpenClaw Users
+
+```bash
+# 1. Install Ghost Mode
+pip install ghostmode
+
+# 2. Install the OpenClaw plugin
+openclaw plugins install @unwind/ghostmode-openclaw
+
+# 3. Restart the gateway
+```
+
+Ghost Mode hooks into OpenClaw's tool-call system. Every write is intercepted. Every read passes through.
+
+## What it does
+
+Ghost Mode intercepts state-modifying tool calls — file writes, deletions, emails, API posts, shell commands — and returns fake success responses. The agent thinks it completed the action. Your filesystem, email, and APIs are untouched.
+
+A shadow virtual filesystem keeps the agent consistent: if it "writes" a file and then reads it back, Ghost Mode serves the written content from memory. The agent doesn't know it's in a sandbox.
+
+## Example output
+
+```
+=======================================================
+  GHOST MODE SESSION SUMMARY
+=======================================================
+  Duration:     47.3s
+  Total events: 12
+  Intercepted:  4 writes blocked
+  Passed:       7 reads forwarded
+  Shadow reads: 1 served from VFS
+
+  Files the agent tried to write:
+    /home/user/Documents/report.md
+    /home/user/Documents/summary.txt
+
+  Files the agent tried to delete:
+    /home/user/Documents/old_draft.md
+
+  4 write(s) were blocked. Nothing was modified.
+
+  Full timeline:
+  14:23:01  [PASSED]  fs_read  /home/user/Documents/notes.txt
+  14:23:02  [PASSED]  fs_list  /home/user/Documents
+  14:23:03  [BLOCKED] fs_write /home/user/Documents/report.md
+  14:23:04  [SHADOW]  fs_read  /home/user/Documents/report.md
+  14:23:05  [BLOCKED] fs_delete /home/user/Documents/old_draft.md
+  14:23:06  [BLOCKED] send_email
+  14:23:07  [PASSED]  fs_read  /home/user/Documents/config.json
+=======================================================
+```
+
+## Use cases
+
+**Testing untrusted tools.** Install a new MCP server and see what it actually does before giving it real access.
+
+**Reviewing agent behaviour.** Let your agent plan and "execute" a complex task, then review the timeline before running it for real.
+
+**Demos and training.** Show stakeholders what an AI agent workflow looks like without risking real data.
+
+**Compliance dry runs.** Verify that an agent workflow stays within policy boundaries before going live.
+
+## What Ghost Mode is not
+
+Ghost Mode does not enforce policy or provide rollback. It is a visibility tool, not a security system. If you need enforcement, audit trails, or recovery, that's what [UNWIND](https://github.com/unwind-mcp/unwind) is for.
+
+## CLI options (MCP proxy mode)
+
+```
+ghostmode -- <upstream command>        Basic usage
+ghostmode -v -- <command>              Verbose: log every action to stderr
+ghostmode --export log.json -- <cmd>   Export session log on exit
+ghostmode --also-block my_tool -- ...  Add custom tool names to intercept
+```
+
+## How it knows what to block
+
+Ghost Mode recognises 50+ common MCP tool names as state-modifying (filesystem writes, email sends, API posts, shell commands, database mutations, git operations). It also uses prefix heuristics: any tool starting with `create_`, `delete_`, `send_`, `write_`, `execute_`, etc. gets intercepted. The block list is heuristic-based and configurable.
+
+If a tool slips through, use `--also-block tool_name` to add it.
+
+## Zero dependencies
+
+Ghost Mode has no external dependencies. It uses only Python 3.9+ stdlib (asyncio, json, pathlib). It installs in under a second.
+
+## Known limitations
+
+**Shell commands can't see ghost-written files.** If the agent writes a file through Ghost Mode and then tries to run it via `bash_exec` or `shell_exec`, the shell will fail because the file only exists in the in-memory shadow VFS, not on disk. Ghost Mode works best for tool-call-level dry runs, not multi-step build/execute workflows.
+
+**Session summary in background clients.** Claude Desktop and Cursor run MCP servers in the background and may not surface stderr output. Ghost Mode automatically writes a `ghostmode-summary.txt` file to your working directory on exit. You can also use `--export log.json` for a machine-readable session log.
+
+## Want more?
+
+Ghost Mode shows you what happened. **UNWIND** lets you control it:
+
+- 15-stage enforcement pipeline (path jail, SSRF shield, DLP, canary honeypots)
+- Smart snapshots with one-command rollback
+- CRAFT tamper-evident audit chain
+- Real-time trust light dashboard
+- Detects encoded/obfuscated data exfiltration attempts
+
+```bash
+pip install unwind-mcp
+```
+
+[github.com/unwind-mcp/unwind](https://github.com/unwind-mcp/unwind)
+
+## License
+
+MIT

ghostmode-0.1.0/README.md

@@ -0,0 +1,131 @@
+# Ghost Mode
+
+**See what your AI agent would do, without letting it do anything.**
+
+Ghost Mode is a safe first step before giving an AI agent real authority.
+
+It's a zero-config dry-run layer for AI agents. It intercepts every write and lets reads through. Think of it as a flight simulator for AI agents — nothing gets modified, but you see everything the agent tried to do.
+
+Requires Python 3.9+.
+
+## Quick Start
+
+### MCP Client Users (Claude Desktop, Cursor, etc.)
+
+```bash
+pip install ghostmode
+ghostmode -- npx @modelcontextprotocol/server-filesystem ~/Documents
+```
+
+Point your agent at Ghost Mode instead of the real server. When the session ends, a summary is written to `ghostmode-summary.txt` in your working directory and printed to stderr.
+
+### OpenClaw Users
+
+```bash
+# 1. Install Ghost Mode
+pip install ghostmode
+
+# 2. Install the OpenClaw plugin
+openclaw plugins install @unwind/ghostmode-openclaw
+
+# 3. Restart the gateway
+```
+
+Ghost Mode hooks into OpenClaw's tool-call system. Every write is intercepted. Every read passes through.
+
+## What it does
+
+Ghost Mode intercepts state-modifying tool calls — file writes, deletions, emails, API posts, shell commands — and returns fake success responses. The agent thinks it completed the action. Your filesystem, email, and APIs are untouched.
+
+A shadow virtual filesystem keeps the agent consistent: if it "writes" a file and then reads it back, Ghost Mode serves the written content from memory. The agent doesn't know it's in a sandbox.
+
+## Example output
+
+```
+=======================================================
+  GHOST MODE SESSION SUMMARY
+=======================================================
+  Duration:     47.3s
+  Total events: 12
+  Intercepted:  4 writes blocked
+  Passed:       7 reads forwarded
+  Shadow reads: 1 served from VFS
+
+  Files the agent tried to write:
+    /home/user/Documents/report.md
+    /home/user/Documents/summary.txt
+
+  Files the agent tried to delete:
+    /home/user/Documents/old_draft.md
+
+  4 write(s) were blocked. Nothing was modified.
+
+  Full timeline:
+  14:23:01  [PASSED]  fs_read  /home/user/Documents/notes.txt
+  14:23:02  [PASSED]  fs_list  /home/user/Documents
+  14:23:03  [BLOCKED] fs_write /home/user/Documents/report.md
+  14:23:04  [SHADOW]  fs_read  /home/user/Documents/report.md
+  14:23:05  [BLOCKED] fs_delete /home/user/Documents/old_draft.md
+  14:23:06  [BLOCKED] send_email
+  14:23:07  [PASSED]  fs_read  /home/user/Documents/config.json
+=======================================================
+```
+
+## Use cases
+
+**Testing untrusted tools.** Install a new MCP server and see what it actually does before giving it real access.
+
+**Reviewing agent behaviour.** Let your agent plan and "execute" a complex task, then review the timeline before running it for real.
+
+**Demos and training.** Show stakeholders what an AI agent workflow looks like without risking real data.
+
+**Compliance dry runs.** Verify that an agent workflow stays within policy boundaries before going live.
+
+## What Ghost Mode is not
+
+Ghost Mode does not enforce policy or provide rollback. It is a visibility tool, not a security system. If you need enforcement, audit trails, or recovery, that's what [UNWIND](https://github.com/unwind-mcp/unwind) is for.
+
+## CLI options (MCP proxy mode)
+
+```
+ghostmode -- <upstream command>        Basic usage
+ghostmode -v -- <command>              Verbose: log every action to stderr
+ghostmode --export log.json -- <cmd>   Export session log on exit
+ghostmode --also-block my_tool -- ...  Add custom tool names to intercept
+```
+
+## How it knows what to block
+
+Ghost Mode recognises 50+ common MCP tool names as state-modifying (filesystem writes, email sends, API posts, shell commands, database mutations, git operations). It also uses prefix heuristics: any tool starting with `create_`, `delete_`, `send_`, `write_`, `execute_`, etc. gets intercepted. The block list is heuristic-based and configurable.
+
+If a tool slips through, use `--also-block tool_name` to add it.
+
+## Zero dependencies
+
+Ghost Mode has no external dependencies. It uses only Python 3.9+ stdlib (asyncio, json, pathlib). It installs in under a second.
+
+## Known limitations
+
+**Shell commands can't see ghost-written files.** If the agent writes a file through Ghost Mode and then tries to run it via `bash_exec` or `shell_exec`, the shell will fail because the file only exists in the in-memory shadow VFS, not on disk. Ghost Mode works best for tool-call-level dry runs, not multi-step build/execute workflows.
+
+**Session summary in background clients.** Claude Desktop and Cursor run MCP servers in the background and may not surface stderr output. Ghost Mode automatically writes a `ghostmode-summary.txt` file to your working directory on exit. You can also use `--export log.json` for a machine-readable session log.
+
+## Want more?
+
+Ghost Mode shows you what happened. **UNWIND** lets you control it:
+
+- 15-stage enforcement pipeline (path jail, SSRF shield, DLP, canary honeypots)
+- Smart snapshots with one-command rollback
+- CRAFT tamper-evident audit chain
+- Real-time trust light dashboard
+- Detects encoded/obfuscated data exfiltration attempts
+
+```bash
+pip install unwind-mcp
+```
+
+[github.com/unwind-mcp/unwind](https://github.com/unwind-mcp/unwind)
+
+## License
+
+MIT

ghostmode-0.1.0/ghostmode/__init__.py

@@ -0,0 +1,6 @@
+"""Ghost Mode — dry-run proxy for AI agents.
+
+See what your agent would do, before it does anything.
+"""
+
+__version__ = "0.1.0"

ghostmode-0.1.0/ghostmode/cli.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+"""Ghost Mode CLI — one command, zero config.
+
+Usage:
+    ghostmode -- npx @modelcontextprotocol/server-filesystem ~/Documents
+    ghostmode -v -- python my_mcp_server.py
+    ghostmode --export session.json -- node my_tools.js
+"""
+
+import argparse
+import asyncio
+import logging
+import sys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="ghostmode",
+        description=(
+            "\U0001f47b Ghost Mode — see what your AI agent would do, "
+            "without letting it do anything."
+        ),
+        epilog=(
+            "Example:\n"
+            "  ghostmode -- npx @modelcontextprotocol/server-filesystem ~/Documents\n"
+            "\n"
+            "Point your agent at ghostmode instead of the MCP server.\n"
+            "Reads pass through. Writes get intercepted. Nothing changes.\n"
+            "\n"
+            "For full security (rollback, enforcement, audit chain), upgrade to UNWIND:\n"
+            "  pip install unwind-mcp\n"
+            "  https://github.com/unwind-mcp/unwind"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "upstream_command",
+        nargs=argparse.REMAINDER,
+        help="The MCP server command (after --)",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Log every intercepted and passed action to stderr",
+    )
+    parser.add_argument(
+        "--export",
+        metavar="FILE",
+        help="Export the session log to a JSON file on exit",
+    )
+    parser.add_argument(
+        "--also-block",
+        metavar="TOOL",
+        action="append",
+        default=[],
+        help="Additional tool names to treat as writes (can be repeated)",
+    )
+
+    args = parser.parse_args()
+
+    # Parse upstream command
+    upstream_cmd = args.upstream_command
+    if upstream_cmd and upstream_cmd[0] == "--":
+        upstream_cmd = upstream_cmd[1:]
+
+    if not upstream_cmd:
+        print(
+            "\n  \U0001f47b Ghost Mode — dry-run proxy for AI agents\n"
+            "\n"
+            "  Usage:\n"
+            "    ghostmode -- <upstream MCP server command>\n"
+            "\n"
+            "  Examples:\n"
+            "    ghostmode -- npx @modelcontextprotocol/server-filesystem ~/Documents\n"
+            "    ghostmode -- python my_mcp_server.py\n"
+            "    ghostmode -v -- node tools_server.js\n"
+            "\n"
+            "  The agent talks to ghostmode. Reads pass through to your\n"
+            "  real MCP server. Writes get intercepted. Nothing changes.\n"
+            "\n"
+            "  When the session ends, you see everything the agent tried to do.\n",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Custom write tools
+    custom_writes = frozenset(args.also_block) if args.also_block else None
+
+    # Logging
+    level = logging.DEBUG if args.verbose else logging.WARNING
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter(
+        "%(asctime)s [ghostmode] %(message)s", datefmt="%H:%M:%S",
+    ))
+    logging.root.addHandler(handler)
+    logging.root.setLevel(level)
+
+    # Banner
+    print(
+        "\n  \U0001f47b Ghost Mode active\n"
+        f"  Upstream: {' '.join(upstream_cmd)}\n"
+        f"  Writes will be intercepted. Reads pass through.\n",
+        file=sys.stderr,
+    )
+
+    from .proxy import run_ghost_proxy
+
+    # Run with export on exit
+    async def _run():
+        from .proxy import GhostProxy
+        proxy = GhostProxy(upstream_cmd, custom_writes, args.verbose)
+        try:
+            await proxy.run()
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            pass
+        finally:
+            await proxy.shutdown()
+
+            # Export if requested
+            if args.export:
+                from pathlib import Path
+                count = proxy.log.export_json(Path(args.export))
+                print(f"\n  Exported {count} events to {args.export}", file=sys.stderr)
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

ghostmode-0.1.0/ghostmode/event_log.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+"""Ghost Mode event log — lightweight action recorder.
+
+A minimal event log that records what the agent tried to do.
+No SQLite, no hash chains — just an in-memory list with optional
+file export. This is the "See Everything" without the security
+infrastructure.
+
+For the full flight recorder with CR-AFT hash chains, tamper
+detection, and rollback, upgrade to UNWIND.
+"""
+
+import json
+import time
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class GhostEvent:
+    """A single intercepted action."""
+    timestamp: float
+    tool: str
+    action: str          # "intercepted", "passed_through", "shadow_read"
+    target: Optional[str] = None
+    parameters_summary: Optional[str] = None  # Brief summary, not full params
+    detail: Optional[str] = None
+
+
+class GhostEventLog:
+    """In-memory event log for Ghost Mode sessions."""
+
+    def __init__(self):
+        self.events: list[GhostEvent] = []
+        self._start_time: float = time.time()
+
+    def log_intercept(self, tool: str, target: Optional[str] = None,
+                      detail: Optional[str] = None) -> GhostEvent:
+        """Log an intercepted (blocked) write action."""
+        event = GhostEvent(
+            timestamp=time.time(),
+            tool=tool,
+            action="intercepted",
+            target=target,
+            detail=detail,
+        )
+        self.events.append(event)
+        return event
+
+    def log_passthrough(self, tool: str, target: Optional[str] = None) -> GhostEvent:
+        """Log a read-only action that was passed through."""
+        event = GhostEvent(
+            timestamp=time.time(),
+            tool=tool,
+            action="passed_through",
+            target=target,
+        )
+        self.events.append(event)
+        return event
+
+    def log_shadow_read(self, tool: str, target: str) -> GhostEvent:
+        """Log a read served from the shadow VFS."""
+        event = GhostEvent(
+            timestamp=time.time(),
+            tool=tool,
+            action="shadow_read",
+            target=target,
+            detail="Content served from shadow VFS (ghost-written earlier)",
+        )
+        self.events.append(event)
+        return event
+
+    @property
+    def intercepted_count(self) -> int:
+        return sum(1 for e in self.events if e.action == "intercepted")
+
+    @property
+    def passthrough_count(self) -> int:
+        return sum(1 for e in self.events if e.action == "passed_through")
+
+    @property
+    def shadow_read_count(self) -> int:
+        return sum(1 for e in self.events if e.action == "shadow_read")
+
+    @property
+    def duration_seconds(self) -> float:
+        return time.time() - self._start_time
+
+    def summary(self) -> dict:
+        """Return a session summary."""
+        return {
+            "duration_seconds": round(self.duration_seconds, 1),
+            "total_events": len(self.events),
+            "intercepted": self.intercepted_count,
+            "passed_through": self.passthrough_count,
+            "shadow_reads": self.shadow_read_count,
+        }
+
+    def format_timeline(self) -> str:
+        """Format events as a human-readable timeline."""
+        if not self.events:
+            return "  No events recorded."
+
+        lines = []
+        for event in self.events:
+            ts = time.strftime("%H:%M:%S", time.localtime(event.timestamp))
+            target_str = f" → {event.target}" if event.target else ""
+
+            if event.action == "intercepted":
+                icon = "\U0001f6ab"  # no entry
+                label = "BLOCKED"
+            elif event.action == "shadow_read":
+                icon = "\U0001f47b"  # ghost
+                label = "SHADOW"
+            else:
+                icon = "\u2705"  # check
+                label = "PASSED"
+
+            lines.append(f"  {icon} {ts}  [{label}]  {event.tool}{target_str}")
+
+            if event.detail:
+                lines.append(f"{'':>14}\u2514\u2500 {event.detail}")
+
+        return "\n".join(lines)
+
+    def export_json(self, path: Path) -> int:
+        """Export the event log to a JSON file."""
+        data = {
+            "ghostmode_version": "0.1.0",
+            "session_summary": self.summary(),
+            "events": [asdict(e) for e in self.events],
+        }
+        path.write_text(json.dumps(data, indent=2))
+        return len(self.events)
+
+    def export_jsonl(self, path: Path) -> int:
+        """Export events as newline-delimited JSON."""
+        with open(path, "w") as f:
+            for event in self.events:
+                f.write(json.dumps(asdict(event)) + "\n")
+        return len(self.events)