Metadata-Version: 2.4
Name: agentmesh-mesh
Version: 0.6.0
Summary: Agent security mesh: 27-endpoint proxy + 12 framework SDKs + coding-agent hooks, composing 54 Tessera modules with SPIRE, agentgateway, and OpenTelemetry.
Author: Kenith Philip
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/kenithphilip/AgentMesh
Project-URL: Repository, https://github.com/kenithphilip/AgentMesh
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: tessera-mesh>=0.6.0
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Provides-Extra: guardrail
Requires-Dist: anthropic>=0.30; extra == "guardrail"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.0.3; extra == "openai-agents"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"

# AgentMesh

[![CI](https://github.com/kenithphilip/AgentMesh/actions/workflows/ci.yml/badge.svg)](https://github.com/kenithphilip/AgentMesh/actions/workflows/ci.yml)
![license](https://img.shields.io/badge/license-AGPL--3.0-blue)
![python](https://img.shields.io/badge/python-3.12+-blue)

A security mesh for AI agent systems. Sits between your agents and the
tools they call, enforcing taint tracking, content scanning, identity
verification, and compliance audit without changing your agent code.

Built on [Tessera](https://github.com/kenithphilip/Tessera) (51 of 94
modules integrated), with support for SPIRE identity, agentgateway data
plane, and OpenTelemetry observability.

## Quickstart

```bash
# Install
pip install agentmesh-mesh tessera-mesh

# Start the demo tools server
python examples/demo_tools_server.py &

# Start the proxy
PYTHONPATH=src python -c "
from agentmesh.proxy import MeshProxy
MeshProxy(signing_key=b'your-key-here-at-least-16-bytes',
          enable_rag_guard=True).run()
"

# Run the demo (in another terminal)
pip install requests
python examples/demo_agent.py
```

## Demo output

```
  [1] Injection Detection and Taint Tracking

  search_hotels: ALLOWED
  read_webpage:  labeled trust=0 (min_trust dropped to 0)
  Scan result:   tainted=True, heuristic=1.00
  send_email:    BLOCKED (context tainted by webpage injection)

  [2] RAG Retrieval Scanning

  Clean chunk:   safe=True, action=allow
  Poison chunk:  safe=False, action=reject

  [3] Tool Shadow Detection

  Shadowed: True
    read_file <-> read_flle  distance=1

  [4] MCP Baseline Drift Detection

  Baseline saved: 2 tools
  Drift detected: True (search: modified)

  [7] Compliance Export (SARIF)

  SARIF version: 2.1.0
  Findings: 11
    [error] tessera/injection-detected
```

## 23 HTTP Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/healthz` | GET | Proxy health and feature flags |
| `/v1/evaluate` | POST | Full evaluation pipeline (identity, rate limit, policy, plan, risk) |
| `/v1/scan` | POST | Quick injection scan (no context update) |
| `/v1/label` | POST | Scan tool output and add to context |
| `/v1/policy` | GET | Current policy requirements |
| `/v1/context` | GET | Context state (segments, trust levels) |
| `/v1/context/split` | GET | Split context into trusted/untrusted halves |
| `/v1/reset` | POST | Clear context for new session |
| `/v1/rate-limit/{id}` | GET | Rate limit status per session |
| `/v1/check-server` | POST | MCP server allowlist check |
| `/v1/check-output` | POST | Output provenance and canary leakage check |
| `/v1/approve` | POST | Resolve pending human approval |
| `/v1/audit` | GET | Audit chain validity |
| `/v1/audit/sarif` | GET | SARIF 2.1.0 compliance export |
| `/v1/evidence` | GET | Signed evidence bundle |
| `/v1/provenance` | GET | Signed provenance manifest |
| `/v1/rag/scan` | POST | RAG retrieval chunk scanning |
| `/v1/mcp/baseline` | POST | Snapshot tool definitions for drift detection |
| `/v1/mcp/drift` | POST | Check tools against baseline |
| `/v1/tool-shadows` | POST | Cross-server tool name shadowing |
| `/v1/heartbeat` | POST | Agent liveness heartbeat |
| `/v1/liveness/{id}` | GET | Agent liveness state |
| `/v1/xds/snapshot` | GET | xDS-compatible policy snapshot |

OpenAPI docs available at `/docs` when the proxy is running.

## Framework SDK

Drop-in adapters for 10 frameworks that call the proxy instead of
running Tessera in-process:

| Framework        | Module                       | Class                   |
|------------------|------------------------------|-------------------------|
| LangChain        | `agentmesh.sdk.langchain`    | `MeshCallbackHandler`   |
| OpenAI Agents    | `agentmesh.sdk.openai_agents`| `MeshAgentHooks`        |
| CrewAI           | `agentmesh.sdk.crewai`       | `MeshCrewCallback`      |
| Google ADK       | `agentmesh.sdk.google_adk`   | `MeshADKCallbacks`      |
| LlamaIndex       | `agentmesh.sdk.llamaindex`   | `MeshLlamaIndexHandler` |
| LangGraph        | `agentmesh.sdk.langgraph`    | `MeshLangGraphGuard`    |
| Haystack         | `agentmesh.sdk.haystack`     | `MeshHaystackGuard`     |
| PydanticAI       | `agentmesh.sdk.pydantic_ai`  | `MeshPydanticAIGuard`   |
| NeMo Guardrails  | `agentmesh.sdk.nemo`         | `MeshRailAction`        |
| AgentDojo        | `agentmesh.sdk.agentdojo`    | `MeshToolLabeler` + `MeshToolGuard` |
| Any framework    | `agentmesh.sdk.generic`      | `MeshGuard`             |

Examples:

```python
# LangChain
from agentmesh.sdk.langchain import MeshCallbackHandler
handler = MeshCallbackHandler(proxy_url="http://localhost:9090")
chain = agent.with_config(callbacks=[handler])

# LlamaIndex
from agentmesh.sdk.llamaindex import MeshLlamaIndexHandler
from llama_index.core.callbacks import CallbackManager
handler = MeshLlamaIndexHandler(proxy_url="http://localhost:9090")
Settings.callback_manager = CallbackManager([handler])

# LangGraph (node functions, not callbacks)
from agentmesh.sdk.langgraph import MeshLangGraphGuard
guard = MeshLangGraphGuard(proxy_url="http://localhost:9090")
graph.add_node("check_tool", guard.check_tool_call)
graph.add_node("label_output", guard.label_tool_output)

# Any framework (manual control)
from agentmesh.sdk.generic import MeshGuard
with MeshGuard() as guard:
    guard.start_session("Find hotels and email me the best one")
    ok, reason = guard.before_tool("search_hotels")
    guard.after_tool("search_hotels", results)
```

## Architecture

```
Agent (any framework)
  |
  v
AgentMesh SDK adapter (or direct HTTP)
  |
  v
AgentMesh Proxy (23 endpoints, 51 Tessera modules)
  |-- Identity (SPIRE JWT-SVID, mTLS, liveness)
  |-- Content scanning (heuristic, directive, intent, unicode, PII)
  |-- Policy evaluation (taint tracking, CEL rules, plan verification)
  |-- RAG guard (retrieval chunk scanning, pattern tracking)
  |-- Risk forecasting (salami detection, irreversibility scoring)
  |-- Compliance (SARIF export, signed evidence, audit chain)
  |
  v
Upstream MCP server (agentgateway or direct)
```

## Performance

Measured on Apple M-series, FastAPI TestClient (in-process), 2,000 iterations
per endpoint per config.

| Endpoint | Minimal p50 | Default p50 | Full p50 |
|----------|-------------|-------------|----------|
| `GET /healthz` | 903us | 959us | 965us |
| `POST /v1/evaluate` (clean) | 1.35ms | **1.42ms** | 1.41ms |
| `POST /v1/evaluate` (blocked by taint) | 4.37ms | 4.58ms | 5.27ms |
| `POST /v1/scan` (clean text) | 1.94ms | 2.14ms | 2.20ms |
| `POST /v1/scan` (tainted text) | 8.41ms | 8.55ms | 8.66ms |
| `POST /v1/label` (adds to context) | 3.23ms | 3.28ms | 3.90ms |
| `GET /v1/context` | 3.57ms | 3.98ms | 4.02ms |

Feature overhead is small. Default vs minimal adds **77us p50** to the
evaluate pipeline (+6%). Full config adds 73us (+5%). The scanner cost
on tainted text (8.5ms) is the fixed work of running the sliding-window
injection detector, which is unaffected by feature flags.

Headline: **AgentMesh adds ~1.4ms p50 and ~2.1ms p99 per tool call** at
the default configuration. Reproduce with `python benchmarks/bench_proxy.py`.

## Defense layers

1. **Prompt screening** before context entry (delegated injection defense)
2. **Content scanning** (heuristic, directive, intent, unicode, schema, PII, secrets)
3. **LLM guardrail** (optional, fires only on ambiguous FREE_TEXT)
4. **Taint tracking** (min_trust floor blocks side-effecting tools)
5. **Value-level taint** (per-argument provenance via DependencyAccumulator)
6. **Read-only guard** (path traversal, mutation detection)
7. **Plan verification** (tool sequence vs user intent)
8. **Risk forecasting** (salami detection, drift, commitment creep, irreversibility scoring)
9. **Toxic flow** (blocks egress when context has both untrusted and sensitive data)
10. **RAG guard** (retrieval chunk scanning, poisoned document detection)
11. **Tool shadow detection** (cross-server typosquatting)
12. **MCP baseline drift** (rug-pull detection)
13. **Canary tokens** (output manipulation confirmation)
14. **Output provenance** (n-gram echo detection, task relevance)
15. **Trust decay** (time-based and anomaly-driven trust degradation)
16. **Cooldown escalation** (adaptive denial response)
17. **Policy invariant** (control-flow bypass detection)
18. **Provenance manifests** (signed segment chains)
19. **Evidence bundles** (signed forensic event export)
20. **SARIF compliance** (security events in standard format)
21. **Side-channel mitigations** (loop guard, structured results)
22. **CEL deny rules** (expression-based policy extension)

## Tests

```bash
pip install -e '.[dev]' tessera-mesh[agentmesh,cel,sessions]
pytest tests/ -v
# 106 passed in 5.5s
```

Install from PyPI:

```bash
pip install agentmesh-mesh
```

## Repository structure

```
src/agentmesh/
    proxy.py          Proxy with 23 endpoints (1,172 lines)
    identity.py       Signing, SPIRE, mTLS, liveness (141 lines)
    transport.py      MCP interceptor, baseline, RAG guard (173 lines)
    exports.py        SARIF, telemetry, evidence, control plane (148 lines)
    client.py         HTTP client for the proxy API (191 lines)
    sdk/              Framework adapters (LangChain, OpenAI, CrewAI, ADK)
tests/
    test_proxy.py     Core proxy tests (19)
    test_tier2_tier3.py  Production hardening tests (31)
    test_tier_ab.py   Defense-in-depth tests (38)
    test_sdk.py       SDK and client tests (18)
deployment/
    docker/           Docker Compose (SPIRE + agentgateway + proxy + OTel)
examples/
    demo_agent.py     Exercises all 23 endpoints
    demo_tools_server.py  Mock MCP tool server
docs/
    ARCHITECTURE.md   Component contracts
    OPERATOR_GUIDE.md Operations procedures
```

## License

AGPL-3.0-or-later.
