gax-cli 0.4.0__tar.gz

gax_cli-0.4.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: gax-cli
+Version: 0.4.0
+Summary: Governed execution layer for agent shell commands — capability-gated, audited, MCP-compatible
+Author: Sparsh Nagpal
+License: MIT
+Project-URL: Homepage, https://github.com/0sparsh2/GAX
+Project-URL: Repository, https://github.com/0sparsh2/GAX
+Project-URL: Documentation, https://github.com/0sparsh2/GAX/blob/main/docs/QUICKSTART.md
+Project-URL: Issues, https://github.com/0sparsh2/GAX/issues
+Keywords: ai-agents,mcp,model-context-protocol,agent-governance,capability-security,audit,llm-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT 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 :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: PyJWT>=2.8
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: keyring
+Requires-Dist: keyring>=25.0; extra == "keyring"
+
+# GAX — Governed Agent eXecution
+
+**Your MCP gateway can't see `bash`. GAX governs both.**
+
+GAX is a governed execution layer for agent shell commands. Agents get a
+command-line-shaped surface; OAuth, policy, audit, and tenancy live in a sidecar the
+model never sees.
+
+The guarantee: **an agent can only run commands you registered, every invoke is checked
+against a capability token before any backend runs, and every invoke produces an
+`audit_id`.**
+
+It **complements MCP** rather than competing with it — MCP servers become adapters behind
+stable command names, so one policy file and one audit trail cover both your MCP calls
+and your shell calls.
+
+Full docs, research, and evaluation: **https://github.com/0sparsh2/GAX**
+
+---
+
+## Install
+
+```bash
+pip install gax-cli
+gax init --profile k8s --profile github
+```
+
+That creates `~/.gax`, mints a 30-day **read-only** capability, starts the sidecar, and
+registers 22 real commands. Measured on a clean machine: about a second.
+
+```bash
+gax k8s.pod.logs --pod web-1     # works immediately, no exports needed
+gax doctor                       # diagnose config, capability, sidecar, backends
+```
+
+## See it stop something dangerous
+
+```bash
+export GAX_K8S_MOCK=1            # no cluster needed
+gax k8s.namespace.delete --namespace prod
+```
+
+```json
+{
+  "ok": false,
+  "error": {
+    "kind": "policy_denied",
+    "message": "side_effects 'destructive' exceeds capability ceiling 'read'"
+  },
+  "audit_id": "aud_cef808f0fadd41e7"
+}
+```
+
+Refused before `kubectl` was ever spawned, and the denial is audited with its arguments.
+
+Even if the command sits on the token's allowlist it is *still* refused, because the
+danger ceiling is a separate control — **two independent things must be wrong before
+something gets deleted.**
+
+To run it, raise the ceiling deliberately, with `--dry-run` available first:
+
+```bash
+export GAX_CAP="$(gax auth cap-mint --command k8s.namespace.delete \
+  --scope k8s:namespaces:write --max-side-effect destructive --raw)"
+
+gax k8s.namespace.delete --namespace staging --dry-run
+```
+
+## Use it from any MCP client
+
+```bash
+claude mcp add gax -- gax-mcp
+```
+
+Publishes exactly three tools — `gax_search`, `gax_doc`, `gax_invoke` — keeping the
+registry behind them, so schema cost stays constant no matter how many commands you
+register.
+
+## Add your own command
+
+One YAML file in `~/.gax/manifests/`:
+
+```yaml
+command: db.migration.run
+version: "1.0.0"
+description: Apply pending migrations
+adapter: exec
+required_scopes: [db:schema:write]
+side_effects: destructive     # sets the ceiling required to invoke it
+input_schema:
+  type: object
+  properties:
+    env:     { type: string, description: Target environment }
+    dry_run: { type: boolean, description: Validate without applying }
+  required: [env]
+```
+
+CLI flags are generated from the schema. Omit `side_effects` and GAX fails closed —
+undeclared commands are treated as `destructive`.
+
+Generate manifests instead of writing them: `gax openapi generate spec.json`.
+
+## Commands
+
+| | |
+|---|---|
+| `gax init` / `gax doctor` | Setup and diagnostics |
+| `gax profile list` / `add` | Bundled command sets (`k8s`, `github`) |
+| `gax search` / `doc` / `schema` | Lazy discovery |
+| `gax <command>` | Invoke a registered command |
+| `gax auth cap-mint` | Mint a capability (`--max-side-effect read\|write\|destructive`) |
+| `gax auth login` | OAuth 2.0 device flow |
+| `gax plan run <file>` | Multi-step / parallel workflows |
+| `gax vault put` / `get` | Tenant secrets (file or HashiCorp) |
+| `gax compliance export` | SOC2-aligned audit export |
+| `gaxd start` / `stop` / `status` | Sidecar lifecycle |
+| `gax-mcp` | Run GAX as an MCP server (stdio) |
+
+Audit log: `~/.gax/audit.jsonl`, one JSON object per invocation, including denials.
+
+## Honest scope
+
+- Raw CLI costs ~3.5× fewer tokens than GAX on like-for-like tasks. Governance is not
+  free, and we publish that number rather than a flattering one.
+- Vault, SPIFFE, and OPA integrations are hooks and stubs, not production features.
+- The evaluation is a self-assessment by the author; methodology and known defects are
+  documented in the repository.
+
+MIT licensed. Issues and contributions: https://github.com/0sparsh2/GAX

gax_cli-0.4.0/README.md

@@ -0,0 +1,129 @@
+# GAX — Governed Agent eXecution
+
+**Your MCP gateway can't see `bash`. GAX governs both.**
+
+GAX is a governed execution layer for agent shell commands. Agents get a
+command-line-shaped surface; OAuth, policy, audit, and tenancy live in a sidecar the
+model never sees.
+
+The guarantee: **an agent can only run commands you registered, every invoke is checked
+against a capability token before any backend runs, and every invoke produces an
+`audit_id`.**
+
+It **complements MCP** rather than competing with it — MCP servers become adapters behind
+stable command names, so one policy file and one audit trail cover both your MCP calls
+and your shell calls.
+
+Full docs, research, and evaluation: **https://github.com/0sparsh2/GAX**
+
+---
+
+## Install
+
+```bash
+pip install gax-cli
+gax init --profile k8s --profile github
+```
+
+That creates `~/.gax`, mints a 30-day **read-only** capability, starts the sidecar, and
+registers 22 real commands. Measured on a clean machine: about a second.
+
+```bash
+gax k8s.pod.logs --pod web-1     # works immediately, no exports needed
+gax doctor                       # diagnose config, capability, sidecar, backends
+```
+
+## See it stop something dangerous
+
+```bash
+export GAX_K8S_MOCK=1            # no cluster needed
+gax k8s.namespace.delete --namespace prod
+```
+
+```json
+{
+  "ok": false,
+  "error": {
+    "kind": "policy_denied",
+    "message": "side_effects 'destructive' exceeds capability ceiling 'read'"
+  },
+  "audit_id": "aud_cef808f0fadd41e7"
+}
+```
+
+Refused before `kubectl` was ever spawned, and the denial is audited with its arguments.
+
+Even if the command sits on the token's allowlist it is *still* refused, because the
+danger ceiling is a separate control — **two independent things must be wrong before
+something gets deleted.**
+
+To run it, raise the ceiling deliberately, with `--dry-run` available first:
+
+```bash
+export GAX_CAP="$(gax auth cap-mint --command k8s.namespace.delete \
+  --scope k8s:namespaces:write --max-side-effect destructive --raw)"
+
+gax k8s.namespace.delete --namespace staging --dry-run
+```
+
+## Use it from any MCP client
+
+```bash
+claude mcp add gax -- gax-mcp
+```
+
+Publishes exactly three tools — `gax_search`, `gax_doc`, `gax_invoke` — keeping the
+registry behind them, so schema cost stays constant no matter how many commands you
+register.
+
+## Add your own command
+
+One YAML file in `~/.gax/manifests/`:
+
+```yaml
+command: db.migration.run
+version: "1.0.0"
+description: Apply pending migrations
+adapter: exec
+required_scopes: [db:schema:write]
+side_effects: destructive     # sets the ceiling required to invoke it
+input_schema:
+  type: object
+  properties:
+    env:     { type: string, description: Target environment }
+    dry_run: { type: boolean, description: Validate without applying }
+  required: [env]
+```
+
+CLI flags are generated from the schema. Omit `side_effects` and GAX fails closed —
+undeclared commands are treated as `destructive`.
+
+Generate manifests instead of writing them: `gax openapi generate spec.json`.
+
+## Commands
+
+| | |
+|---|---|
+| `gax init` / `gax doctor` | Setup and diagnostics |
+| `gax profile list` / `add` | Bundled command sets (`k8s`, `github`) |
+| `gax search` / `doc` / `schema` | Lazy discovery |
+| `gax <command>` | Invoke a registered command |
+| `gax auth cap-mint` | Mint a capability (`--max-side-effect read\|write\|destructive`) |
+| `gax auth login` | OAuth 2.0 device flow |
+| `gax plan run <file>` | Multi-step / parallel workflows |
+| `gax vault put` / `get` | Tenant secrets (file or HashiCorp) |
+| `gax compliance export` | SOC2-aligned audit export |
+| `gaxd start` / `stop` / `status` | Sidecar lifecycle |
+| `gax-mcp` | Run GAX as an MCP server (stdio) |
+
+Audit log: `~/.gax/audit.jsonl`, one JSON object per invocation, including denials.
+
+## Honest scope
+
+- Raw CLI costs ~3.5× fewer tokens than GAX on like-for-like tasks. Governance is not
+  free, and we publish that number rather than a flattering one.
+- Vault, SPIFFE, and OPA integrations are hooks and stubs, not production features.
+- The evaluation is a self-assessment by the author; methodology and known defects are
+  documented in the repository.
+
+MIT licensed. Issues and contributions: https://github.com/0sparsh2/GAX

gax_cli-0.4.0/gax/__init__.py

@@ -0,0 +1,3 @@
+"""GAX — Governed Agent eXecution."""
+
+__version__ = "0.1.0"

gax_cli-0.4.0/gax/adapters/__init__.py

@@ -0,0 +1,3 @@
+from gax.adapters.base import run_adapter
+
+__all__ = ["run_adapter"]

gax_cli-0.4.0/gax/adapters/base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from gax.adapters import exec_adapter, http_adapter, k8s_adapter, mock_adapter, mcp_bridge
+from gax.registry import CommandManifest
+
+
+def run_adapter(
+    manifest: CommandManifest,
+    args: dict[str, Any],
+    *,
+    tenant_id: str | None = None,
+) -> dict[str, Any]:
+    if manifest.adapter == "k8s":
+        return k8s_adapter.run(manifest, args, tenant_id=tenant_id)
+    if manifest.adapter == "exec":
+        return exec_adapter.run(manifest, args, tenant_id=tenant_id)
+    if manifest.adapter == "mock":
+        return mock_adapter.run(manifest, args)
+    if manifest.adapter == "mcp":
+        return mcp_bridge.run(manifest, args, tenant_id=tenant_id)
+    if manifest.adapter == "http":
+        return http_adapter.run(manifest, args, tenant_id=tenant_id)
+    raise RuntimeError(f"unknown adapter: {manifest.adapter}")

gax_cli-0.4.0/gax/adapters/exec_adapter.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from typing import Any
+
+from gax.adapters import mock_adapter
+from gax.oauth import load_tokens
+from gax.registry import CommandManifest
+
+
+def _gh_available() -> bool:
+    return shutil.which("gh") is not None
+
+
+def _gh_env(tenant_id: str | None) -> dict[str, str]:
+    env = os.environ.copy()
+    if tenant_id:
+        tokens = load_tokens(tenant_id, "github")
+        if tokens and tokens.get("access_token"):
+            env["GH_TOKEN"] = tokens["access_token"]
+    return env
+
+
+def run(
+    manifest: CommandManifest,
+    args: dict[str, Any],
+    *,
+    tenant_id: str | None = None,
+) -> dict[str, Any]:
+    if not _gh_available():
+        return mock_adapter.run(manifest, args)
+
+    name = _HANDLERS.get(manifest.command)
+    if name is None:
+        raise RuntimeError(f"exec adapter has no handler for {manifest.command}")
+    # Resolve the handler by name at call time rather than capturing the function
+    # object in the table. Binding at import makes monkeypatching a handler
+    # silently ineffective — the table would keep calling the original.
+    handler = globals()[name]
+    if manifest.command in _MUTATING:
+        return handler(args, tenant_id=tenant_id, dry_run=bool(args.get("dry_run")))
+    return handler(args, tenant_id=tenant_id)
+
+
+def _gh_pr_list(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = args["repo"]
+    limit = int(args.get("limit", 30))
+    state = args.get("state", "open")
+    cmd = [
+        "gh",
+        "pr",
+        "list",
+        "--repo",
+        repo,
+        "--limit",
+        str(limit),
+        "--state",
+        state,
+        "--json",
+        "number,title,state,url,author,isDraft",
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=60, env=_gh_env(tenant_id))
+    if proc.returncode != 0:
+        raise RuntimeError(proc.stderr.strip() or "gh pr list failed")
+    raw = json.loads(proc.stdout or "[]")
+    items = []
+    for row in raw:
+        author = row.get("author") or {}
+        items.append(
+            {
+                "number": row["number"],
+                "title": row["title"],
+                "state": row["state"],
+                "url": row["url"],
+                "author": author.get("login", "unknown"),
+                "draft": row.get("isDraft", False),
+            }
+        )
+    return {"items": items}
+
+
+def _gh_pr_view(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = args["repo"]
+    number = int(args["number"])
+    cmd = [
+        "gh",
+        "pr",
+        "view",
+        str(number),
+        "--repo",
+        repo,
+        "--json",
+        "number,title,body,state,url,author",
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=60, env=_gh_env(tenant_id))
+    if proc.returncode != 0:
+        raise RuntimeError(proc.stderr.strip() or "gh pr view failed")
+    row = json.loads(proc.stdout or "{}")
+    author = row.get("author") or {}
+    return {
+        "number": row["number"],
+        "title": row["title"],
+        "body": (row.get("body") or "")[:2000],
+        "state": row["state"],
+        "url": row["url"],
+        "author": author.get("login", "unknown"),
+    }
+
+
+def _repo(args: dict[str, Any]) -> str:
+    """Validate owner/name before it reaches the gh subprocess."""
+    repo = str(args.get("repo") or "").strip()
+    if not re.fullmatch(r"[\w.-]+/[\w.-]+", repo):
+        raise ValueError(f"invalid repo {repo!r}; expected owner/name")
+    return repo
+
+
+def _gh(argv: list[str], tenant_id: str | None) -> str:
+    proc = subprocess.run(
+        ["gh", *argv], capture_output=True, text=True, timeout=60, env=_gh_env(tenant_id)
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(proc.stderr.strip() or f"gh {' '.join(argv)} failed")
+    return proc.stdout
+
+
+def _gh_issue_list(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = _repo(args)
+    argv = [
+        "issue", "list", "--repo", repo,
+        "--limit", str(int(args.get("limit", 30))),
+        "--state", str(args.get("state", "open")),
+        "--json", "number,title,state,url,author",
+    ]
+    rows = json.loads(_gh(argv, tenant_id) or "[]")
+    return {
+        "items": [
+            {
+                "number": r["number"],
+                "title": r["title"],
+                "state": r["state"],
+                "url": r["url"],
+                "author": (r.get("author") or {}).get("login", "unknown"),
+            }
+            for r in rows
+        ]
+    }
+
+
+def _gh_issue_view(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = _repo(args)
+    number = int(args["number"])
+    row = json.loads(
+        _gh(
+            ["issue", "view", str(number), "--repo", repo,
+             "--json", "number,title,body,state,url,author"],
+            tenant_id,
+        )
+        or "{}"
+    )
+    return {
+        "number": row.get("number"),
+        "title": row.get("title"),
+        "body": (row.get("body") or "")[:2000],
+        "state": row.get("state"),
+        "url": row.get("url"),
+        "author": (row.get("author") or {}).get("login", "unknown"),
+    }
+
+
+def _gh_run_list(args: dict[str, Any], *, tenant_id: str | None = None) -> dict[str, Any]:
+    repo = _repo(args)
+    rows = json.loads(
+        _gh(
+            ["run", "list", "--repo", repo,
+             "--limit", str(int(args.get("limit", 20))),
+             "--json", "databaseId,displayTitle,status,conclusion,workflowName"],
+            tenant_id,
+        )
+        or "[]"
+    )
+    return {
+        "items": [
+            {
+                "id": r.get("databaseId"),
+                "title": r.get("displayTitle"),
+                "workflow": r.get("workflowName"),
+                "status": r.get("status"),
+                "conclusion": r.get("conclusion"),
+            }
+            for r in rows
+        ]
+    }
+
+
+def _gh_pr_comment(
+    args: dict[str, Any], *, tenant_id: str | None = None, dry_run: bool = False
+) -> dict[str, Any]:
+    repo = _repo(args)
+    number = int(args["number"])
+    body = str(args.get("body") or "").strip()
+    if not body:
+        raise ValueError("body is required")
+    if dry_run:
+        return {"posted": False, "repo": repo, "number": number, "dry_run": True}
+    out = _gh(["pr", "comment", str(number), "--repo", repo, "--body", body], tenant_id)
+    return {
+        "posted": True,
+        "repo": repo,
+        "number": number,
+        "dry_run": False,
+        "url": out.strip(),
+    }
+
+
+def _gh_pr_merge(
+    args: dict[str, Any], *, tenant_id: str | None = None, dry_run: bool = False
+) -> dict[str, Any]:
+    repo = _repo(args)
+    number = int(args["number"])
+    method = str(args.get("method") or "squash").lower()
+    if method not in {"merge", "squash", "rebase"}:
+        raise ValueError(f"invalid merge method {method!r}; expected merge|squash|rebase")
+    if dry_run:
+        return {
+            "merged": False,
+            "repo": repo,
+            "number": number,
+            "method": method,
+            "dry_run": True,
+        }
+    out = _gh(["pr", "merge", str(number), "--repo", repo, f"--{method}"], tenant_id)
+    return {
+        "merged": True,
+        "repo": repo,
+        "number": number,
+        "method": method,
+        "dry_run": False,
+        "output": out.strip(),
+    }
+
+
+# Table-driven so a new gh manifest needs one entry, not an if-branch.
+# Values are function *names*, resolved at call time in run() — see the comment
+# there. Mutating commands receive dry_run; read-only ones cannot accept one
+# they would silently ignore.
+_HANDLERS = {
+    "gh.pr.list": "_gh_pr_list",
+    "gh.pr.view": "_gh_pr_view",
+    "gh.issue.list": "_gh_issue_list",
+    "gh.issue.view": "_gh_issue_view",
+    "gh.run.list": "_gh_run_list",
+    "gh.pr.comment": "_gh_pr_comment",
+    "gh.pr.merge": "_gh_pr_merge",
+}
+
+_MUTATING = {"gh.pr.comment", "gh.pr.merge"}

gax_cli-0.4.0/gax/adapters/http_adapter.py

@@ -0,0 +1,33 @@
+"""Generic HTTP adapter for OpenAPI-generated manifests."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from gax.registry import CommandManifest
+
+
+def run(manifest: CommandManifest, args: dict[str, Any], **_: Any) -> dict[str, Any]:
+    http = (manifest.raw or {}).get("http") or {}
+    method = str(http.get("method", "GET")).upper()
+    url_template = str(http.get("url", ""))
+    if not url_template:
+        raise RuntimeError(f"http.url missing for {manifest.command}")
+
+    url = url_template
+    path_params = http.get("path_params") or []
+    query_params = http.get("query_params") or []
+    for p in path_params:
+        url = url.replace("{" + p + "}", str(args[p]))
+    query = {p: args[p] for p in query_params if p in args}
+
+    headers = dict(http.get("headers") or {})
+    with httpx.Client(timeout=60.0) as client:
+        resp = client.request(method, url, params=query, headers=headers)
+        resp.raise_for_status()
+        try:
+            return resp.json()
+        except Exception:
+            return {"text": resp.text}