Metadata-Version: 2.4
Name: capfence
Version: 0.7.0
Summary: Runtime governance for AI agents — deterministic fail-closed enforcement. Wraps any agent tool and blocks dangerous calls before execution. Zero LLM calls, zero cloud dependencies, works offline.
Project-URL: Homepage, https://capfence.dev/
Project-URL: Repository, https://github.com/capfencelabs/capfence
Project-URL: Issues, https://github.com/capfencelabs/capfence/issues
Author: Anshuman Kumar
License: MIT
License-File: LICENSE
Keywords: agents,ai,audit,compliance,crewai,enforcement,governance,guardrails,langchain,llm,runtime,safety,security,tool-calling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: crewai
Requires-Dist: crewai>=0.30; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == 'langchain'
Description-Content-Type: text/markdown

# CapFence

<p align="center">
  <strong>Deterministic runtime authorization for AI agent tool calls.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/capfence/"><img src="https://img.shields.io/pypi/v/capfence?color=blue" alt="PyPI version"></a>
  <a href="https://pypi.org/project/capfence/"><img src="https://img.shields.io/pypi/pyversions/capfence" alt="Python versions"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="Tests: passing">
</p>

CapFence sits between AI agents and their tools. It evaluates every tool call against deterministic policy before execution, then allows it, blocks it, or requires approval.

It is closer to IAM, Open Policy Agent, API gateways, and admission controllers than prompt guardrails or moderation.

```text
Agent -> CapFence -> Tool
          |
          +-- allow
          +-- deny
          +-- require approval
```

<p align="center">
  <img src="docs/assets/demo.gif" alt="CapFence terminal demo" width="720">
</p>

## Why This Exists

Agents increasingly call tools that can move money, edit databases, run shell commands, read files, modify permissions, and operate SaaS admin APIs.

Prompt instructions are not an execution boundary. CapFence gives those tool calls an explicit runtime authorization layer:

- No LLM call in the gate path.
- Policy-as-code decisions.
- Default-deny behavior when policy does not match.
- Fail-closed handling for policy and audit failures.
- Local audit logs with hash-chain verification.
- Observe mode for safe rollout before enforcement.

## Install

```bash
pip install capfence
```

## 60-Second Example

Create a policy:

```yaml
deny:
  - capability: shell.execute
    contains: "rm -rf"

require_approval:
  - capability: payments.transfer
    amount_gt: 1000

allow:
  - capability: shell.execute
  - capability: payments.transfer
    amount_lte: 1000
```

Evaluate a tool call before execution:

```python
from capfence.core.gate import Gate

gate = Gate()

result = gate.evaluate(
    agent_id="ops-agent",
    task_context="shell",
    risk_category="shell_execution",
    capability="shell.execute",
    policy_path="policies/shell_agent.yaml",
    payload={"command": "rm -rf /var/lib/postgresql"},
)

if not result.passed:
    raise PermissionError(f"Blocked: {result.reason}")
```

The dangerous command never reaches the tool.

## Framework Integrations

CapFence can wrap tools in:

- LangChain
- LangGraph
- CrewAI
- OpenAI Agents SDK
- MCP
- PydanticAI
- LlamaIndex
- AutoGen
- Direct Python runtimes

LangChain example:

```python
from capfence import CapFenceTool
from langchain.tools import ShellTool

safe_shell = CapFenceTool(
    tool=ShellTool(),
    agent_id="ops-agent",
    capability="shell.execute",
    policy_path="policies/shell_agent.yaml",
)
```

## CLI Workflows

Scan for ungated tools:

```bash
capfence check ./src --fail-on-ungated
```

Validate a policy:

```bash
capfence check-policy policies/shell_agent.yaml
```

Replay a trace through policy:

```bash
capfence simulate --trace-file traces/agent_trace.jsonl --compare
```

Verify audit-log integrity:

```bash
capfence verify --audit-log audit.db
```

## Rollout Path

1. Start in observe mode and log decisions without blocking.
2. Review audit logs and tune policies.
3. Enforce policy for high-risk tools.
4. Add CI checks so new ungated tools cannot quietly ship.
5. Replay incidents and policy changes against saved traces.

## What CapFence Is Not

CapFence is a runtime authorization and audit layer. It does not replace:

- sandboxing for shell/code execution
- least-privilege credentials
- network egress controls
- prompt-injection defenses
- human review for genuinely ambiguous high-risk actions

Use it as the deterministic control point before tool execution.

## Why Not Prompt Guardrails?

Prompt guardrails are useful, but they do not enforce execution. A prompt can be bypassed, misinterpreted, or ignored under pressure. CapFence adds a deterministic enforcement boundary that blocks tool calls before they execute and records a tamper-evident audit trail.

## Where It Sits In Your Stack

```
Agent framework -> CapFence gate -> Tool/API/DB/Shell
```

CapFence does not replace sandboxing, network egress controls, or least-privilege credentials. It complements them by enforcing runtime policy at the tool boundary.

## Project Status

CapFence is beta infrastructure for agent tool governance. The repo includes:

- deterministic gate and policy engine
- local audit log with hash-chain verification
- approval workflows
- observe mode and bypass audit trails
- framework adapters
- MCP gateway and adapter
- static scanner and CI mode
- OWASP Agentic Top 10 and EU AI Act evidence reports
- typed Python package with ruff, mypy, and pytest coverage

Current local verification: run `pytest -q`.

## Documentation

- Docs: https://capfence.dev/
- PyPI: https://pypi.org/project/capfence/
- Repository: https://github.com/capfencelabs/capfence

Useful starting points:

- [Quickstart](docs/getting-started/quickstart.md)
- [First policy](docs/getting-started/first-policy.md)
- [Recipes](docs/recipes/index.md)
- [Compatibility matrix](docs/integrations/compatibility.md)
- [Protect shell tools](docs/guides/protect-shell-tools.md)
- [Protect payment agents](docs/guides/protect-payment-agents.md)
- [Secure MCP servers](docs/guides/secure-mcp-servers.md)
- [Demo walkthrough](docs/examples/demo-walkthrough.md)
- [Demo cast](docs/examples/demo-cast.md)
- [Policy schema](docs/reference/policy-schema.md)

## Contributing

```bash
git clone https://github.com/capfencelabs/capfence.git
cd capfence
pip install -e ".[dev]"
pytest tests/ -q
```

Policy recipes, framework adapters, taxonomies, docs, and focused bug reports are welcome.

## License

MIT License

<p align="center">
  <sub>Built by <a href="https://github.com/capfencelabs">CapFence Labs</a></sub>
</p>
