diff --git a/README.md b/README.md index 1935df3..2e7cb4a 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,36 @@ -# ProofLayer Runtime +# ProofLayer Rules [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) -ProofLayer Runtime is the open runtime security layer for MCP servers and -LangGraph agents. It sits on the tool-call or agent-execution path, scans -requests with local rules, and can warn, block, or stop dangerous actions before -they reach the underlying server, tool, state update, or output stream. +ProofLayer Rules is the open runtime security, adversarial evals, and compliance +evidence layer for **LangGraph agents**, MCP-connected tools, and agent +frameworks. It wraps runtime execution, scans agent inputs, tool descriptions, +tool calls, state updates, outputs, streams, and handoffs, then warns or blocks +unsafe behavior before it reaches tools, memory, downstream agents, or users. + +```python +from prooflayer.integrations.langgraph import SecurityConfig, SecurityMiddleware + +middleware = SecurityMiddleware(SecurityConfig(prompt_injection="block")) +secured_graph = middleware.wrap(graph.compile()) +result = secured_graph.invoke({"input": user_input}) +``` + +Install the LangGraph integration: + +```bash +pip install "prooflayer-rules[langgraph]" +``` + +Other integrations use the same pattern: + +```python +from prooflayer.integrations.openai_agents import ProofLayerGuardrail + +secured_agent = ProofLayerGuardrail().wrap_agent(agent) +result = secured_agent.run("Summarize this safely.") +``` The runtime works by itself in rules-only mode. It can also call the `prooflayer-detector` service over `/v1/detect` for model-backed scoring of @@ -17,15 +41,24 @@ offering; see [proof-layer.com](https://www.proof-layer.com). ## What This Repo Contains -- Local MCP runtime wrappers for synchronous and MCP Python SDK servers. -- HTTP proxy transport for JSON-RPC `tools/call` traffic. - LangGraph runtime wrapper with prompt injection, jailbreak, tool abuse, exfiltration, scope drift, state manipulation, multi-turn, and streaming checks. +- LangChain MCP adapter and LlamaIndex wrappers for securing MCP tools, tool + descriptions, tool arguments, tool outputs, and retrieved context. +- Agent-framework adapters for OpenAI Agents SDK, CrewAI, AutoGen, Semantic + Kernel, and Pydantic AI. +- Shared integration primitives for runtime envelopes, decisions, audit + hashing, agent input/output scanning, unsafe handoff detection, role drift, + and cross-agent instruction smuggling. - Adversarial evals for LangGraph agents through a built-in suite, GARAK, and PromptFoo. - Compliance evidence mapped to NIST AI RMF, EU AI Act Articles 13-15, SOC 2 CC6/CC7, and HIPAA Security Rule. +- Five runnable LangGraph examples for RAG, tool calling, multi-agent + supervision, memory attacks, and production compliance reporting. +- Local MCP runtime wrappers for synchronous and MCP Python SDK servers. +- HTTP proxy transport for JSON-RPC `tools/call` traffic. - YAML detection rules for prompt injection, jailbreaks, command injection, data exfiltration, role manipulation, tool poisoning, SSRF/XXE, and SQL injection. @@ -37,34 +70,91 @@ offering; see [proof-layer.com](https://www.proof-layer.com). - CLI tools for local scans, rule validation, proxy mode, reports, and version checks. -## Runtime Modes +## Integration Family + +ProofLayer keeps one detection engine and audit schema across runtime surfaces. +Each integration is optional, dependency-light, and designed to preserve the +underlying framework's native invocation flow. + +| Surface | Package API | Install extra | Protected paths | +|---|---|---|---| +| MCP runtime wrapper | `prooflayer.ProofLayerRuntime` | base / `mcp` | MCP `call_tool`, JSON-RPC `tools/call` | +| LangGraph | `prooflayer.integrations.langgraph.SecurityMiddleware` | `langgraph` | graph input, nodes, tools, state, output, streams | +| LangChain MCP | `prooflayer.integrations.langchain_mcp.SecurityMiddleware` | `langchain-mcp` | tool descriptions, arguments, outputs | +| LlamaIndex | `prooflayer.integrations.llamaindex.ProofLayerToolWrapper` | `llamaindex` | tools and retrieved context chunks | +| OpenAI Agents SDK | `prooflayer.integrations.openai_agents.ProofLayerGuardrail` | `openai-agents` | agent input/output, tools, handoffs | +| CrewAI | `prooflayer.integrations.crewai.SecurityMiddleware` | `crewai` | crews, agents, tools, delegation | +| AutoGen | `prooflayer.integrations.autogen.SecurityMiddleware` | `autogen` | multi-agent messages, tools, handoffs | +| Semantic Kernel | `prooflayer.integrations.semantic_kernel.SecurityMiddleware` | `semantic-kernel` | kernels, agents, tools, handoffs | +| Pydantic AI | `prooflayer.integrations.pydantic_ai.SecurityMiddleware` | `pydantic-ai` | typed-agent input/output, tools, handoffs | + +Common detection coverage includes prompt injection, jailbreak, tool abuse, +tool poisoning, command injection, data exfiltration, scope drift, state +manipulation, multi-turn manipulation, memory poisoning, unsafe delegation, +role drift, and cross-agent instruction smuggling. + +See [docs/integrations/runtime-integrations.md](docs/integrations/runtime-integrations.md) +for the shared architecture, and the per-integration docs under +[docs/integrations/](docs/integrations/). + +## LangGraph Security Layer + +ProofLayer is complementary to LangGraph and LangSmith: + +| Layer | What it does | Provided by | +|---|---|---| +| Agent orchestration | Build, deploy, run agents | LangGraph | +| Tracing + observability | See what agents did | LangSmith | +| Generic evals | LLM-as-judge, regression tests | LangSmith | +| Adversarial evals | GARAK / PromptFoo red-team probes | ProofLayer | +| Runtime security | Real-time prompt injection, tool abuse, exfil detection + blocking | ProofLayer | +| Compliance evidence | NIST AI RMF / EU AI Act / SOC 2 / HIPAA audit-defensible reports | ProofLayer | -Rules-only mode is the default: +Configure the categories you want to warn or block: ```python -from prooflayer import ProofLayerRuntime +from prooflayer.integrations.langgraph import SecurityConfig, SecurityMiddleware -runtime = ProofLayerRuntime(action_on_threat="block") -protected_server = runtime.wrap(mcp_server) -protected_server.run() +middleware = SecurityMiddleware( + SecurityConfig( + prompt_injection="block", + jailbreak="block", + tool_abuse="block", + exfil="block", + scope_drift="warn", + state_manipulation="block", + multi_turn="warn", + compliance_frameworks=["nist_ai_rmf", "soc2"], + ) +) ``` -Detector-assisted mode calls a local `prooflayer-detector` service: +Run the examples: + +```bash +python examples/integrations/langgraph/01_simple_rag.py +python examples/integrations/langgraph/02_tool_calling_agent.py +python examples/integrations/langgraph/03_multi_agent_supervisor.py +python examples/integrations/langgraph/04_memory_attack_demo.py +python examples/integrations/langgraph/05_production_template.py +``` + +See [docs/integrations/langgraph.md](docs/integrations/langgraph.md), [docs/evals.md](docs/evals.md), and [docs/compliance.md](docs/compliance.md). + +## MCP Runtime Modes + +Rules-only mode is the default for MCP servers: ```python from prooflayer import ProofLayerRuntime -runtime = ProofLayerRuntime( - action_on_threat="block", - detector_url="http://127.0.0.1:8088", - detector_timeout_ms=250, -) +runtime = ProofLayerRuntime(action_on_threat="block") protected_server = runtime.wrap(mcp_server) protected_server.run() ``` -Detector failures degrade to rules-only scanning. Runtime does not block traffic -just because the detector is unavailable. +Detector-assisted mode calls a local `prooflayer-detector` service for MCP +traffic. Detector failures degrade to rules-only scanning. ## Install @@ -86,53 +176,36 @@ Install MCP Python SDK support: pip install -e ".[mcp]" ``` -Install LangGraph support: +Install LangGraph support from this checkout: ```bash pip install -e ".[langgraph]" ``` -Install everything: +Install MCP and agent-framework integrations from this checkout: ```bash -pip install -e ".[all]" +pip install -e ".[langchain-mcp]" +pip install -e ".[llamaindex]" +pip install -e ".[openai-agents]" +pip install -e ".[crewai]" +pip install -e ".[autogen]" +pip install -e ".[semantic-kernel]" +pip install -e ".[pydantic-ai]" ``` -## LangGraph Security Layer - -ProofLayer is complementary to LangGraph and LangSmith: - -| Layer | What it does | Provided by | -|---|---|---| -| Agent orchestration | Build, deploy, run agents | LangGraph | -| Tracing + observability | See what agents did | LangSmith | -| Generic evals | LLM-as-judge, regression tests | LangSmith | -| Adversarial evals | GARAK / PromptFoo red-team probes | ProofLayer | -| Runtime security | Real-time prompt injection, tool abuse, exfil detection + blocking | ProofLayer | -| Compliance evidence | NIST AI RMF / EU AI Act / SOC 2 / HIPAA audit-defensible reports | ProofLayer | - -Three-line integration: - -```python -from prooflayer.integrations.langgraph import SecurityConfig, SecurityMiddleware +Install everything: -middleware = SecurityMiddleware(SecurityConfig(prompt_injection="block")) -secured_graph = middleware.wrap(graph.compile()) -result = secured_graph.invoke({"input": user_input}) +```bash +pip install -e ".[all]" ``` -Run the examples: +Install all runtime integrations without eval/compliance PDF dependencies: ```bash -python examples/integrations/langgraph/01_simple_rag.py -python examples/integrations/langgraph/02_tool_calling_agent.py -python examples/integrations/langgraph/03_multi_agent_supervisor.py -python examples/integrations/langgraph/04_memory_attack_demo.py -python examples/integrations/langgraph/05_production_template.py +pip install -e ".[all-integrations]" ``` -See [docs/integrations/langgraph.md](docs/integrations/langgraph.md), [docs/evals.md](docs/evals.md), and [docs/compliance.md](docs/compliance.md). - ## Verify Locally Benign call: