custos-mcp 0.1.0__tar.gz

custos_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.custos/
+.custos-demo/
+__pycache__/
+*.egg-info/
+dist/
+build/
+node_modules/
+*.tsbuildinfo
+.pytest_cache/
+.venv/

custos_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: custos-mcp
+Version: 0.1.0
+Summary: Runtime governance, policy enforcement, and cryptographic audit ledger for MCP tool calls
+Project-URL: Homepage, https://github.com/sanjaynandanj/custos
+Project-URL: Documentation, https://github.com/sanjaynandanj/custos
+Project-URL: Repository, https://github.com/sanjaynandanj/custos
+Author: Custos contributors
+License: Apache-2.0
+Keywords: ai-agents,audit,ed25519,governance,ledger,mcp,policy
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software 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: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=41.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: cedarpy>=4.0; extra == 'all'
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: jinja2>=3.1; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.24; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.24; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
+Requires-Dist: pytest>=8; extra == 'all'
+Requires-Dist: ruff>=0.5; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
+Provides-Extra: cedar
+Requires-Dist: cedarpy>=4.0; extra == 'cedar'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.24; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otel'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == 'web'
+Requires-Dist: jinja2>=3.1; extra == 'web'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'web'
+Description-Content-Type: text/markdown
+
+# custos-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/custos-mcp.svg)](https://pypi.org/project/custos-mcp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/custos-mcp.svg)](https://pypi.org/project/custos-mcp/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/sanjaynandanj/custos/blob/main/LICENSE)
+
+Runtime governance, policy enforcement, and cryptographic audit for MCP tool calls.
+
+Every `tools/call` from an AI agent is evaluated against a policy, allowed or denied, timed, and appended to an Ed25519-signed hash-chained ledger. The ledger format is wire-compatible with the [Node package](https://www.npmjs.com/package/custos-mcp) — audit anywhere.
+
+```bash
+pip install custos-mcp[web]
+```
+
+## Quickstart
+
+```python
+from custos import Gate, Ledger, Actor, Server, generate_keypair, load_policy
+
+kp = generate_keypair()
+kp.save(".custos")
+ledger = Ledger(".custos/ledger.jsonl", kp)
+policy = load_policy("policy.yaml")
+
+gate = Gate(policy, ledger, Actor("agent-1"), Server("fs"))
+
+result = gate.call("read_file", {"path": "/workspace/x"}, fn=open_file)
+if result.allowed:
+    print(result.result)
+```
+
+## CLI
+
+```bash
+custos keygen                            # write .custos/ledger.key + ledger.pub
+custos proxy --policy policy.yaml -- python -m my_mcp_server
+custos verify --ledger .custos/ledger.jsonl
+custos bundle out.tar.gz                 # export portable evidence
+custos verify-bundle out.tar.gz
+custos serve                             # dashboard on :8787
+```
+
+## Policy DSL
+
+```yaml
+version: 1
+id: default
+default: deny
+rules:
+  - id: allow-read
+    when:
+      tool: read_file
+      args.path: {prefix: "/workspace/"}
+    decision: allow
+    reason: workspace-only reads
+```
+
+See `spec/POLICY.md` for the full grammar.

custos_mcp-0.1.0/README.md

@@ -0,0 +1,58 @@
+# custos-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/custos-mcp.svg)](https://pypi.org/project/custos-mcp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/custos-mcp.svg)](https://pypi.org/project/custos-mcp/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/sanjaynandanj/custos/blob/main/LICENSE)
+
+Runtime governance, policy enforcement, and cryptographic audit for MCP tool calls.
+
+Every `tools/call` from an AI agent is evaluated against a policy, allowed or denied, timed, and appended to an Ed25519-signed hash-chained ledger. The ledger format is wire-compatible with the [Node package](https://www.npmjs.com/package/custos-mcp) — audit anywhere.
+
+```bash
+pip install custos-mcp[web]
+```
+
+## Quickstart
+
+```python
+from custos import Gate, Ledger, Actor, Server, generate_keypair, load_policy
+
+kp = generate_keypair()
+kp.save(".custos")
+ledger = Ledger(".custos/ledger.jsonl", kp)
+policy = load_policy("policy.yaml")
+
+gate = Gate(policy, ledger, Actor("agent-1"), Server("fs"))
+
+result = gate.call("read_file", {"path": "/workspace/x"}, fn=open_file)
+if result.allowed:
+    print(result.result)
+```
+
+## CLI
+
+```bash
+custos keygen                            # write .custos/ledger.key + ledger.pub
+custos proxy --policy policy.yaml -- python -m my_mcp_server
+custos verify --ledger .custos/ledger.jsonl
+custos bundle out.tar.gz                 # export portable evidence
+custos verify-bundle out.tar.gz
+custos serve                             # dashboard on :8787
+```
+
+## Policy DSL
+
+```yaml
+version: 1
+id: default
+default: deny
+rules:
+  - id: allow-read
+    when:
+      tool: read_file
+      args.path: {prefix: "/workspace/"}
+    decision: allow
+    reason: workspace-only reads
+```
+
+See `spec/POLICY.md` for the full grammar.

custos_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "custos-mcp"
+version = "0.1.0"
+description = "Runtime governance, policy enforcement, and cryptographic audit ledger for MCP tool calls"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [{name = "Custos contributors"}]
+keywords = ["mcp", "governance", "policy", "audit", "ed25519", "ledger", "ai-agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "cryptography>=41.0",
+    "pyyaml>=6.0",
+    "click>=8.1",
+]
+
+[project.optional-dependencies]
+web = ["fastapi>=0.110", "uvicorn[standard]>=0.29", "jinja2>=3.1"]
+otel = ["opentelemetry-api>=1.24", "opentelemetry-sdk>=1.24"]
+cedar = ["cedarpy>=4.0"]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "httpx>=0.27", "ruff>=0.5"]
+all = ["custos-mcp[web,otel,cedar,dev]"]
+
+[project.scripts]
+custos = "custos.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/sanjaynandanj/custos"
+Documentation = "https://github.com/sanjaynandanj/custos"
+Repository = "https://github.com/sanjaynandanj/custos"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/custos"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

custos_mcp-0.1.0/src/custos/__init__.py

@@ -0,0 +1,35 @@
+"""Custos: runtime governance for MCP tool calls."""
+
+from custos.canonical import dumps as canonical_dumps, loads as canonical_loads
+from custos.keys import KeyPair, generate_keypair, load_keypair, load_public_key
+from custos.ledger import Ledger, LedgerError
+from custos.policy import Policy, PolicyDecision, Rule, load_policy
+from custos.record import Decision, DecisionRecord, Actor, Server
+from custos.sdk import Gate, GateResult
+from custos.verify import verify_ledger, VerifyResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Actor",
+    "canonical_dumps",
+    "canonical_loads",
+    "Decision",
+    "DecisionRecord",
+    "Gate",
+    "GateResult",
+    "generate_keypair",
+    "KeyPair",
+    "Ledger",
+    "LedgerError",
+    "load_keypair",
+    "load_policy",
+    "load_public_key",
+    "Policy",
+    "PolicyDecision",
+    "Rule",
+    "Server",
+    "verify_ledger",
+    "VerifyResult",
+    "__version__",
+]

custos_mcp-0.1.0/src/custos/adapters/__init__.py

@@ -0,0 +1 @@
+"""Optional policy engine adapters (Cedar, OPA)."""

custos_mcp-0.1.0/src/custos/adapters/cedar.py

@@ -0,0 +1,55 @@
+"""Cedar adapter (optional): requires `pip install custos-mcp[cedar]`."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+from custos.policy import PolicyDecision
+from custos.record import Decision
+
+
+@dataclass
+class CedarPolicy:
+    id: str
+    policy_text: str
+    default: Decision = Decision.DENY
+    version: int = 1
+    engine: str = "cedar"
+    rules: List = field(default_factory=list)
+
+    def __post_init__(self):
+        try:
+            import cedarpy  # noqa: F401
+        except ImportError as e:
+            raise ImportError(
+                "Cedar support requires `pip install custos-mcp[cedar]`"
+            ) from e
+
+    def evaluate(self, ctx: dict) -> PolicyDecision:
+        import cedarpy
+        # Build principal/action/resource from context
+        principal = f'Actor::"{ctx.get("actor", {}).get("id", "unknown")}"'
+        action = f'Action::"{ctx.get("tool", "unknown")}"'
+        resource = f'Server::"{ctx.get("server", {}).get("id", "unknown")}"'
+        try:
+            result = cedarpy.is_authorized(
+                self.policy_text,
+                {"schema": {}},
+                {
+                    "principal": principal,
+                    "action": action,
+                    "resource": resource,
+                    "context": ctx,
+                },
+                [],
+            )
+            allowed = bool(result.get("allowed", False))
+            reasons = result.get("reasons", [])
+            reason = ", ".join(reasons) if reasons else ("cedar allow" if allowed else "cedar deny")
+        except Exception as e:
+            return PolicyDecision(decision=Decision.ERROR, rule_id="", reason=f"cedar error: {e}")
+        return PolicyDecision(
+            decision=Decision.ALLOW if allowed else self.default,
+            rule_id="cedar",
+            reason=reason,
+        )

custos_mcp-0.1.0/src/custos/adapters/opa.py

@@ -0,0 +1,55 @@
+"""OPA adapter: evaluate policies via a locally running OPA HTTP sidecar.
+
+Presents the same interface as `custos.policy.Policy` — the ledger records
+`engine="opa"` and captures the OPA rule/reason.
+"""
+from __future__ import annotations
+
+import json
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from custos.policy import PolicyDecision
+from custos.record import Decision
+
+
+@dataclass
+class OpaPolicy:
+    id: str
+    url: str  # e.g. http://localhost:8181/v1/data/custos/authz
+    default: Decision = Decision.DENY
+    version: int = 1
+    engine: str = "opa"
+    rules: List = field(default_factory=list)
+
+    def evaluate(self, ctx: dict) -> PolicyDecision:
+        req = urllib.request.Request(
+            self.url,
+            data=json.dumps({"input": ctx}).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=2.0) as resp:
+                body = json.loads(resp.read())
+        except Exception as e:
+            return PolicyDecision(
+                decision=Decision.ERROR,
+                rule_id="",
+                reason=f"opa unreachable: {e}",
+            )
+        result = body.get("result") or {}
+        if isinstance(result, dict):
+            allow = result.get("allow", False)
+            rule = result.get("rule", "")
+            reason = result.get("reason", "")
+        else:
+            allow = bool(result)
+            rule = ""
+            reason = ""
+        return PolicyDecision(
+            decision=Decision.ALLOW if allow else self.default,
+            rule_id=rule,
+            reason=reason or ("opa allow" if allow else "opa deny"),
+        )

custos_mcp-0.1.0/src/custos/bundle.py

@@ -0,0 +1,103 @@
+"""Portable evidence bundle: tar.gz containing ledger + pubkey + policy snapshot + signed manifest."""
+from __future__ import annotations
+
+import base64
+import hashlib
+import io
+import json
+import tarfile
+import time
+from pathlib import Path
+from typing import Optional
+
+from cryptography.exceptions import InvalidSignature
+
+from custos.canonical import dumps as canonical_dumps
+from custos.keys import KeyPair, public_key_from_b64
+
+
+def create_bundle(
+    ledger_path: str | Path,
+    pubkey_path: str | Path,
+    output_path: str | Path,
+    keypair: KeyPair,
+    policies_dir: Optional[str | Path] = None,
+) -> Path:
+    ledger_path = Path(ledger_path)
+    pubkey_path = Path(pubkey_path)
+    output_path = Path(output_path)
+
+    records = 0
+    with ledger_path.open("rb") as f:
+        for line in f:
+            if line.strip():
+                records += 1
+
+    manifest = {
+        "v": 1,
+        "created": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "records": records,
+        "pubkey": Path(pubkey_path).read_bytes().decode("ascii").strip(),
+    }
+    manifest_bytes = canonical_dumps(manifest)
+    digest = hashlib.sha256(manifest_bytes).digest()
+    sig = keypair.sign(digest)
+    sig_line = "ed25519:" + base64.b64encode(sig).decode("ascii")
+
+    with tarfile.open(output_path, "w:gz") as tar:
+        _add_file(tar, "bundle/manifest.json", manifest_bytes)
+        _add_file(tar, "bundle/manifest.sig", sig_line.encode("ascii"))
+        _add_file(tar, "bundle/ledger.jsonl", ledger_path.read_bytes())
+        _add_file(tar, "bundle/ledger.pub", pubkey_path.read_bytes())
+        if policies_dir:
+            pd = Path(policies_dir)
+            for p in pd.rglob("*"):
+                if p.is_file():
+                    rel = p.relative_to(pd)
+                    _add_file(tar, f"bundle/policies/{rel.as_posix()}", p.read_bytes())
+    return output_path
+
+
+def _add_file(tar: tarfile.TarFile, name: str, data: bytes) -> None:
+    info = tarfile.TarInfo(name=name)
+    info.size = len(data)
+    info.mtime = int(time.time())
+    tar.addfile(info, io.BytesIO(data))
+
+
+def verify_bundle(path: str | Path) -> dict:
+    """Return {ok, records, errors} after verifying manifest signature and ledger chain."""
+    from custos.verify import verify_ledger
+
+    path = Path(path)
+    with tarfile.open(path, "r:gz") as tar:
+        manifest_b = _read_member(tar, "bundle/manifest.json")
+        sig_b = _read_member(tar, "bundle/manifest.sig").decode("ascii").strip()
+        ledger_b = _read_member(tar, "bundle/ledger.jsonl")
+        pub_b = _read_member(tar, "bundle/ledger.pub").decode("ascii").strip()
+
+    manifest = json.loads(manifest_b)
+    pub = public_key_from_b64(pub_b)
+    digest = hashlib.sha256(canonical_dumps(manifest)).digest()
+    if not sig_b.startswith("ed25519:"):
+        return {"ok": False, "records": 0, "errors": ["manifest sig format invalid"]}
+    try:
+        pub.verify(base64.b64decode(sig_b.split(":", 1)[1]), digest)
+    except InvalidSignature:
+        return {"ok": False, "records": 0, "errors": ["manifest signature invalid"]}
+
+    # Extract to temp files and reuse verifier
+    import tempfile
+    with tempfile.TemporaryDirectory() as td:
+        tdp = Path(td)
+        (tdp / "ledger.jsonl").write_bytes(ledger_b)
+        (tdp / "ledger.pub").write_bytes(pub_b.encode("ascii"))
+        r = verify_ledger(tdp / "ledger.jsonl", tdp / "ledger.pub")
+    return {"ok": r.ok, "records": r.records, "errors": r.errors, "manifest": manifest}
+
+
+def _read_member(tar: tarfile.TarFile, name: str) -> bytes:
+    m = tar.getmember(name)
+    f = tar.extractfile(m)
+    assert f is not None
+    return f.read()

custos_mcp-0.1.0/src/custos/canonical.py

@@ -0,0 +1,31 @@
+"""Canonical JSON serialization compatible with the Custos wire spec.
+
+Rules (see spec/WIRE.md §1):
+  - UTF-8, no BOM
+  - Keys sorted lexicographically at every depth
+  - No insignificant whitespace
+  - ensure_ascii=False (raw UTF-8)
+  - allow_nan=False (strict JSON)
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def dumps(value: Any) -> bytes:
+    """Serialize to Canonical JSON bytes."""
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def loads(data: bytes | str) -> Any:
+    """Parse JSON (canonical or not) into Python."""
+    if isinstance(data, bytes):
+        data = data.decode("utf-8")
+    return json.loads(data)

custos_mcp-0.1.0/src/custos/cli.py

@@ -0,0 +1,126 @@
+"""Custos CLI: `custos <command>`."""
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from custos import __version__
+from custos.bundle import create_bundle, verify_bundle
+from custos.keys import generate_keypair, load_keypair
+from custos.ledger import Ledger
+from custos.policy import load_policy
+from custos.record import Actor, Server
+from custos.verify import verify_ledger
+
+
+@click.group()
+@click.version_option(__version__, prog_name="custos")
+def main():
+    """Custos: runtime governance for MCP tool calls."""
+
+
+@main.command()
+@click.option("--dir", "dir_", default="./.custos", show_default=True, help="Directory to write ledger.key + ledger.pub")
+def keygen(dir_: str):
+    """Generate a new Ed25519 signing keypair."""
+    kp = generate_keypair()
+    kp.save(dir_)
+    click.echo(f"wrote {dir_}/ledger.key + ledger.pub")
+    click.echo(f"pubkey (base64): {kp.public_b64()}")
+
+
+@main.command()
+@click.option("--ledger", "ledger_path", default="./.custos/ledger.jsonl", show_default=True)
+@click.option("--pub", "pub_path", default=None, help="Public key (defaults to ledger.pub sidecar)")
+def verify(ledger_path: str, pub_path: str | None):
+    """Verify a signed ledger."""
+    r = verify_ledger(ledger_path, pub_path)
+    if r.ok:
+        click.secho(f"OK  {r.records} records verified", fg="green")
+        sys.exit(0)
+    else:
+        for e in r.errors:
+            click.secho(f"ERR {e}", fg="red")
+        sys.exit(1)
+
+
+@main.command()
+@click.option("--policy", "policy_path", required=True, help="Policy YAML/JSON")
+@click.option("--ledger", "ledger_path", default="./.custos/ledger.jsonl", show_default=True)
+@click.option("--keys", "keys_dir", default="./.custos", show_default=True)
+@click.option("--actor-id", default="agent")
+@click.option("--server-id", default="upstream")
+@click.argument("upstream", nargs=-1, required=True)
+def proxy(policy_path: str, ledger_path: str, keys_dir: str, actor_id: str, server_id: str, upstream: tuple):
+    """Run stdio MCP proxy: custos proxy --policy p.yaml -- python -m server."""
+    from custos.proxy import ProxyConfig, run_stdio_proxy
+
+    policy = load_policy(policy_path)
+    kp = load_keypair(keys_dir)
+    ledger = Ledger(ledger_path, kp)
+    cfg = ProxyConfig(
+        upstream_cmd=list(upstream),
+        policy=policy,
+        ledger=ledger,
+        actor=Actor(id=actor_id),
+        server=Server(id=server_id, pubkey=kp.public_b64()),
+    )
+    code = asyncio.run(run_stdio_proxy(cfg))
+    sys.exit(code)
+
+
+@main.command()
+@click.option("--ledger", "ledger_path", default="./.custos/ledger.jsonl", show_default=True)
+@click.option("--host", default="127.0.0.1", show_default=True)
+@click.option("--port", default=8787, show_default=True, type=int)
+def serve(ledger_path: str, host: str, port: int):
+    """Launch the FastAPI dashboard (requires `pip install custos-mcp[web]`)."""
+    from custos.dashboard import create_app
+    import uvicorn
+
+    uvicorn.run(create_app(ledger_path), host=host, port=port, log_level="warning")
+
+
+@main.command()
+@click.option("--ledger", "ledger_path", default="./.custos/ledger.jsonl", show_default=True)
+@click.option("--keys", "keys_dir", default="./.custos", show_default=True)
+@click.option("--policies", default=None, help="Optional policies dir to snapshot")
+@click.argument("output")
+def bundle(ledger_path: str, keys_dir: str, policies: str | None, output: str):
+    """Export a signed evidence bundle."""
+    kp = load_keypair(keys_dir)
+    ledger = Path(ledger_path)
+    pub = ledger.parent / (ledger.stem + ".pub")
+    out = create_bundle(ledger, pub, output, kp, policies_dir=policies)
+    click.echo(f"wrote {out}")
+
+
+@main.command("verify-bundle")
+@click.argument("bundle_path")
+def verify_bundle_cmd(bundle_path: str):
+    """Verify a portable evidence bundle."""
+    r = verify_bundle(bundle_path)
+    if r["ok"]:
+        click.secho(f"OK  {r['records']} records verified", fg="green")
+        click.echo(json.dumps(r.get("manifest"), indent=2))
+        sys.exit(0)
+    click.secho(f"FAIL {r['errors']}", fg="red")
+    sys.exit(1)
+
+
+@main.command("show-policy")
+@click.argument("policy_path")
+def show_policy(policy_path: str):
+    """Load and print a normalized policy."""
+    p = load_policy(policy_path)
+    click.echo(f"id={p.id} version={p.version} default={p.default.value} rules={len(p.rules)}")
+    for r in p.rules:
+        click.echo(f"  {r.id}: when={r.when} decision={r.decision.value} reason={r.reason!r}")
+
+
+if __name__ == "__main__":
+    main()