{"id":49909916,"url":"https://github.com/cloudmorphai/cloudmorph-tessera","last_synced_at":"2026-05-24T05:03:11.737Z","repository":{"id":357052186,"uuid":"1134700612","full_name":"CloudMorphAI/cloudmorph-tessera","owner":"CloudMorphAI","description":"Deterministic firewall for MCP agent tool calls. YAML policies, hash-chained audit, blast-radius scoring, multi-cloud cost intelligence.","archived":false,"fork":false,"pushed_at":"2026-05-16T10:59:54.000Z","size":1646,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T12:43:48.979Z","etag":null,"topics":["agent-security","agentic-ai","ai-security","aws","azure","mcp","policy-as-code","python"],"latest_commit_sha":null,"homepage":"https://cloudmorph.ai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CloudMorphAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-15T04:33:57.000Z","updated_at":"2026-05-16T10:59:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CloudMorphAI/cloudmorph-tessera","commit_stats":null,"previous_names":["cloudmorphai/cloudmorph-tessera"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/CloudMorphAI/cloudmorph-tessera","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudMorphAI%2Fcloudmorph-tessera","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudMorphAI%2Fcloudmorph-tessera/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudMorphAI%2Fcloudmorph-tessera/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudMorphAI%2Fcloudmorph-tessera/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CloudMorphAI","download_url":"https://codeload.github.com/CloudMorphAI/cloudmorph-tessera/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudMorphAI%2Fcloudmorph-tessera/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33203112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"online","status_checked_at":"2026-05-19T02:00:06.763Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-security","agentic-ai","ai-security","aws","azure","mcp","policy-as-code","python"],"created_at":"2026-05-16T12:04:31.249Z","updated_at":"2026-05-24T05:03:11.721Z","avatar_url":"https://github.com/CloudMorphAI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tessera\n\n\u003c!-- mcp-name: io.github.CloudMorphAI/tessera --\u003e\n\n**Runtime intelligent firewall for AI agent and MCP tool calls.**\n\n[![PyPI version](https://img.shields.io/pypi/v/cloudmorph-tessera.svg)](https://pypi.org/project/cloudmorph-tessera/)\n[![Python versions](https://img.shields.io/pypi/pyversions/cloudmorph-tessera.svg)](https://pypi.org/project/cloudmorph-tessera/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fcloudmorphai%2Ftessera-blue.svg)](https://ghcr.io/cloudmorphai/tessera)\n\nTessera is a deterministic in-process firewall that sits between an AI agent and every MCP server, evaluates each tool call against a YAML policy bench, and either forwards, blocks, or routes for approval — writing each decision to a hash-chained audit log.\n\n## v0.7.0 benchmarks (single worker, loopback, 24 bundled policies)\n\n| Metric | Value | Conditions |\n|---|---|---|\n| p50 HTTP cycle | **6.40 ms** | 10 concurrent conns, full proxy stack (auth + 24-policy eval + SQLite audit write) |\n| p99 HTTP cycle | **12.30 ms** | 10 concurrent conns, SQLite write jitter is dominant |\n| Sustained throughput | **2,009 RPS** | 200 concurrent conns, single uvicorn worker (linear with N workers behind nginx) |\n| Engine-eval microbench | 25-86 µs | in-process only, no HTTP, no audit |\n| HTTP overhead above engine | ~6.3 ms p50 | uvicorn + auth + audit write + JSON serde |\n\nHardware: Intel Core Ultra 5 115U (15W mobile chip), WSL2. Honest developer-hardware numbers — not inflated production claims. Full methodology: [benchmarks/results/v0.4.0-production.md](benchmarks/results/v0.4.0-production.md).\n\n## Install + first block in 60 seconds\n\n```bash\npip install cloudmorph-tessera\ntessera init                                        # writes tessera.yaml + policies/ in cwd\nTESSERA_BEARER_TOKEN=\"tk_$(openssl rand -hex 16)\" tessera serve\n```\n\nTessera now listens on `http://127.0.0.1:8080/mcp/\u003cupstream\u003e`. Wire it into Cursor / Claude Code / your agent's MCP config (recipes in [recipes/](recipes/)), and every `tools/call` flows through 24 bundled defensive policies — `prod-protection`, `cost-cap`, `secret-leak-block`, `prompt-injection-heuristic`, `aws-mcp-passrole-guard`, plus 19 others.\n\n---\n\n## What this protects against\n\nConcrete categories the 24 bundled policies cover out of the box:\n\n- **Cost spikes** — `cost-cap`, `aws-bedrock-cost-ceiling-EXAMPLE`, `aws-cost-runaway-stop-EXAMPLE`, `aws-ec2-cost-cap-EXAMPLE`. Per-call ceiling, daily cumulative ceiling, model-specific Bedrock ceiling.\n- **IAM blast-radius expansion** — `aws-mcp-passrole-guard`, `aws-mcp-admin-policy-deny`, `aws-mcp-create-access-key-deny`, `aws-iam-blast-radius-EXAMPLE`. PassRole approval gate, AWS-managed-admin attach hard-deny, access-key creation deny, principal-count guard.\n- **Destructive operations on production** — `prod-protection`, `non-prod-only`, `write-action-approval`. Block by tag or name pattern, default-deny writes on prod, require human approval for delete-class actions.\n- **Secret / PII exfiltration in arguments** — `secret-leak-block`, `pii-block`. Regex bench for API keys + tokens + SSN + credit-card numbers in tool-call args.\n- **Prompt injection signals** — `prompt-injection-heuristic`. Regex bench for common jailbreak strings (`ignore previous`, `system: you are now`, etc.).\n- **Region / data-residency violations** — `data-residency-eu`, `aws-region-allowlist-EXAMPLE`. Block ops outside permitted regions.\n- **MCP server hygiene** — `aws-mcp-rds-public-deny`, `aws-mcp-ec2-imdsv1-deny`, `aws-mcp-kms-deletion-approval`. RDS public-access block, EC2 IMDSv1 deny, KMS deletion approval gate.\n\nVendor-specific packs (GitHub, Jira, Salesforce, Slack, Postgres, OWASP prompt injection, OWASP tool poisoning) are available via the Tessera Cloud premium pack `vendor-mcp-protection` — `tessera intelligence pull vendor-mcp-protection`.\n\n## How it works\n\n```\n                ┌──────────────┐                ┌──────────────┐\n   prompt  ───→ │   AI Agent   │ ─── MCP ──→    │   Tessera    │ ───→ MCP upstream\n                │ (Claude /    │   tools/call   │  auth +      │      (AWS, GitHub,\n                │  GPT / etc.) │                │  policy +    │ ◄─── Slack, your own)\n                └──────────────┘                │  audit       │\n                                                └──────┬───────┘\n                                                       │ block / allow / require_approval\n                                                       ▼\n                                                  hash-chain audit log\n```\n\nEvery inbound `POST /mcp/{upstream}` is:\n\n1. **Authenticated** — bearer token matched; `AuthContext.scope` assigned (isolates audit streams per token).\n2. **Evaluated** — policy engine walks the sorted set (descending `priority`, first-match-wins). Returns `allow`, `block`, `log_only`, or `require_approval`.\n3. **Audited** — the decision is written to a SHA-256 hash-chain; `tessera audit verify` detects any tamper or gap.\n\nIn `enforcement` mode a `block` returns a JSON-RPC error and never touches the upstream. In `log_only` mode the upstream is always called and the decision rides in `X-Tessera-Decision` / `X-Tessera-Policy-Id` / `X-Tessera-Reason` response headers.\n\nThe engine is pure Python — no OPA, no LLM round-trip, no cloud credentials. Policy outcomes are deterministic.\n\n## Tier levels\n\n| Tier | Engine + 24 bundled policies | Premium packs |\n|---|---|---|\n| **Free** | Yes (local enforcement, hash-chain audit, multi-token scoping) | None |\n| **Developer** | Yes | `aws-cost-aware-defaults`, `vendor-mcp-protection` |\n| **Team** | Yes | + `hipaa-guardrails`, `pci-dss-controls` |\n| **Enterprise** | Yes | All 12 packs (tri-cloud AWS+Azure+GCP), custom-pack authoring |\n\nPremium packs are fetched from the Tessera Cloud CDN, Ed25519-signature-verified, and cached locally. Free-tier installs continue to enforce 24 bundled policies with no network calls.\n\n## Installation\n\n```bash\n# Local development / CLI use\npip install cloudmorph-tessera\n\n# With optional extras\npip install \"cloudmorph-tessera[aws,gemini,intelligence,infracost,observability]\"\n\n# Production deploy (recommended)\ndocker pull ghcr.io/cloudmorphai/tessera:0.7.0\n```\n\nAfter install: `tessera version` prints `tessera 0.7.0`. Full install matrix + supported Python versions: [docs/INSTALL.md](docs/INSTALL.md).\n\n## Wire it into Cursor\n\n```bash\ntessera serve --bind 127.0.0.1:8080\n```\n\nThen add to `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\\.cursor\\mcp.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"tessera\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8080/mcp\"\n    }\n  }\n}\n```\n\nRestart Cursor. Tessera appears in the MCP indicator. Every Cursor tool call is now policy-checked and audit-logged.\n\nFor Claude Code, Claude Desktop, VS Code Copilot, Continue, Cline, generic shell hooks, and the Cursor Hooks integration: [recipes/](recipes/) and [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).\n\n## Routing pattern — make Tessera the agent's default\n\nAdding Tessera as one of many available MCP servers isn't enough — the agent will often prefer the direct cloud MCP server because it sees both. To make Tessera the default route, instruct the agent in its system context.\n\nFor Claude Code, drop a `CLAUDE.md` at project root:\n\n```markdown\n# Tool routing — use Tessera as the MCP firewall\n\nWhen this project calls MCP tools that touch cloud resources (AWS, GCP, Azure,\nDatabricks, Snowflake, GitHub, Slack, Postgres, Kubernetes):\n\n- Always prefer the `tessera` MCP server if the same tool is reachable through it.\n- If a tool is only available via a direct cloud MCP server, stop and ask the\n  user before proceeding — don't silently bypass the firewall.\n- When a block response carries `error.data._meta.tessera_audit_event_id`,\n  surface the policy reason to the user verbatim.\n```\n\nEquivalent goes in `.cursorrules` for Cursor, or the system prompt for Claude Desktop. This pattern is the difference between \"a firewall the user must remember to use\" and \"a firewall the agent uses by default.\"\n\n## Configuration at a glance\n\n```yaml\nlisten:\n  host: 127.0.0.1\n  port: 8080\n\nauth:\n  type: bearer\n\npolicies:\n  dir: /etc/tessera/policies\n  reload: watch\n  mode: log_only           # enforcement | log_only | observation\n  default_action: block\n\nupstreams:\n  - name: aws\n    kind: aws_mcp\n    url: https://mcp.amazonaws.com\n    aws_region: us-east-1\n```\n\nFull reference: [docs/CONFIGURATION.md](docs/CONFIGURATION.md). Annotated example: [tessera.example.yaml](tessera.example.yaml).\n\n## Authoring policies\n\nOne YAML file per rule in `policies.dir`. Files prefixed with `_` are skipped. The engine evaluates in descending `priority`; first match wins.\n\n```yaml\nid: block-delete-prod\nname: Block Delete in Production\ndescription: Block delete calls targeting prod-suffixed resources.\nmatch:\n  upstream: \"*\"\nwhen:\n  - condition: action_class_in\n    values: [\"write.delete\"]\n  - condition: arg_matches_regex\n    arg: resource_name\n    pattern: \".*-prod$\"\naction: block\nreason: \"Delete blocked on production resource\"\npriority: 90\n```\n\nValidate before deploying:\n\n```bash\ntessera policy lint --policy-dir policies/\ntessera policy test --policy-dir policies/ --fixture-dir tests/fixtures/\n```\n\n18 condition primitives shipped (`arg_equals`, `arg_matches_regex`, `arg_path_matches_regex`, `arg_in_set`, `predicted_cost`, `blast_radius`, `affected_resource_count`, `cumulative_spend_today`, `sts_chain_depth_greater_than`, `time_of_day_outside`, `any_of`, `none_of`, plus 6 more). Full catalog + fixture format: [docs/POLICIES.md](docs/POLICIES.md).\n\n## What ships\n\n- **24 bundled defensive policies** — 7 generic + 6 AWS-MCP defaults + 5 AWS-illustrative + 6 Batch 8 (intent / business-hours / oversized-payload / tool-allowlist / prompt-injection / non-prod-only).\n- **Hash-chained audit log** — SQLite-backed; per-token scope isolation; `tessera audit verify` detects gap or tamper.\n- **Three pluggable Protocols** — `Authenticator`, `PolicyLoader`, `AuditSink` resolved via importlib at startup. Same Protocols in Tessera Cloud (which swaps in Cognito + DynamoDB implementations).\n- **Three enforcement modes** — `enforcement`, `log_only`, `observation`.\n- **Multi-token bearer auth** + JWT mode (Entra / Okta / Cognito).\n- **OAuth 2.1 PKCE + DCR + introspection** for management-plane SSO.\n- **Multi-stage Docker image** — runs as UID 10001 (non-root).\n- **Observability** — Prometheus metrics + optional OpenTelemetry tracing (off by default).\n- **Optional extras** — `[aws]` (AWS-MCP routing), `[gemini]` (policy authoring), `[infracost]` (real-time cost), `[intelligence]` (premium-pack CDN client).\n\n## Tessera Cloud\n\nHosted, multi-tenant, SSO, compliance evidence export, signed premium intelligence packs. Same engine, same Protocols — the implementations are swapped (e.g., `DynamoDBPolicyLoader` instead of `FilesystemPolicyLoader`). Your existing `tessera.yaml` and policy files work without changes when you migrate. https://cloudmorph.ai\n\n## Manual smoke scenarios\n\nSix human-readable customer journeys — fresh install, intelligence fetch + verify, policy-allow, cost-cap block, tier downgrade, anonymous CDN — under [tests/scenarios/](tests/scenarios/). Run them before tagging a release.\n\n## Roadmap\n\nDetail and rationale: [docs/ROADMAP.md](docs/ROADMAP.md).\n\n- **stdio transport** — for Claude Desktop free-tier and agent runtimes that launch MCP servers as subprocesses.\n- **Postgres audit sink** — for write volumes beyond SQLite's comfort zone; the `AuditSink` Protocol is already designed for it.\n- **Native rate limiting** — per-token token bucket; workaround today is nginx/Caddy in front.\n- **Rego escape hatch** — gated on a concrete use case the YAML condition catalog cannot express.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). `pip install -e \".[dev]\"` and `pre-commit install` to get started.\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n\n## Security\n\nReport vulnerabilities privately via [SECURITY.md](SECURITY.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudmorphai%2Fcloudmorph-tessera","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudmorphai%2Fcloudmorph-tessera","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudmorphai%2Fcloudmorph-tessera/lists"}