handcuff 0.2.3__tar.gz → 0.3.0__tar.gz

{handcuff-0.2.3 → handcuff-0.3.0}/.gitignore

@@ -26,4 +26,5 @@ AgentLens_SPEC_Part1.md
 AgentLens_SPEC_Part2.md
 AgentLens_SPEC_Part3.md
 AgentLens_SPEC_Part4.md
-__pycache__/
+__pycache__/
+Dummy Agentic Project/

{handcuff-0.2.3 → handcuff-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handcuff
-Version: 0.2.3
+Version: 0.3.0
 Summary: A dashcam for your AI agents: local, tamper-evident recorder for process/file/network activity, with a LangChain/LangGraph drop-in prompt-injection circuit breaker.
 Project-URL: Homepage, https://github.com/Mister2005/Handcuff
 Project-URL: Repository, https://github.com/Mister2005/Handcuff
@@ -38,6 +38,8 @@ Requires-Dist: pytest>=8.2; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Provides-Extra: sandbox
+Requires-Dist: docker>=7.0.0; extra == 'sandbox'
 Description-Content-Type: text/markdown
 
 # Handcuff — Documentation Index (Start Here)

handcuff-0.3.0/handcuff/integrations/langchain_sandbox.py

@@ -0,0 +1,36 @@
+"""LangChain tools that run inside a Docker Sandbox"""
+
+from pathlib import Path
+from langchain_core.tools import tool
+
+from handcuff.sandbox.manager import DockerSandbox, SandboxError, QuarantineViolation
+
+@tool
+def sandboxed_download(url: str, dest_filename: str) -> str:
+    """Download a file from a URL securely into an isolated Sandbox.
+    The file is scanned for prompt injection and malicious signatures 
+    before being copied to the local workspace.
+    
+    Args:
+        url: The URL to download.
+        dest_filename: The local filename to save the safe file to.
+    """
+    try:
+        with DockerSandbox() as sandbox:
+            container_path = "/tmp/downloaded_file"
+            # Execute python inside the container to download, safely passing url via env var
+            cmd = f"""python -c "import os, urllib.request; urllib.request.urlretrieve(os.environ['DOWNLOAD_URL'], '{container_path}')" """
+            sandbox.execute(cmd, environment={"DOWNLOAD_URL": url})
+            
+            # Copy to host through the quarantine scanner
+            host_path = Path.cwd() / dest_filename
+            sandbox.copy_quarantined(container_path, host_path)
+            
+            return f"Successfully downloaded and verified safe. Saved to {dest_filename}"
+            
+    except SandboxError as e:
+        return f"Sandbox execution failed: {e}"
+    except QuarantineViolation as e:
+        return f"QUARANTINE BLOCKED: File was malicious and destroyed in the sandbox. {e}"
+    except Exception as e:
+        return f"Error: {e}"

handcuff-0.3.0/handcuff/sandbox/__init__.py

@@ -0,0 +1,4 @@
+"""Handcuff Sandbox Module"""
+from .manager import DockerSandbox, SandboxError, QuarantineViolation
+
+__all__ = ["DockerSandbox", "SandboxError", "QuarantineViolation"]

handcuff-0.3.0/handcuff/sandbox/manager.py

@@ -0,0 +1,184 @@
+"""Docker Sandbox Manager for Handcuff Quarantine.
+
+Provides an ephemeral Docker container for executing risky agent 
+tools (e.g. downloading datasets, cloning repos) without risking 
+the host machine.
+"""
+from __future__ import annotations
+
+import io
+import os
+import tarfile
+from pathlib import Path
+
+try:
+    import docker
+    _HAS_DOCKER = True
+except ImportError:
+    _HAS_DOCKER = False
+
+from handcuff.rules.injection import scan_for_injection
+
+
+class SandboxError(Exception):
+    """Raised for general sandbox execution failures."""
+    pass
+
+
+class QuarantineViolation(PermissionError):
+    """Raised when a file fails heuristic quarantine checks and is blocked."""
+    pass
+
+
+class DockerSandbox:
+    """Ephemeral Docker container manager for secure execution and quarantine."""
+    
+    def __init__(self, image: str = "python:3.11-slim"):
+        if not _HAS_DOCKER:
+            raise ImportError("The 'docker' package is required. Run: pip install handcuff[sandbox]")
+            
+        self.image = image
+        try:
+            self.client = docker.from_env()
+            # Test connection
+            self.client.ping()
+        except docker.errors.DockerException as e:
+            raise SandboxError(f"Could not connect to Docker Daemon. Is Docker running? Details: {e}")
+            
+        self.container = None
+
+    def __enter__(self) -> DockerSandbox:
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.stop()
+
+    def start(self) -> None:
+        """Starts the ephemeral container."""
+        try:
+            # Ensure image exists locally, pull if not
+            try:
+                self.client.images.get(self.image)
+            except docker.errors.ImageNotFound:
+                self.client.images.pull(self.image)
+                
+            self.container = self.client.containers.run(
+                self.image,
+                command="tail -f /dev/null",  # Keep alive
+                detach=True,
+                network_mode="bridge",
+                remove=True, # Auto-remove when stopped
+                cap_drop=["ALL"], # Drop all privileges for security
+                mem_limit="512m"
+            )
+        except Exception as e:
+            raise SandboxError(f"Failed to start Docker sandbox: {e}")
+
+    def stop(self) -> None:
+        """Stops and destroys the container."""
+        if self.container:
+            try:
+                self.container.remove(force=True)
+            except Exception:
+                pass
+            self.container = None
+
+    def execute(self, cmd: str, timeout: int = 30, environment: dict | None = None) -> str:
+        """Execute a command inside the container and return stdout.
+        
+        Args:
+            cmd: Command to execute
+            timeout: Maximum execution time in seconds.
+            environment: Dictionary of environment variables to pass to the command.
+        """
+        if not self.container:
+            raise SandboxError("Sandbox is not running.")
+            
+        import threading
+        result = {"exit_code": -1, "output": b""}
+        exc = []
+        
+        def run_cmd():
+            try:
+                # exec_run returns (exit_code, output)
+                exit_code, output = self.container.exec_run(cmd, environment=environment)
+                result["exit_code"] = exit_code
+                result["output"] = output
+            except Exception as e:
+                exc.append(e)
+
+        t = threading.Thread(target=run_cmd)
+        t.start()
+        t.join(timeout=timeout)
+        
+        if t.is_alive():
+            # If still alive, it timed out. Force kill the container.
+            self.stop()
+            raise SandboxError(f"Command execution timed out after {timeout} seconds. Container was destroyed.")
+            
+        if exc:
+            raise SandboxError(f"Failed to execute command: {exc[0]}")
+            
+        if result["exit_code"] != 0:
+            raise SandboxError(f"Command failed (exit {result['exit_code']}): {result['output'].decode('utf-8', errors='replace')}")
+            
+        return result["output"].decode('utf-8', errors='replace')
+
+    def copy_quarantined(self, container_path: str, host_path: str | Path) -> None:
+        """
+        Copy a file from the container to the host, running heuristic scans
+        before persisting it to the host filesystem.
+        """
+        if not self.container:
+            raise SandboxError("Sandbox is not running.")
+            
+        try:
+            bits, stat = self.container.get_archive(container_path)
+        except docker.errors.NotFound:
+            raise FileNotFoundError(f"File {container_path} not found in sandbox.")
+            
+        # get_archive returns a tar stream. We extract it in memory.
+        tar_stream = io.BytesIO()
+        max_size = 100 * 1024 * 1024  # 100 MB limit
+        current_size = 0
+        
+        for chunk in bits:
+            current_size += len(chunk)
+            if current_size > max_size:
+                raise SandboxError("File exceeds the 100MB quarantine extraction limit.")
+            tar_stream.write(chunk)
+            
+        tar_stream.seek(0)
+        with tarfile.open(fileobj=tar_stream, mode='r') as tar:
+            members = tar.getmembers()
+            if not members:
+                raise SandboxError("Empty archive returned from container.")
+                
+            # We only support single file extraction for now
+            file_member = members[0]
+            if not file_member.isfile():
+                raise SandboxError(f"{container_path} is not a file.")
+                
+            extracted = tar.extractfile(file_member)
+            if not extracted:
+                raise SandboxError(f"Could not read {file_member.name} from archive.")
+                
+            content = extracted.read()
+            
+        # --- QUARANTINE SCAN ---
+        # Decode as string to run heuristic prompt injection scan
+        try:
+            text_content = content.decode('utf-8')
+            findings = scan_for_injection(text_content)
+            if findings:
+                reasons = ", ".join(f.reason for f in findings)
+                raise QuarantineViolation(f"Quarantine block! Malicious patterns detected: {reasons}")
+        except UnicodeDecodeError:
+            # Binary file, skip text injection scanning
+            # We could add yara rules or malware scanning here in the future
+            pass
+            
+        # --- PERSIST TO HOST ---
+        with open(host_path, 'wb') as f:
+            f.write(content)

{handcuff-0.2.3 → handcuff-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "handcuff"
-version = "0.2.3"
+version = "0.3.0"
 description = "A dashcam for your AI agents: local, tamper-evident recorder for process/file/network activity, with a LangChain/LangGraph drop-in prompt-injection circuit breaker."
 readme = "00_README_START_HERE.md"
 requires-python = ">=3.10"
@@ -59,6 +59,9 @@ dev = [
 langchain = [
     "langchain-core>=0.2",
 ]
+sandbox = [
+    "docker>=7.0.0",
+]
 
 [tool.ruff]
 line-length = 100

handcuff-0.2.3/01KX3HRHQKZHGVE0TWJV1SH6MX.json

@@ -1,118 +0,0 @@
-{
-  "session": {
-    "id": "01KX3HRHQKZHGVE0TWJV1SH6MX",
-    "label": null,
-    "target_cmd": "python main.py",
-    "root_pid": 40008,
-    "started_at": 1783604463347,
-    "ended_at": 1783604464847,
-    "status": "CLOSED"
-  },
-  "events": [
-    {
-      "seq": 0,
-      "ts": 1783604463387,
-      "kind": "PROCESS_SPAWN",
-      "pid": 40008,
-      "ppid": 40008,
-      "payload": {
-        "argv": [
-          "python",
-          "main.py"
-        ],
-        "cwd": "C:\\Users\\Varun\\Desktop\\Main\\Personal Learning\\Handcuff\\Dummy Agentic Project",
-        "exe": "C:\\Program Files\\Python310\\python.exe",
-        "user": "LAPTOP-3FU0HLB5\\Varun"
-      },
-      "prev_hash": "0000000000000000000000000000000000000000000000000000000000000000",
-      "hash": "047618168c7d6a803b7b76e778b6fd05135ad6c81e469cc00588221e9ad21e57"
-    },
-    {
-      "seq": 1,
-      "ts": 1783604464262,
-      "kind": "NET_CONNECT",
-      "pid": 40008,
-      "ppid": null,
-      "payload": {
-        "bytes": 0,
-        "domain": "pt-in-f153.1e100.net",
-        "dst_ip": "2404:6800:4000:100c::99",
-        "port": 443,
-        "proto": "tcp"
-      },
-      "prev_hash": "047618168c7d6a803b7b76e778b6fd05135ad6c81e469cc00588221e9ad21e57",
-      "hash": "ed20e99732dc71fbe7128414b9b66d0de07dcc5c3abaf20dbee7f7d394fe1718"
-    },
-    {
-      "seq": 2,
-      "ts": 1783604464262,
-      "kind": "ALERT",
-      "pid": null,
-      "ppid": null,
-      "payload": {
-        "message": "Connection to new domain",
-        "rule_id": "unknown_domain",
-        "severity": "warn"
-      },
-      "prev_hash": "ed20e99732dc71fbe7128414b9b66d0de07dcc5c3abaf20dbee7f7d394fe1718",
-      "hash": "ae82f1646e5391bc13d7bd49fd00bae8096cf2fa29368f566c79a17cea7cd89e"
-    },
-    {
-      "seq": 3,
-      "ts": 1783604464305,
-      "kind": "FILE_WRITE",
-      "pid": null,
-      "ppid": null,
-      "payload": {
-        "bytes_delta": 46,
-        "op": "modify",
-        "path": "C:\\Users\\Varun\\Desktop\\Main\\Personal Learning\\Handcuff\\Dummy Agentic Project\\agent_output.txt"
-      },
-      "prev_hash": "ae82f1646e5391bc13d7bd49fd00bae8096cf2fa29368f566c79a17cea7cd89e",
-      "hash": "75f7802b56da702651385cfc59f44ba547ecfdce2b9508cb90ec7ed8b81153ff"
-    },
-    {
-      "seq": 4,
-      "ts": 1783604464305,
-      "kind": "FILE_WRITE",
-      "pid": null,
-      "ppid": null,
-      "payload": {
-        "bytes_delta": 46,
-        "op": "modify",
-        "path": "C:\\Users\\Varun\\Desktop\\Main\\Personal Learning\\Handcuff\\Dummy Agentic Project\\agent_output.txt"
-      },
-      "prev_hash": "75f7802b56da702651385cfc59f44ba547ecfdce2b9508cb90ec7ed8b81153ff",
-      "hash": "8b4f21a0f221a029643d1e516be579103205ae3f5e4cd08ddeb71f9b86333bb1"
-    },
-    {
-      "seq": 5,
-      "ts": 1783604464472,
-      "kind": "PROCESS_EXIT",
-      "pid": 40008,
-      "ppid": 40008,
-      "payload": {
-        "duration_ms": 1085,
-        "exit_code": null
-      },
-      "prev_hash": "8b4f21a0f221a029643d1e516be579103205ae3f5e4cd08ddeb71f9b86333bb1",
-      "hash": "7227928e46db3fc85b92f642df1e8f255033769d4949a2bbe99baab11ded5924"
-    }
-  ],
-  "alerts": [
-    {
-      "seq": 1,
-      "rule_id": "unknown_domain",
-      "severity": "warn",
-      "message": "Connection to new domain",
-      "muted": false,
-      "ts": 1783604464262
-    }
-  ],
-  "checkpoints": [],
-  "verification": {
-    "head_hash": "7227928e46db3fc85b92f642df1e8f255033769d4949a2bbe99baab11ded5924",
-    "pubkey": "7cf9d095c6d73e03e4c6dbba67b5905f9787a9705eb85068b46899642e4a8f9f",
-    "signature": "c4f1fd20bc4716fe00e47a24ded6bf86f2123a7a8b889b5d25c076917bbd87eec92221a85694761eadca19bd5a013f5e857e174485539bfc70e0847821ac4102"
-  }
-}

handcuff-0.2.3/Dummy Agentic Project/README.md

@@ -1,36 +0,0 @@
-# Dummy Agentic Project
-
-This is a sample project to demonstrate how to test the `handcuff` monitoring tool. 
-It uses LangGraph to orchestrate a workflow with two agents:
-1. **Researcher Agent**: Fetches a random joke from an external API (Network Activity).
-2. **Writer Agent**: Saves the fetched joke to a local file (File Activity).
-
-## Setup
-1. Create a virtual environment (optional but recommended):
-   ```bash
-   python -m venv .venv
-   .venv\Scripts\activate
-   ```
-2. Install dependencies:
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-## Running the Agent normally
-```bash
-python main.py
-```
-This will fetch a joke and write it to `agent_output.txt`.
-
-## Testing with Handcuff
-To verify that Handcuff successfully intercepts the network and file I/O operations, run the script wrapped with the `handcuff` CLI:
-
-```bash
-handcuff watch python main.py
-```
-
-### What to look for in Handcuff:
-- **Network Request**: Handcuff should flag the `GET` request to `official-joke-api.appspot.com`.
-- **File Activity**: Handcuff should flag the creation and write operations for `agent_output.txt`.
-
-You can view the generated reports in the terminal UI or export them to see the exact logs that Handcuff recorded.

handcuff-0.2.3/Dummy Agentic Project/agent_output.txt

@@ -1 +0,0 @@
-What do you call a pile of cats? - A Meowtain.

handcuff-0.2.3/Dummy Agentic Project/main.py

@@ -1,71 +0,0 @@
-import httpx
-from typing import TypedDict
-from langgraph.graph import StateGraph, END
-
-# Define our state
-class AgentState(TypedDict):
-    task: str
-    fetched_data: str
-    output_file: str
-    status: str
-
-# Node 1: The Researcher Agent
-# This agent's job is to fetch data from an external API
-def researcher_agent(state: AgentState):
-    print(f"[Researcher Agent] Fetching data for task: {state['task']}")
-    
-    # Simulating a web search or API call (Network Activity)
-    # We fetch a random joke to have some dynamic content
-    response = httpx.get("https://official-joke-api.appspot.com/random_joke")
-    if response.status_code == 200:
-        data = response.json()
-        joke = f"{data['setup']} - {data['punchline']}"
-    else:
-        joke = "Failed to fetch a joke."
-        
-    print(f"[Researcher Agent] Fetched data: {joke}")
-    
-    return {"fetched_data": joke}
-
-# Node 2: The Writer Agent
-# This agent's job is to save the data to a local file
-def writer_agent(state: AgentState):
-    print(f"[Writer Agent] Writing data to file: {state['output_file']}")
-    
-    # Simulating file modifications (File Activity)
-    with open(state["output_file"], "w", encoding="utf-8") as f:
-        f.write(state["fetched_data"])
-        
-    print("[Writer Agent] Data successfully written.")
-    return {"status": "completed"}
-
-# Build the Graph
-workflow = StateGraph(AgentState)
-
-# Add nodes
-workflow.add_node("researcher", researcher_agent)
-workflow.add_node("writer", writer_agent)
-
-# Add edges (Simple sequential flow)
-workflow.set_entry_point("researcher")
-workflow.add_edge("researcher", "writer")
-workflow.add_edge("writer", END)
-
-# Compile the graph
-app = workflow.compile()
-
-if __name__ == "__main__":
-    print("=== Starting LangGraph Agentic Workflow ===")
-    
-    initial_state = {
-        "task": "Find a joke",
-        "fetched_data": "",
-        "output_file": "agent_output.txt",
-        "status": "pending"
-    }
-    
-    # Run the graph
-    app.invoke(initial_state)
-    
-    print("=== Workflow Completed ===")
-    print("Check 'agent_output.txt' to see the result.")

handcuff-0.2.3/Dummy Agentic Project/requirements.txt

@@ -1,5 +0,0 @@
-langchain
-langgraph
-langchain-community
-httpx
-handcuff