veritrail 0.3.0__py3-none-any.whl

veritrail/__init__.py

@@ -0,0 +1,98 @@
+"""
+Veritrail — verifiable provenance and forensics for autonomous AI agents.
+
+Veritrail is the "flight recorder and chain-of-custody" for agentic actions.
+For any action an agent (or a sub-agent it spawned, N hops deep) takes, it can
+answer the three questions every CISO, auditor, and court will ask:
+
+    1. Who authorized this?  -> cryptographically reconstruct the chain to the
+       originating human.
+    2. Was the chain hijacked? -> detect goal-hijack, tool poisoning, intent
+       drift, expired authority, identity abuse, and consent fatigue.
+    3. Can you prove it later? -> a tamper-evident, hash-chained ledger.
+
+Quick start::
+
+    from veritrail import Engine, Scope, crypto
+
+    eng = Engine()
+    h_priv, h_pub = crypto.generate_keypair()
+    a_priv, a_pub = crypto.generate_keypair()
+    human = eng.register_human("Alice (CFO)", h_pub)
+    agent = eng.register_agent("FinanceBot", a_pub)
+
+    grant = eng.issue_root_delegation(
+        human_private_key=h_priv, human_id=human.id, agent_id=agent.id,
+        scope=Scope.make(tools={"payments.read"}, actions={"read"}, max_risk=20),
+        purpose="reconcile invoices", ttl_seconds=3600,
+    )
+    rec, verdict = eng.record_action(
+        actor_private_key=a_priv, actor_id=agent.id, delegation_id=grant.id,
+        tool="payments.read", action="read", risk=10, description="read invoice 42",
+    )
+    assert verdict.authorized
+"""
+
+from __future__ import annotations
+
+from . import crypto
+from .action import ActionRecord, build_signed_action
+from .audit import AuditSink, JsonlSink, NullSink, make_event
+from .delegation import Delegation, build_signed_delegation
+from .detection import DetectionEngine, Finding, Severity
+from .engine import ChainResult, Engine, VerdictResult
+from .errors import (
+    ChainBroken,
+    ExpiredGrant,
+    ScopeViolation,
+    SignatureError,
+    TamperDetected,
+    UnknownPrincipal,
+    ValidationError,
+    VeritrailError,
+)
+from .ledger import Ledger, LedgerEntry
+from .persistence import PostgresStore, SqliteStore, open_store
+from .principals import Principal, PrincipalKind, PrincipalRegistry
+from .revocation import Revocation, RevocationRegistry
+from .scope import Scope
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "crypto",
+    "Engine",
+    "Scope",
+    "Delegation",
+    "build_signed_delegation",
+    "ActionRecord",
+    "build_signed_action",
+    "DetectionEngine",
+    "Finding",
+    "Severity",
+    "ChainResult",
+    "VerdictResult",
+    "Ledger",
+    "LedgerEntry",
+    "Principal",
+    "PrincipalKind",
+    "PrincipalRegistry",
+    "Revocation",
+    "RevocationRegistry",
+    "SqliteStore",
+    "PostgresStore",
+    "open_store",
+    "AuditSink",
+    "JsonlSink",
+    "NullSink",
+    "make_event",
+    "VeritrailError",
+    "ChainBroken",
+    "ExpiredGrant",
+    "ScopeViolation",
+    "SignatureError",
+    "TamperDetected",
+    "UnknownPrincipal",
+    "ValidationError",
+    "__version__",
+]

veritrail/action.py

@@ -0,0 +1,126 @@
+"""
+veritrail.action
+================
+An :class:`ActionRecord` is the signed statement "principal X performed this
+action under delegation D". It is the leaf of the provenance tree — the thing
+a forensic investigator starts from when asking "who authorized this, and was
+the chain hijacked?".
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from . import crypto
+from .errors import ValidationError
+from .principals import new_id
+
+_TOOL_MAX = 256
+_DESC_MAX = 2048
+
+
+@dataclass(frozen=True)
+class ActionRecord:
+    id: str
+    actor_id: str           # the principal taking the action
+    delegation_id: str      # the delegation authorizing it
+    tool: str               # tool/capability invoked (e.g. "payments.transfer")
+    action: str             # action type (e.g. "write", "read", "execute")
+    risk: int               # 0-100 risk band the caller assigns this action
+    description: str        # what the agent believes it is doing / params digest
+    params_digest: str      # sha256 of the concrete parameters (no raw secrets)
+    occurred_at: float
+    signature: str = ""
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.tool, str) or not (0 < len(self.tool) <= _TOOL_MAX):
+            raise ValidationError("tool invalid")
+        if not isinstance(self.action, str) or not (0 < len(self.action) <= _TOOL_MAX):
+            raise ValidationError("action invalid")
+        if not isinstance(self.risk, int) or not (0 <= self.risk <= 100):
+            raise ValidationError("risk must be int in [0,100]")
+        if not isinstance(self.description, str) or len(self.description) > _DESC_MAX:
+            raise ValidationError("description too long")
+
+    def _signing_payload(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "actor_id": self.actor_id,
+            "delegation_id": self.delegation_id,
+            "tool": self.tool,
+            "action": self.action,
+            "risk": self.risk,
+            "description": self.description,
+            "params_digest": self.params_digest,
+            "occurred_at": self.occurred_at,
+        }
+
+    def signing_bytes(self) -> bytes:
+        return crypto.canonical_bytes(self._signing_payload())
+
+    def verify_signature(self, actor_public_key) -> bool:
+        return crypto.verify(actor_public_key, self.signing_bytes(), self.signature)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = self._signing_payload()
+        d["signature"] = self.signature
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "ActionRecord":
+        if not isinstance(d, dict):
+            raise ValidationError("action payload must be an object")
+        try:
+            return cls(
+                id=d["id"],
+                actor_id=d["actor_id"],
+                delegation_id=d["delegation_id"],
+                tool=d["tool"],
+                action=d["action"],
+                risk=int(d["risk"]),
+                description=d["description"],
+                params_digest=d["params_digest"],
+                occurred_at=float(d["occurred_at"]),
+                signature=d.get("signature", ""),
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ValidationError(f"malformed action payload: {exc}") from None
+
+
+def build_signed_action(
+    *,
+    actor_private_key,
+    actor_id: str,
+    delegation_id: str,
+    tool: str,
+    action: str,
+    risk: int,
+    description: str,
+    params: dict[str, Any] | None = None,
+    now: float | None = None,
+) -> ActionRecord:
+    """Construct and sign an action record.
+
+    ``params`` are hashed, never stored raw, so the ledger carries proof-of-
+    parameters without becoming a secrets repository (OWASP A02/A09 hygiene).
+    """
+    params_digest = crypto.sha256_hex(crypto.canonical_bytes(params or {}))
+    rec = ActionRecord(
+        id=new_id("act"),
+        actor_id=actor_id,
+        delegation_id=delegation_id,
+        tool=tool,
+        action=action,
+        risk=risk,
+        description=description,
+        params_digest=params_digest,
+        occurred_at=now if now is not None else time.time(),
+    )
+    sig = crypto.sign(actor_private_key, rec.signing_bytes())
+    return ActionRecord(
+        id=rec.id, actor_id=rec.actor_id, delegation_id=rec.delegation_id,
+        tool=rec.tool, action=rec.action, risk=rec.risk, description=rec.description,
+        params_digest=rec.params_digest, occurred_at=rec.occurred_at, signature=sig,
+    )

veritrail/api/server.py

@@ -0,0 +1,320 @@
+"""
+veritrail.api.server
+====================
+The Veritrail REST service.
+
+Security & robustness posture:
+* Clients sign delegations/actions locally with the SDK; the service only ever
+  receives public keys and signatures. No private key material is accepted,
+  stored, or logged (OWASP A02 Cryptographic Failures, A09 Logging).
+* Domain errors are raised as typed ``VeritrailError`` subclasses at the source
+  and mapped to HTTP status codes by global exception handlers. A catch-all
+  handler guarantees no unhandled exception ever leaks a stack trace to a
+  client (OWASP A04/A05). Stack traces are logged server-side only.
+* Strict security headers on every response, including error responses.
+* Optional bearer-token auth on writes; per-client rate limiting with bounded
+  memory; optional trusted-host enforcement.
+
+Run:  uvicorn veritrail.api.server:app --host 0.0.0.0 --port 8080
+Docs: http://localhost:8080/docs   (or the machine-readable /openapi.json)
+
+Environment variables:
+  VERITRAIL_DB             path to a SQLite file to enable durable persistence
+  VERITRAIL_API_KEY        if set, writes require "Authorization: Bearer <key>"
+  VERITRAIL_RATE_LIMIT     max requests per client IP per 60s window (default 240)
+  VERITRAIL_ALLOWED_HOSTS  comma-separated Host allowlist (TrustedHostMiddleware)
+  VERITRAIL_DISABLE_DOCS   set to "1" to disable the interactive docs in prod
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from collections import defaultdict, deque
+from typing import Any
+
+from fastapi import FastAPI, Header, HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import HTMLResponse, JSONResponse
+from pydantic import BaseModel, Field
+
+from veritrail import __version__
+from veritrail.action import ActionRecord
+from veritrail.delegation import Delegation
+from veritrail.engine import Engine
+from veritrail.errors import (
+    ChainBroken,
+    ExpiredGrant,
+    ScopeViolation,
+    SignatureError,
+    UnknownPrincipal,
+    ValidationError,
+    VeritrailError,
+)
+from veritrail.forensics import build_report
+from veritrail.persistence import open_store
+from veritrail.principals import Principal, PrincipalKind, new_id
+
+logger = logging.getLogger("veritrail")
+
+# --- configuration ---------------------------------------------------------
+_DISABLE_DOCS = os.environ.get("VERITRAIL_DISABLE_DOCS") == "1"
+
+app = FastAPI(
+    title="Veritrail",
+    version=__version__,
+    description="Verifiable provenance and forensics for autonomous AI agents.",
+    docs_url=None if _DISABLE_DOCS else "/docs",
+    redoc_url=None if _DISABLE_DOCS else "/redoc",
+)
+
+# Optional durable persistence.
+_db_path = os.environ.get("VERITRAIL_DB")
+_store = open_store(_db_path) if _db_path else None
+engine = Engine(store=_store)
+
+# Optional API-key auth for write endpoints.
+_API_KEY = os.environ.get("VERITRAIL_API_KEY")
+
+# Optional trusted-host enforcement.
+_allowed_hosts = os.environ.get("VERITRAIL_ALLOWED_HOSTS")
+if _allowed_hosts:
+    from fastapi.middleware.trustedhost import TrustedHostMiddleware
+    app.add_middleware(
+        TrustedHostMiddleware,
+        allowed_hosts=[h.strip() for h in _allowed_hosts.split(",") if h.strip()],
+    )
+
+# Rate limiter (bounded-memory, per client IP).
+_RATE_LIMIT = int(os.environ.get("VERITRAIL_RATE_LIMIT", "240"))
+_RATE_WINDOW = 60.0
+_MAX_TRACKED_IPS = 100_000
+_hits: dict[str, deque] = defaultdict(deque)
+_last_prune = 0.0
+
+# Security headers applied to *every* response, including errors.
+_BASE_SECURITY_HEADERS = {
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "no-referrer",
+    "Cache-Control": "no-store",
+}
+_STRICT_CSP = "default-src 'none'; frame-ancestors 'none'"
+# The interactive docs load Swagger UI assets from a CDN, so they need a
+# relaxed policy. This applies ONLY to the docs routes; the API stays strict.
+_DOCS_CSP = (
+    "default-src 'none'; "
+    "script-src 'self' https://cdn.jsdelivr.net 'unsafe-inline'; "
+    "style-src 'self' https://cdn.jsdelivr.net 'unsafe-inline'; "
+    "img-src 'self' https://fastapi.tiangolo.com data:; "
+    "connect-src 'self'"
+)
+_DOCS_PATHS = ("/docs", "/redoc", "/openapi.json")
+
+
+def _security_headers_for(path: str) -> dict[str, str]:
+    headers = dict(_BASE_SECURITY_HEADERS)
+    headers["Content-Security-Policy"] = _DOCS_CSP if path in _DOCS_PATHS else _STRICT_CSP
+    return headers
+
+
+def _check_auth(authorization: str | None) -> None:
+    if _API_KEY is None:
+        return
+    import hmac
+    expected = f"Bearer {_API_KEY}"
+    if authorization is None or not hmac.compare_digest(authorization, expected):
+        raise HTTPException(status_code=401, detail="missing or invalid API key")
+
+
+def _prune_rate_limiter(now: float) -> None:
+    """Drop stale per-IP buckets so memory cannot grow without bound."""
+    global _last_prune
+    if now - _last_prune < _RATE_WINDOW:
+        return
+    _last_prune = now
+    stale = [ip for ip, dq in _hits.items() if not dq or dq[-1] < now - _RATE_WINDOW]
+    for ip in stale:
+        _hits.pop(ip, None)
+    # Hard cap as a final backstop against a flood of unique IPs.
+    if len(_hits) > _MAX_TRACKED_IPS:
+        _hits.clear()
+
+
+@app.middleware("http")
+async def security_and_rate_limit(request: Request, call_next):
+    path = request.url.path
+    if path != "/healthz":
+        client = request.client.host if request.client else "unknown"
+        now = time.time()
+        _prune_rate_limiter(now)
+        dq = _hits[client]
+        while dq and dq[0] < now - _RATE_WINDOW:
+            dq.popleft()
+        if len(dq) >= _RATE_LIMIT:
+            return JSONResponse(
+                status_code=429,
+                content={"detail": "rate limit exceeded"},
+                headers=_security_headers_for(path),
+            )
+        dq.append(now)
+
+    response = await call_next(request)
+    for k, v in _security_headers_for(path).items():
+        response.headers[k] = v
+    return response
+
+
+# --- global exception handlers --------------------------------------------
+def _status_and_detail(exc: VeritrailError) -> tuple[int, str]:
+    if isinstance(exc, (ScopeViolation, ExpiredGrant, SignatureError, ChainBroken, ValidationError)):
+        return 422, f"{type(exc).__name__}: {exc}"
+    if isinstance(exc, UnknownPrincipal):
+        return 404, str(exc)
+    return 400, str(exc)
+
+
+@app.exception_handler(VeritrailError)
+async def veritrail_error_handler(request: Request, exc: VeritrailError) -> JSONResponse:
+    status, detail = _status_and_detail(exc)
+    return JSONResponse(
+        status_code=status, content={"detail": detail},
+        headers=_security_headers_for(request.url.path),
+    )
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_error_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    return JSONResponse(
+        status_code=422, content={"detail": "invalid request body", "errors": exc.errors()},
+        headers=_security_headers_for(request.url.path),
+    )
+
+
+@app.exception_handler(Exception)
+async def unhandled_error_handler(request: Request, exc: Exception) -> JSONResponse:
+    # Log the full context server-side; return a sanitized message to the client.
+    logger.exception("unhandled error on %s %s", request.method, request.url.path)
+    return JSONResponse(
+        status_code=500, content={"detail": "internal server error"},
+        headers=_security_headers_for(request.url.path),
+    )
+
+
+# --- request models --------------------------------------------------------
+class RegisterPrincipal(BaseModel):
+    id: str | None = Field(default=None, max_length=128)
+    kind: str = Field(pattern="^(human|agent)$")
+    name: str = Field(min_length=1, max_length=256)
+    public_key_b64: str = Field(min_length=1, max_length=128)
+
+
+class DelegationIn(BaseModel):
+    delegation: dict[str, Any]
+
+
+class ActionIn(BaseModel):
+    action: dict[str, Any]
+
+
+class RevokeIn(BaseModel):
+    target_id: str = Field(min_length=1, max_length=256)
+    target_kind: str = Field(pattern="^(delegation|principal)$")
+    reason: str = Field(min_length=1, max_length=512)
+    revoked_by: str | None = Field(default=None, max_length=256)
+
+
+# --- endpoints -------------------------------------------------------------
+@app.get("/healthz")
+def healthz() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/v1/stats")
+def stats() -> dict[str, Any]:
+    return engine.stats()
+
+
+@app.post("/v1/principals", status_code=201)
+def register_principal(body: RegisterPrincipal, authorization: str | None = Header(default=None)) -> dict[str, Any]:
+    _check_auth(authorization)
+    # Principal construction validates the key and raises ValidationError on
+    # malformed input, which the global handler maps to 422.
+    p = Principal(
+        id=body.id or new_id(body.kind),
+        kind=PrincipalKind(body.kind),
+        name=body.name,
+        public_key_b64=body.public_key_b64,
+    )
+    engine.registry.register(p)
+    if engine.store is not None:
+        engine.store.save_principal(p)
+    return p.to_dict()
+
+
+@app.get("/v1/principals")
+def list_principals() -> list[dict[str, Any]]:
+    return [p.to_dict() for p in engine.registry.all()]
+
+
+@app.post("/v1/delegations", status_code=201)
+def ingest_delegation(body: DelegationIn, authorization: str | None = Header(default=None)) -> dict[str, Any]:
+    _check_auth(authorization)
+    d = Delegation.from_dict(body.delegation)   # raises ValidationError if malformed
+    engine.ingest_delegation(d)                 # raises typed errors on failure
+    return {"id": d.id, "status": "accepted"}
+
+
+@app.post("/v1/actions", status_code=201)
+def ingest_action(body: ActionIn, authorization: str | None = Header(default=None)) -> dict[str, Any]:
+    _check_auth(authorization)
+    a = ActionRecord.from_dict(body.action)
+    _, verdict = engine.ingest_action(a)
+    return verdict.to_dict()
+
+
+@app.post("/v1/revocations", status_code=201)
+def revoke(body: RevokeIn, authorization: str | None = Header(default=None)) -> dict[str, Any]:
+    _check_auth(authorization)
+    if body.target_kind == "delegation":
+        r = engine.revoke_delegation(body.target_id, body.reason, revoked_by=body.revoked_by)
+    else:
+        r = engine.revoke_principal(body.target_id, body.reason, revoked_by=body.revoked_by)
+    return r.to_dict()
+
+
+@app.get("/v1/revocations")
+def list_revocations() -> list[dict[str, Any]]:
+    return [r.to_dict() for r in engine.revocations.all()]
+
+
+@app.get("/v1/actions/{action_id}/verdict")
+def get_verdict(action_id: str) -> dict[str, Any]:
+    if not engine.has_action(action_id):
+        raise HTTPException(status_code=404, detail="unknown action")
+    return engine.verify_action(action_id).to_dict()
+
+
+@app.get("/v1/actions/{action_id}/chain")
+def get_chain(action_id: str) -> dict[str, Any]:
+    if not engine.has_action(action_id):
+        raise HTTPException(status_code=404, detail="unknown action")
+    return engine.reconstruct_chain(action_id).to_dict()
+
+
+@app.get("/v1/actions/{action_id}/report", response_class=HTMLResponse)
+def get_report(action_id: str) -> HTMLResponse:
+    if not engine.has_action(action_id):
+        raise HTTPException(status_code=404, detail="unknown action")
+    verdict = engine.verify_action(action_id)
+    return HTMLResponse(content=build_report(engine, verdict))
+
+
+@app.get("/v1/ledger/verify")
+def verify_ledger() -> dict[str, Any]:
+    try:
+        ok = engine.verify_ledger()
+        return {"intact": ok, "entries": len(engine.ledger), "head": engine.ledger.head_hash}
+    except VeritrailError as exc:
+        return {"intact": False, "error": str(exc)}

veritrail/audit.py

@@ -0,0 +1,65 @@
+"""
+veritrail.audit
+===============
+Structured audit events for SIEM / observability pipelines.
+
+Veritrail emits a structured event for every consequential operation
+(delegation issued, action verified, revocation, integrity check). Field names
+follow the OpenTelemetry GenAI semantic conventions where one exists
+(``gen_ai.agent.id``, ``gen_ai.operation.name``, ``gen_ai.tool.name``) so the
+events drop straight into an OTel collector, Datadog, Splunk, or Elastic
+without remapping. Veritrail-specific fields use the ``veritrail.*`` namespace.
+
+By default no event sink is attached (``NullSink``). Attach :class:`JsonlSink`
+to write newline-delimited JSON, or implement the one-method protocol to bridge
+to your tracer. Sinks must never raise into the caller — an observability
+failure must not break an authorization decision.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import time
+from typing import Any, Protocol, TextIO
+
+
+class AuditSink(Protocol):
+    def emit(self, event: dict[str, Any]) -> None: ...
+
+
+class NullSink:
+    """Discards events. The safe default."""
+
+    def emit(self, event: dict[str, Any]) -> None:  # noqa: D401
+        return None
+
+
+class JsonlSink:
+    """Writes newline-delimited JSON. Thread-safe; never raises into callers."""
+
+    def __init__(self, stream: TextIO | None = None) -> None:
+        self._stream = stream or sys.stdout
+        self._lock = threading.Lock()
+
+    def emit(self, event: dict[str, Any]) -> None:
+        try:
+            line = json.dumps(event, separators=(",", ":"), default=str)
+            with self._lock:
+                self._stream.write(line + "\n")
+                self._stream.flush()
+        except Exception:
+            # Observability must not break authorization.
+            pass
+
+
+def make_event(operation: str, **fields: Any) -> dict[str, Any]:
+    """Build an OTel-GenAI-flavored event envelope."""
+    event = {
+        "timestamp": time.time(),
+        "gen_ai.operation.name": operation,
+        "veritrail.event": operation,
+    }
+    event.update(fields)
+    return event

veritrail/cli.py

@@ -0,0 +1,83 @@
+"""
+veritrail.cli
+=============
+A small operator CLI. Deliberately minimal — the heavy lifting is the SDK and
+the REST service; this just covers the things an operator does at a terminal.
+
+    veritrail keygen            generate an Ed25519 keypair (prints public, and
+                                writes the private key to a 0600 file)
+    veritrail serve             run the REST API (uvicorn)
+    veritrail demo              run the end-to-end demo
+    veritrail version           print the version
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__, crypto
+
+
+def _keygen(args: argparse.Namespace) -> int:
+    priv, pub = crypto.generate_keypair()
+    pub_b64 = crypto.public_key_to_b64(pub)
+    print(f"public_key_b64: {pub_b64}")
+    if args.out:
+        # Write private key with restrictive permissions; never print it.
+        fd = os.open(args.out, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as f:
+            f.write(crypto.private_key_to_b64(priv))
+        print(f"private key written to {args.out} (mode 0600) — keep it secret")
+    else:
+        print("(re-run with --out PATH to persist the private key to a 0600 file)")
+    return 0
+
+
+def _serve(args: argparse.Namespace) -> int:
+    try:
+        import uvicorn
+    except ImportError:
+        print("uvicorn is required to serve; pip install 'uvicorn[standard]'", file=sys.stderr)
+        return 1
+    uvicorn.run("veritrail.api.server:app", host=args.host, port=args.port)
+    return 0
+
+
+def _demo(_args: argparse.Namespace) -> int:
+    from examples.demo import main as demo_main
+    demo_main()
+    return 0
+
+
+def _version(_args: argparse.Namespace) -> int:
+    print(f"veritrail {__version__}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="veritrail", description="Veritrail operator CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_keygen = sub.add_parser("keygen", help="generate an Ed25519 keypair")
+    p_keygen.add_argument("--out", help="path to write the private key (0600)")
+    p_keygen.set_defaults(func=_keygen)
+
+    p_serve = sub.add_parser("serve", help="run the REST API")
+    p_serve.add_argument("--host", default="0.0.0.0")
+    p_serve.add_argument("--port", type=int, default=8080)
+    p_serve.set_defaults(func=_serve)
+
+    p_demo = sub.add_parser("demo", help="run the end-to-end demo")
+    p_demo.set_defaults(func=_demo)
+
+    p_version = sub.add_parser("version", help="print version")
+    p_version.set_defaults(func=_version)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())