Metadata-Version: 2.4
Name: handcuff
Version: 1.4.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: 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) and a **Prompt-Injection Circuit Breaker** 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. You can use the `handcuff verify` command to cryptographically re-validate the chain of events from the database or exported JSON reports. Verification pins the signature against this machine's key (or a `--pubkey` you supply for exports from other machines); record your key's fingerprint out-of-band with `handcuff key fingerprint`.
- **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 (`handcuff.rules.injection` and `llm_guard`). 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. A positive match blocks further network egress for the agent.
- **Framework Integration**: Built-in support for LangChain and LangGraph via the `HandcuffHandler`. Handcuff integrates seamlessly as a `BaseCallbackHandler`, isolating parallel runs correctly through native `run_id` state management.
- **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, eliminating recursive agent-hijacking vectors.

## Installation

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

```powershell
# Standard installation
pip install handcuff

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

## Quickstart

You can use Handcuff from the command line to monitor an agent script, view active sessions, and verify audit logs.

```powershell
# Record an agent (or any arbitrary command) and log all OS events
handcuff watch -- python my_agent.py

# Launch an MCP Proxy to intercept and secure tool calls between agents and servers
# Use `--llm-guard` to block malicious tool calls using a local Ollama model (100% private)
handcuff mcp --llm-guard npx -y @modelcontextprotocol/server-filesystem /tmp

# View the live TUI dashboard in a separate terminal
handcuff tui

# List all recorded sessions
handcuff sessions

# Replay a specific past session
handcuff replay <SESSION_ID>

# Export a tamper-evident HTML report
handcuff export <SESSION_ID> --format html

# Cryptographically verify the session's hash chain
handcuff verify <SESSION_ID>
```

### Using the LangChain Integration

Add the `HandcuffHandler` to any LangChain or LangGraph invocation to start recording agent telemetry automatically:

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

handler = HandcuffHandler()
result = my_agent.invoke(inputs, config={"callbacks": [handler]})
handler.close()
```

### Using the Docker Sandbox

For safe, isolated tool execution, use the provided `DockerSandbox`:

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

# Launch a secure container with strict memory limits and a 30-second execution timeout
with DockerSandbox() as sandbox:
    # Execute commands in the container
    sandbox.execute("echo 'Untrusted data processing'")
    
    # Safely transfer files back to the host, triggering the injection scanner
    sandbox.copy_quarantined(
        container_path="/sandbox/output.txt",
        host_path="./host_workspace/output.txt"
    )
```

## 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.*
