Metadata-Version: 2.4
Name: handcuff
Version: 1.16.3
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 — an antivirus for AI agents

Handcuff is a security-first observability and enforcement tool for AI agents. It records what an agent does at the OS level in a tamper-evident, hash-chained log — and it can **stop** malicious content before an agent ever sees it, through a detonate-and-verdict sandbox and, on Windows, a signed kernel driver that blocks file opens and process launches in Ring-0.

*Full architecture diagrams, TUI screenshots, and the complete guide live on the [Handcuff GitHub repository](https://github.com/Mister2005/Handcuff) — this page covers install and the essentials.*

## Key features

- **Tamper-evident recording** — every event is SHA-256 hash-chained and the session head is Ed25519-signed. `handcuff verify` re-validates the chain from the live database or an exported report.
- **Sandbox analysis before admission** — `SandboxAnalyzer` gives every intercepted download (and MCP tool payload) an approve/reject verdict *before* the agent receives it: static risk-indicator analysis always, plus detonation in a hardened, network-less Docker container when available. Falls back to static-only with no Docker installed — nothing breaks.
- **Kernel-level enforcement (Windows, optional)** — a signed minifilter driver denies file opens and process launches for anything flagged, even for a process that never calls into Handcuff. Content-hash matching catches a copy/rename of previously-flagged bytes. The deny-list persists and re-applies itself across reboots.
- **MCP proxy firewall** — `handcuff mcp` intercepts `tools/call` requests, scans them with a regex injection detector plus an optional local LLM judge (Ollama, 100% local), and returns a proper JSON-RPC error for a blocked call instead of forwarding it.
- **Prompt-injection circuit breaker** — `handcuff.gateway.Gateway` implements taint-tracking: once untrusted content is read, further network egress and out-of-workspace reads are denied for a window, cutting Simon Willison's "lethal trifecta" before it completes.
- **Live dashboard** — `handcuff tui` shows the event stream, risk score, alerts, and a kernel-enforcement panel in real time.
- **Local-only** — nothing leaves your machine except an optional, content-light webhook you configure yourself.

## Install

Requires Python 3.10+.

```bash
pip install handcuff
```

Optional extras, install only what you need:

```bash
pip install "handcuff[proxy]"      # mitmproxy, for the download-interception proxy
pip install "handcuff[sandbox]"    # docker SDK, for dynamic sandbox detonation
pip install "handcuff[mcp]"        # mcp package
pip install "handcuff[langchain]"  # langchain-core, for the HandcuffHandler callback
```

## Quickstart

```bash
handcuff init
```
```
Environment readiness:
[ ok ] Config file: ~/.config/handcuff/config.yaml
[ -- ] mitmproxy (download proxy): mitmdump not found
[ -- ] Docker (dynamic sandbox): not available
[ -- ] Ollama (LLM judge): not reachable
[ -- ] Kernel driver (Ring-0 enforcement): not loaded

Each unchecked item is optional - the tool works with whatever is available.
```

```bash
handcuff watch -- python my_agent.py
```
```
session 01KXG26CAXY0XB65RMG05EGHFD closed
```

```bash
handcuff verify 01KXG26CAXY0XB65RMG05EGHFD
```
```
chain: OK
signature: OK
```

Check a file before you trust it, no Docker required:

```bash
handcuff sandbox analyze ./suspicious_script.sh
```
```
REJECTED - high-risk static indicators
method: static-fallback
indicators: disk_wipe
```

## The CLI, at a glance

```bash
handcuff watch -- <command>          # record OS-level activity for <command>
handcuff mcp -- <command>            # MCP stdio proxy with tool-call scanning
handcuff proxy                       # download interception proxy
handcuff sandbox analyze <file>      # detonate/analyze verdict for a file
handcuff kernel status               # kernel driver load state + quarantine count
handcuff kernel quarantine <path>    # deny file opens for <path>
handcuff kernel watch <dir>          # background auto-quarantine
handcuff tui                         # live dashboard
handcuff verify <session_id>         # re-validate hash chain + signature
handcuff doctor                      # full environment diagnostics
```

Every command supports `--help`.

## Python integration

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

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

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

# Hardened defaults: no network, read-only root fs, capability drop,
# memory/pids/CPU ceilings.
with DockerSandbox(allow_network=True) as sandbox:
    sandbox.execute("curl -sO https://example.com/untrusted_data.csv")
    # Runs the injection scanner + a native-executable check before the
    # file ever reaches the host; raises QuarantineViolation and discards
    # it on a match instead.
    sandbox.copy_quarantined(
        container_path="/sandbox/untrusted_data.csv",
        host_path="./host_workspace/clean_data.csv",
    )
```

## Honest scope

- The regex/heuristic injection scanner is a tripwire against known patterns, not a semantic guarantee.
- The Gateway and MCP proxy only secure agents whose tool-calling layer routes through them — an agent with raw shell access bypasses both. The kernel driver is the only layer that doesn't depend on agent cooperation, and it requires Windows plus a one-time signed build; nothing else in Handcuff requires it.
- Dynamic sandbox execution runs scripts, not opaque binaries, and container isolation is a strong mitigation, not a zero-risk guarantee.

## Full documentation

Architecture diagrams, the complete CLI/config reference, the kernel driver build/sign workflow, and contributing guidelines: **[github.com/Mister2005/Handcuff](https://github.com/Mister2005/Handcuff)**.

*Handcuff currently prioritizes the Windows ecosystem (psutil, watchdog, Windows ACL/Firewall, the kernel driver). macOS and Linux are partially supported by the underlying capture abstractions, but enforcement (ACL/firewall/kernel) is Windows-only today.*
