superuser 0.1.0__tar.gz

superuser-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: superuser
+Version: 0.1.0
+Summary: A permission-gated superuser (sysadmin) MCP agent with Cisco AI Defense runtime guardrails.
+Author: Super
+License: Apache-2.0
+Keywords: mcp,agent,sysadmin,superuser,cisco,ai-defense,guardrails
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<2,>=1.2.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: requests>=2.31
+Provides-Extra: security
+Requires-Dist: cisco-aidefense-sdk>=2.1.0; extra == "security"
+Provides-Extra: billing
+Requires-Dist: stripe>=11.0; extra == "billing"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: all
+Requires-Dist: cisco-aidefense-sdk>=2.1.0; extra == "all"
+Requires-Dist: stripe>=11.0; extra == "all"
+
+# Super
+
+<!-- mcp-name: io.github.fitzyracing1/superuser -->
+
+A **permission-gated superuser agent** exposed over the [Model Context Protocol
+(MCP)](https://modelcontextprotocol.io). It gives an AI agent real
+system-administration powers on this machine — running shell commands, checking
+system state, and acting on GitHub — while wrapping every action in guardrails:
+a dangerous-command denylist, a human-approval gate for risky operations,
+least-privilege GitHub access, an append-only audit log, and **Cisco AI Defense**
+runtime inspection of every tool call and response.
+
+The design goal is the version of a "superuser agent" you can actually ship:
+powerful, but safe, auditable, and compatible with enterprise guardrails.
+
+> **Landing site:** https://fitzyracing1.github.io/super-landing/ (source: [fitzyracing1/super-landing](https://github.com/fitzyracing1/super-landing)).
+> The previous Pages site in this repo is preserved at tag `site-v1` / branch `site-archive`.
+
+## Why it's built this way
+
+An agent that can do *anything* as root is a liability, not a product. Buyers
+(and marketplace security reviews) expect scoping, approvals, and an audit
+trail. So capabilities here always pass through a single choke point — the
+`Guard` — which enforces, in order:
+
+1. **Cisco AI Defense** inspects the tool call (can block).
+2. **Cisco Duo Agentic Identity** authorizes the tool call per-policy (can block).
+3. **Approval gate** — anything at or above `approval_required_at` (default
+   `MEDIUM`) needs an explicit `confirm=true` from a human.
+4. The operation runs.
+5. **Cisco AI Defense** inspects the response before it is returned (catches
+   data leakage).
+6. **Stripe** meters the successful call (best-effort; never blocks).
+7. The outcome is written to the **audit log** as
+   `human owner -> agent -> tool -> action -> outcome`.
+
+This mirrors the enterprise model: your app owns scoping + approvals + local
+audit; **Cisco AI Defense** provides runtime threat inspection at the MCP layer;
+**Cisco Duo Agentic Identity** provides per-tool-call authorization tied to an
+accountable human owner; and **Stripe** turns metered tool calls into revenue.
+
+### Cisco Duo Agentic Identity (authorization)
+
+Duo follows a "Duo decides, the gateway enforces" model. This agent registers as
+a non-human identity, authenticates via the OAuth 2.1 **client-credentials**
+grant (with an RFC 8707 resource indicator), and authorizes every tool call
+either by matching the tool's required **scope** against what Duo granted, or by
+calling an explicit Duo **decision endpoint**. Set `DUO_ENABLED=true` plus
+`DUO_TOKEN_URL` / `DUO_CLIENT_ID` / `DUO_CLIENT_SECRET` (see `.env.example`). When
+Duo is not configured, calls are allowed but flagged `governed: false`; in
+`enforce` mode authorization errors fail closed.
+
+### Stripe usage-based billing (monetization)
+
+Each authorized, successful tool call emits a Stripe **meter event**
+(v2 billing meter events API), so the agent can be sold per-action. Configure a
+meter in Stripe, then set `STRIPE_ENABLED=true`, `STRIPE_API_KEY`,
+`STRIPE_CUSTOMER_ID`, and `STRIPE_METER_EVENT_NAME`. Per-tool weights let
+higher-risk actions cost more. Billing is best-effort: metering failures are
+logged and never block or fail the tool call (results are annotated
+`billed: true|false`).
+
+## Tools
+
+| Tool | Risk | Notes |
+|------|------|-------|
+| `system_status` | LOW | Host, CPU, memory, uptime |
+| `disk_usage` | LOW | Per-partition disk usage |
+| `list_processes` | LOW | Top processes by memory/cpu |
+| `run_command` | HIGH* | Shell command; denylist + approval + audit |
+| `github_get_repo` | LOW | Repo metadata (allowlisted repos only) |
+| `github_list_issues` | LOW | Issues for an allowlisted repo |
+| `github_create_issue_comment` | HIGH | Write; needs approval + `GITHUB_ALLOW_WRITES` |
+| `security_status` | — | Reports the active guardrail configuration |
+
+\* `run_command` is LOW risk only when its base command is in
+`command_allowlist`; otherwise HIGH (requires `confirm=true`).
+
+## Install
+
+Not yet on PyPI. Install straight from git:
+
+```bash
+pip install "superuser @ git+https://github.com/fitzyracing1/Super.git"
+pip install "superuser[all] @ git+https://github.com/fitzyracing1/Super.git"   # + Cisco AI Defense + Stripe SDKs
+```
+
+From a clone:
+
+Requires Python 3.10+.
+
+```bash
+pip install -e .              # core agent (Duo authz uses requests; no extra dep)
+pip install -e '.[security]'  # + Cisco AI Defense SDK (cisco-aidefense-sdk)
+pip install -e '.[billing]'   # + Stripe SDK (usage-based billing)
+pip install -e '.[all]'       # security + billing
+pip install -e '.[dev]'       # + pytest / ruff
+```
+
+## Configure
+
+Copy `.env.example` to `.env` (or use a YAML file — see `superuser.example.yaml`)
+and set values. Key settings:
+
+- `SUPERUSER_HUMAN_OWNER` — the human accountable for the agent's actions.
+- `SUPERUSER_APPROVAL_AT` — risk threshold for the approval gate (`LOW`…`CRITICAL`).
+- `AI_DEFENSE_*` — Cisco AI Defense credentials/mode (see below).
+- `DUO_*` — Cisco Duo Agentic Identity authorization (see below).
+- `STRIPE_*` — Stripe usage-based billing (see below).
+- `GITHUB_TOKEN`, `GITHUB_ALLOWED_REPOS`, `GITHUB_ALLOW_WRITES` — least-privilege GitHub.
+
+> For a full console-value → env-var mapping for all three services, see
+> [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
+
+### Cisco AI Defense
+
+Install the SDK (`pip install 'superuser[security]'`) and provide credentials:
+
+- **Explicit inspection** of this server's own tool calls/responses:
+  set `AI_DEFENSE_INSPECTION_API_KEY`.
+- **Runtime protection** (`agentsec.protect()` auto-patches LLM + MCP clients):
+  set `AI_DEFENSE_API_MODE_LLM_ENDPOINT` + `AI_DEFENSE_API_MODE_LLM_API_KEY`,
+  or point `AI_DEFENSE_AGENTSEC_CONFIG` at an `agentsec.yaml`
+  (see `agentsec.example.yaml`).
+- `AI_DEFENSE_MODE`: `enforce` (block), `monitor` (log only), or `off`.
+
+If the SDK is not installed or no credentials are set, the agent still runs but
+every result is annotated `protected: false` / `UNPROTECTED` — the gap is never
+silent. In `enforce` mode, inspection errors **fail closed** (the call is
+blocked); in `monitor` mode they fail open (logged, allowed).
+
+## Environment variables
+
+| Area | Variables |
+|------|-----------|
+| Core | `SUPERUSER_CONFIG`, `SUPERUSER_HUMAN_OWNER`, `SUPERUSER_APPROVAL_AT`, `SUPERUSER_COMMAND_TIMEOUT`, `SUPERUSER_AUDIT_LOG` |
+| Cisco AI Defense | `AI_DEFENSE_ENABLED` (default `true`; set `false` for local dev), `AI_DEFENSE_MODE`, `AI_DEFENSE_INSPECTION_API_KEY`, `AI_DEFENSE_API_MODE_LLM_ENDPOINT`, `AI_DEFENSE_API_MODE_LLM_API_KEY`, `AI_DEFENSE_AGENTSEC_CONFIG` |
+| Cisco Duo | `DUO_ENABLED`, `DUO_MODE`, `DUO_AGENT_ID`, `DUO_TOKEN_URL`, `DUO_CLIENT_ID`, `DUO_CLIENT_SECRET`, `DUO_AUTHORIZATION_URL`, `DUO_RESOURCE`, `DUO_SCOPES` |
+| Stripe | `STRIPE_ENABLED`, `STRIPE_API_KEY`, `STRIPE_CUSTOMER_ID`, `STRIPE_METER_EVENT_NAME`, `STRIPE_DEFAULT_VALUE` |
+| GitHub | `GITHUB_TOKEN`, `GITHUB_ALLOWED_REPOS`, `GITHUB_ALLOW_WRITES`, `GITHUB_API_URL` |
+
+With no keys set the server still runs: Duo and Stripe are off by default, and Cisco AI Defense runs unprotected (clearly flagged) if the SDK/keys are missing.
+
+## Run
+
+```bash
+# Validate configuration and print guardrail/Cisco status, then exit:
+superuser --check
+
+# Start the MCP server (stdio transport, for MCP clients like Cursor/Claude):
+superuser
+# or: python -m superuser
+```
+
+### Register with an MCP client
+
+Example client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "superuser": {
+      "command": "superuser",
+      "env": {
+        "SUPERUSER_HUMAN_OWNER": "you@example.com",
+        "AI_DEFENSE_MODE": "enforce",
+        "AI_DEFENSE_INSPECTION_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+## Test
+
+```bash
+pytest
+```
+
+## Security notes
+
+- The dangerous-command denylist is a backstop, not the primary control. The
+  primary controls are Cisco AI Defense inspection and the approval gate.
+- GitHub access **fails closed**: no token or an empty repo allowlist means no
+  access. Use a fine-grained, least-privilege token.
+- Secrets are redacted in the audit log. Keep `.env` / `*.yaml` config files out
+  of version control (already in `.gitignore`).
+
+## License
+
+Apache-2.0.

superuser-0.1.0/README.md

@@ -0,0 +1,191 @@
+# Super
+
+<!-- mcp-name: io.github.fitzyracing1/superuser -->
+
+A **permission-gated superuser agent** exposed over the [Model Context Protocol
+(MCP)](https://modelcontextprotocol.io). It gives an AI agent real
+system-administration powers on this machine — running shell commands, checking
+system state, and acting on GitHub — while wrapping every action in guardrails:
+a dangerous-command denylist, a human-approval gate for risky operations,
+least-privilege GitHub access, an append-only audit log, and **Cisco AI Defense**
+runtime inspection of every tool call and response.
+
+The design goal is the version of a "superuser agent" you can actually ship:
+powerful, but safe, auditable, and compatible with enterprise guardrails.
+
+> **Landing site:** https://fitzyracing1.github.io/super-landing/ (source: [fitzyracing1/super-landing](https://github.com/fitzyracing1/super-landing)).
+> The previous Pages site in this repo is preserved at tag `site-v1` / branch `site-archive`.
+
+## Why it's built this way
+
+An agent that can do *anything* as root is a liability, not a product. Buyers
+(and marketplace security reviews) expect scoping, approvals, and an audit
+trail. So capabilities here always pass through a single choke point — the
+`Guard` — which enforces, in order:
+
+1. **Cisco AI Defense** inspects the tool call (can block).
+2. **Cisco Duo Agentic Identity** authorizes the tool call per-policy (can block).
+3. **Approval gate** — anything at or above `approval_required_at` (default
+   `MEDIUM`) needs an explicit `confirm=true` from a human.
+4. The operation runs.
+5. **Cisco AI Defense** inspects the response before it is returned (catches
+   data leakage).
+6. **Stripe** meters the successful call (best-effort; never blocks).
+7. The outcome is written to the **audit log** as
+   `human owner -> agent -> tool -> action -> outcome`.
+
+This mirrors the enterprise model: your app owns scoping + approvals + local
+audit; **Cisco AI Defense** provides runtime threat inspection at the MCP layer;
+**Cisco Duo Agentic Identity** provides per-tool-call authorization tied to an
+accountable human owner; and **Stripe** turns metered tool calls into revenue.
+
+### Cisco Duo Agentic Identity (authorization)
+
+Duo follows a "Duo decides, the gateway enforces" model. This agent registers as
+a non-human identity, authenticates via the OAuth 2.1 **client-credentials**
+grant (with an RFC 8707 resource indicator), and authorizes every tool call
+either by matching the tool's required **scope** against what Duo granted, or by
+calling an explicit Duo **decision endpoint**. Set `DUO_ENABLED=true` plus
+`DUO_TOKEN_URL` / `DUO_CLIENT_ID` / `DUO_CLIENT_SECRET` (see `.env.example`). When
+Duo is not configured, calls are allowed but flagged `governed: false`; in
+`enforce` mode authorization errors fail closed.
+
+### Stripe usage-based billing (monetization)
+
+Each authorized, successful tool call emits a Stripe **meter event**
+(v2 billing meter events API), so the agent can be sold per-action. Configure a
+meter in Stripe, then set `STRIPE_ENABLED=true`, `STRIPE_API_KEY`,
+`STRIPE_CUSTOMER_ID`, and `STRIPE_METER_EVENT_NAME`. Per-tool weights let
+higher-risk actions cost more. Billing is best-effort: metering failures are
+logged and never block or fail the tool call (results are annotated
+`billed: true|false`).
+
+## Tools
+
+| Tool | Risk | Notes |
+|------|------|-------|
+| `system_status` | LOW | Host, CPU, memory, uptime |
+| `disk_usage` | LOW | Per-partition disk usage |
+| `list_processes` | LOW | Top processes by memory/cpu |
+| `run_command` | HIGH* | Shell command; denylist + approval + audit |
+| `github_get_repo` | LOW | Repo metadata (allowlisted repos only) |
+| `github_list_issues` | LOW | Issues for an allowlisted repo |
+| `github_create_issue_comment` | HIGH | Write; needs approval + `GITHUB_ALLOW_WRITES` |
+| `security_status` | — | Reports the active guardrail configuration |
+
+\* `run_command` is LOW risk only when its base command is in
+`command_allowlist`; otherwise HIGH (requires `confirm=true`).
+
+## Install
+
+Not yet on PyPI. Install straight from git:
+
+```bash
+pip install "superuser @ git+https://github.com/fitzyracing1/Super.git"
+pip install "superuser[all] @ git+https://github.com/fitzyracing1/Super.git"   # + Cisco AI Defense + Stripe SDKs
+```
+
+From a clone:
+
+Requires Python 3.10+.
+
+```bash
+pip install -e .              # core agent (Duo authz uses requests; no extra dep)
+pip install -e '.[security]'  # + Cisco AI Defense SDK (cisco-aidefense-sdk)
+pip install -e '.[billing]'   # + Stripe SDK (usage-based billing)
+pip install -e '.[all]'       # security + billing
+pip install -e '.[dev]'       # + pytest / ruff
+```
+
+## Configure
+
+Copy `.env.example` to `.env` (or use a YAML file — see `superuser.example.yaml`)
+and set values. Key settings:
+
+- `SUPERUSER_HUMAN_OWNER` — the human accountable for the agent's actions.
+- `SUPERUSER_APPROVAL_AT` — risk threshold for the approval gate (`LOW`…`CRITICAL`).
+- `AI_DEFENSE_*` — Cisco AI Defense credentials/mode (see below).
+- `DUO_*` — Cisco Duo Agentic Identity authorization (see below).
+- `STRIPE_*` — Stripe usage-based billing (see below).
+- `GITHUB_TOKEN`, `GITHUB_ALLOWED_REPOS`, `GITHUB_ALLOW_WRITES` — least-privilege GitHub.
+
+> For a full console-value → env-var mapping for all three services, see
+> [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
+
+### Cisco AI Defense
+
+Install the SDK (`pip install 'superuser[security]'`) and provide credentials:
+
+- **Explicit inspection** of this server's own tool calls/responses:
+  set `AI_DEFENSE_INSPECTION_API_KEY`.
+- **Runtime protection** (`agentsec.protect()` auto-patches LLM + MCP clients):
+  set `AI_DEFENSE_API_MODE_LLM_ENDPOINT` + `AI_DEFENSE_API_MODE_LLM_API_KEY`,
+  or point `AI_DEFENSE_AGENTSEC_CONFIG` at an `agentsec.yaml`
+  (see `agentsec.example.yaml`).
+- `AI_DEFENSE_MODE`: `enforce` (block), `monitor` (log only), or `off`.
+
+If the SDK is not installed or no credentials are set, the agent still runs but
+every result is annotated `protected: false` / `UNPROTECTED` — the gap is never
+silent. In `enforce` mode, inspection errors **fail closed** (the call is
+blocked); in `monitor` mode they fail open (logged, allowed).
+
+## Environment variables
+
+| Area | Variables |
+|------|-----------|
+| Core | `SUPERUSER_CONFIG`, `SUPERUSER_HUMAN_OWNER`, `SUPERUSER_APPROVAL_AT`, `SUPERUSER_COMMAND_TIMEOUT`, `SUPERUSER_AUDIT_LOG` |
+| Cisco AI Defense | `AI_DEFENSE_ENABLED` (default `true`; set `false` for local dev), `AI_DEFENSE_MODE`, `AI_DEFENSE_INSPECTION_API_KEY`, `AI_DEFENSE_API_MODE_LLM_ENDPOINT`, `AI_DEFENSE_API_MODE_LLM_API_KEY`, `AI_DEFENSE_AGENTSEC_CONFIG` |
+| Cisco Duo | `DUO_ENABLED`, `DUO_MODE`, `DUO_AGENT_ID`, `DUO_TOKEN_URL`, `DUO_CLIENT_ID`, `DUO_CLIENT_SECRET`, `DUO_AUTHORIZATION_URL`, `DUO_RESOURCE`, `DUO_SCOPES` |
+| Stripe | `STRIPE_ENABLED`, `STRIPE_API_KEY`, `STRIPE_CUSTOMER_ID`, `STRIPE_METER_EVENT_NAME`, `STRIPE_DEFAULT_VALUE` |
+| GitHub | `GITHUB_TOKEN`, `GITHUB_ALLOWED_REPOS`, `GITHUB_ALLOW_WRITES`, `GITHUB_API_URL` |
+
+With no keys set the server still runs: Duo and Stripe are off by default, and Cisco AI Defense runs unprotected (clearly flagged) if the SDK/keys are missing.
+
+## Run
+
+```bash
+# Validate configuration and print guardrail/Cisco status, then exit:
+superuser --check
+
+# Start the MCP server (stdio transport, for MCP clients like Cursor/Claude):
+superuser
+# or: python -m superuser
+```
+
+### Register with an MCP client
+
+Example client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "superuser": {
+      "command": "superuser",
+      "env": {
+        "SUPERUSER_HUMAN_OWNER": "you@example.com",
+        "AI_DEFENSE_MODE": "enforce",
+        "AI_DEFENSE_INSPECTION_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+## Test
+
+```bash
+pytest
+```
+
+## Security notes
+
+- The dangerous-command denylist is a backstop, not the primary control. The
+  primary controls are Cisco AI Defense inspection and the approval gate.
+- GitHub access **fails closed**: no token or an empty repo allowlist means no
+  access. Use a fine-grained, least-privilege token.
+- Secrets are redacted in the audit log. Keep `.env` / `*.yaml` config files out
+  of version control (already in `.gitignore`).
+
+## License
+
+Apache-2.0.

superuser-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "superuser"
+version = "0.1.0"
+description = "A permission-gated superuser (sysadmin) MCP agent with Cisco AI Defense runtime guardrails."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Super" }]
+keywords = ["mcp", "agent", "sysadmin", "superuser", "cisco", "ai-defense", "guardrails"]
+
+dependencies = [
+    "mcp>=1.2.0,<2",
+    "psutil>=5.9",
+    "PyYAML>=6.0",
+    "requests>=2.31",
+]
+
+[project.optional-dependencies]
+# Cisco AI Defense runtime guardrails. Imported lazily so the server still
+# runs (in an unprotected, clearly-warned state) when this is not installed.
+security = ["cisco-aidefense-sdk>=2.1.0"]
+# Stripe usage-based billing. Optional; metering degrades gracefully without it.
+billing = ["stripe>=11.0"]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+all = ["cisco-aidefense-sdk>=2.1.0", "stripe>=11.0"]
+
+[project.scripts]
+superuser = "superuser.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

superuser-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

superuser-0.1.0/src/superuser/__init__.py

@@ -0,0 +1,5 @@
+"""Superuser: a permission-gated sysadmin MCP agent with Cisco AI Defense guardrails."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

superuser-0.1.0/src/superuser/__main__.py

@@ -0,0 +1,62 @@
+"""Entry point: `superuser` / `python -m superuser`."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from .config import Config
+from .server import build_server
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="superuser",
+        description="Permission-gated superuser MCP agent with Cisco AI Defense guardrails.",
+    )
+    parser.add_argument("--config", help="Path to a YAML config file (or set SUPERUSER_CONFIG).")
+    parser.add_argument(
+        "--transport", default="stdio", choices=["stdio", "sse", "streamable-http"],
+        help="MCP transport (default: stdio).",
+    )
+    parser.add_argument("--log-level", default="INFO")
+    parser.add_argument(
+        "--check", action="store_true",
+        help="Validate config and print security status, then exit (no server).",
+    )
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=getattr(logging, args.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+    config = Config.load(args.config)
+    server = build_server(config)
+
+    if args.check:
+        from .authz import DuoAuthorizer
+        from .billing import StripeMeter
+        from .security import CiscoAIDefense
+
+        defense = CiscoAIDefense(config.cisco)
+        authorizer = DuoAuthorizer(config.duo)
+        meter = StripeMeter(config.stripe)
+        print("Superuser agent configuration OK.")
+        print(f"  Human owner:          {config.human_owner}")
+        print(f"  Approval required at: {config.approval_required_at.name}")
+        print(f"  Audit log:            {config.audit_log_path}")
+        print(f"  Cisco AI Defense:     {defense.status}")
+        print(f"  Cisco Duo (authz):    {authorizer.status}")
+        print(f"  Stripe billing:       {meter.status}")
+        print(f"  GitHub configured:    {bool(config.github.token)}")
+        return 0
+
+    server.run(transport=args.transport)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

superuser-0.1.0/src/superuser/audit.py

@@ -0,0 +1,70 @@
+"""Append-only audit logging.
+
+Every tool invocation produces an identity-correlated record:
+``human owner -> agent -> tool -> action -> outcome``. This is the local
+counterpart to the audit chain enforced by Cisco Duo's MCP gateway, and it is
+what makes the agent's actions reviewable after the fact.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# Argument keys whose values must never be written to the audit log verbatim.
+_SENSITIVE_KEYS = {"token", "api_key", "apikey", "password", "secret", "authorization"}
+
+
+def _redact(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            k: ("***REDACTED***" if k.lower() in _SENSITIVE_KEYS else _redact(v))
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [_redact(v) for v in value]
+    if isinstance(value, str) and len(value) > 2000:
+        return value[:2000] + f"...[truncated {len(value) - 2000} chars]"
+    return value
+
+
+class AuditLog:
+    """Thread-safe JSONL audit logger."""
+
+    def __init__(self, path: str | os.PathLike[str], human_owner: str = "unknown") -> None:
+        self.path = Path(path)
+        self.human_owner = human_owner
+        self._lock = threading.Lock()
+        if self.path.parent and not self.path.parent.exists():
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def record(
+        self,
+        tool: str,
+        arguments: dict[str, Any],
+        decision: str,
+        status: str,
+        *,
+        risk: str | None = None,
+        detail: str | None = None,
+    ) -> dict[str, Any]:
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "human_owner": self.human_owner,
+            "agent": "superuser",
+            "tool": tool,
+            "arguments": _redact(arguments),
+            "risk": risk,
+            "decision": decision,
+            "status": status,
+            "detail": detail,
+        }
+        line = json.dumps(entry, ensure_ascii=False)
+        with self._lock:
+            with self.path.open("a", encoding="utf-8") as fh:
+                fh.write(line + "\n")
+        return entry