Metadata-Version: 2.4
Name: handcuff
Version: 1.16.0
Summary: Handcuff is a security-first observability tool for AI agents, featuring tamper-evident OS-level recording, prompt-injection circuit breakers, and Docker sandboxing.
Project-URL: Homepage, https://github.com/Mister2005/Handcuff
Project-URL: Repository, https://github.com/Mister2005/Handcuff
Project-URL: Issues, https://github.com/Mister2005/Handcuff/issues
Author: Varun Gupta
License: MIT
License-File: LICENSE
Keywords: agents,langchain,langgraph,observability,prompt-injection,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27
Requires-Dist: pillow>=10.0
Requires-Dist: psutil>=5.9
Requires-Dist: pyfiglet>=1.0
Requires-Dist: python-ulid>=2.2
Requires-Dist: rich-pixels>=3.0
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: textual>=0.58
Requires-Dist: typer>=0.12
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
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: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: proxy
Requires-Dist: mitmproxy>=10.0; extra == 'proxy'
Provides-Extra: sandbox
Requires-Dist: docker>=7.0.0; extra == 'sandbox'
Description-Content-Type: text/markdown

# Handcuff: Dashcam and Sandbox for AI Agents

Handcuff is a security-first observability and sandboxing tool designed specifically for AI agents. It acts as a local, tamper-evident dashcam that records the operating system-level side effects of your AI agents—such as spawned processes, written files, and open network connections.

In addition to monitoring, Handcuff provides a **Docker Sandbox** (no network, dropped capabilities, and resource ceilings by default; networking is opt-in for download workloads), a **Hybrid Prompt-Injection Circuit Breaker**, and an **MCP Proxy Firewall** to execute unverified AI-generated code or untrusted file downloads in isolation, shielding the host system from malicious actions and data breaches.

*Note: For full implementation details, architectural diagrams, and TUI screenshots, please refer to the [Handcuff GitHub Repository](https://github.com/Mister2005/Handcuff).*

## Key Features

- **Tamper-Evident Timeline**: Every system event is SHA-256 hash-chained, and session heads are Ed25519-signed. Use the `handcuff verify` command to cryptographically re-validate the chain of events from the database or exported JSON/HTML reports.
- **Docker-Isolated Sandboxing**: The `DockerSandbox` and `langchain_sandbox` integrations execute risky agent actions—such as downloading external code or cloning repositories—inside ephemeral, memory-limited Docker containers.
- **Hybrid Prompt-Injection Circuit Breaker**: Handcuff employs a true hybrid pipeline. Incoming untrusted content is first evaluated using deterministic, zero-latency regex signatures. If this rapid heuristic check is passed, Handcuff optionally falls back to a deep semantic evaluation using a local Ollama model to accurately catch novel adversarial injections and malicious payloads.
- **MCP Proxy Firewall**: Secure communication between agents and external Model Context Protocol (MCP) servers using `handcuff mcp`. Intercepts and scans tool calls using the local LLM Guard before they reach the server.
- **Live Observability**: The `handcuff tui` command opens a real-time, terminal-based dashboard displaying trust meters, flagged event cards, and live monitoring across all active agent sessions.
- **Local-Only Guarantee**: The core system is completely disconnected from external cloud services. Captured content is strictly treated as data and never interpreted as instructions.

## Installation

Handcuff requires Python 3.11 or newer. To install the package from PyPI:

```powershell
# Standard installation
pip install handcuff

# Installation with LangChain integration, MCP Proxy, and Docker Sandboxing support
pip install "handcuff[langchain,sandbox]"
```

## Complete User Guide

Handcuff can be used as a CLI tool to monitor processes, a proxy firewall for MCP servers, or a Python library integrated directly into your LangChain/LangGraph applications.

### 1. The Handcuff CLI

The `handcuff` command line tool provides a suite of features for recording and analyzing agent sessions.

- **`handcuff watch -- <command>`**
  Record an agent (or any arbitrary command) and log all OS-level events. This acts as the dashcam, recording files modified, processes spawned, and network connections opened.
  *Example:* `handcuff watch -- python my_agent.py`

- **`handcuff mcp [--llm-guard] <command>`**
  Launch an MCP Proxy to intercept and secure tool calls between agents and servers. The `--llm-guard` flag enables semantic scanning using a local Ollama model to block malicious tool calls with 100% privacy.
  *Example:* `handcuff mcp --llm-guard npx -y @modelcontextprotocol/server-filesystem /tmp`

- **`handcuff tui`**
  Open the real-time Textual UI dashboard in a separate terminal. It connects to the SQLite database and displays live events, risk meters, and critical alerts (like Quarantine violations).

- **`handcuff sessions`**
  List all recorded sessions in the local database.

- **`handcuff replay <SESSION_ID>`**
  Replay a specific past session in the terminal to see what happened step-by-step.

- **`handcuff export <SESSION_ID> --format <html|json>`**
  Export a tamper-evident report of a session to share with security teams or auditors.

- **`handcuff verify <SESSION_ID>`**
  Cryptographically verify the session's hash chain to ensure no logs were tampered with or deleted.

### 2. Python Integration (LangChain/LangGraph)

You can embed Handcuff directly into your agent's code using the `HandcuffHandler`. This integrates seamlessly as a `BaseCallbackHandler`, isolating parallel runs correctly through native `run_id` state management.

**Where to make changes:**
Simply add the handler to the `callbacks` list when invoking your agent or initializing your LLM.

```python
from handcuff.integrations.langchain import HandcuffHandler

handler = HandcuffHandler()

# Example with LangGraph or AgentExecutor
result = my_agent.invoke(
    {"input": "Do some research"}, 
    config={"callbacks": [handler]}
)
handler.close()
```

### 3. Using the Docker Sandbox

For safe, isolated tool execution, Handcuff provides the `DockerSandbox` and `langchain_sandbox` wrappers. These ensure that tools dealing with untrusted data (like web scrapers or code executors) run inside a secure container.

**Where to make changes:**
Wrap your standard LangChain tools using `langchain_sandbox` or use `DockerSandbox` manually in your custom tool definitions.

```python
from handcuff.sandbox.manager import DockerSandbox

# Hardened defaults: no network, read-only root fs, capability drop,
# memory/pids/CPU ceilings. Pass allow_network=True only for workloads
# that must reach the internet (e.g. downloading a dataset).
with DockerSandbox(allow_network=True) as sandbox:
    # Execute commands in the container
    sandbox.execute("curl -sO https://example.com/untrusted_data.csv")
    
    # Safely transfer files back to the host. 
    # This automatically triggers the Prompt-Injection Circuit Breaker (Hybrid Scanner).
    # If the file contains malicious instructions, it will raise a QuarantineViolation 
    # and DESTROY the file before it reaches your host system.
    sandbox.copy_quarantined(
        container_path="/sandbox/untrusted_data.csv",
        host_path="./host_workspace/clean_data.csv"
    )
```

## Contributing and Internal Documentation

If you are a developer and want to contribute to Handcuff, refer to the existing codebase and `CONTRIBUTING.md` for more information. The codebase is well-documented, following a modular architecture that separates concerns between monitoring, sandboxing, and the TUI.

*Note: Handcuff currently prioritizes the Windows ecosystem (psutil, watchdog, Windows ACL/Firewall) and PyInstaller for distributions. While macOS and Linux are partially supported by the underlying abstraction layers, active enforcement rules are optimized for Windows environments.*
