superuser

Super

通过权限门控的超级用户 Agent，通过 Model Context Protocol (MCP) 提供服务。它让 AI Agent 能在这台机器上执行实际的系统管理操作——运行 Shell 命令、检查系统状态，以及操作 GitHub——同时为每项操作设置防护措施：危险命令拒绝列表、高风险操作的人类审批门控、遵循最小权限原则的 GitHub 访问权限、仅追加审计日志，以及由 Cisco AI Defense 对每次工具调用及响应进行运行时检查。

设计目标是打造一个真正可以发布的“超级用户 Agent”：功能强大，同时安全、可审计，并兼容企业防护要求。

落地页： https://fitzyracing1.github.io/super-landing/（源代码：[fitzyracing1/super-landing](https://github.com/fitzyracing1/super-landing)）。 此仓库中此前的 Pages 网站已保留在标签 site-v1 / 分支 site-archive 中。

为什么这样设计

一个可以以 root 身份执行任何操作的 Agent 是一种安全隐患，而不是产品。买家（以及市场平台的安全审查）期望具备范围限制、审批机制和审计跟踪。因此，这里的功能始终经过单一控制点——Guard，并按以下顺序执行：

1. Cisco AI Defense 检查工具调用（可以拦截）。
2. Cisco Duo Agentic Identity 按策略授权工具调用（可以拦截）。
3. 审批门控——达到或超过 approval_required_at（默认为 MEDIUM）的操作，必须由人类明确设置 confirm=true。
4. 执行操作。
5. Cisco AI Defense 在返回响应前进行检查（以捕获数据泄露）。
6. Stripe 对成功的调用计量（尽力而为；不会拦截）。
7. 将结果写入审计日志，格式为 human owner -> agent -> tool -> action -> outcome。

这与企业模式一致：应用负责范围限制、审批和本地审计；Cisco AI Defense 在 MCP 层提供运行时威胁检查；Cisco Duo Agentic Identity 提供与负责任的人类所有者关联的逐工具调用授权；Stripe 则将计量后的工具调用转化为收入。

Cisco Duo Agentic Identity（授权）

Duo 遵循“由 Duo 决策，由网关执行”的模式。此 Agent 注册为非人类身份，通过 OAuth 2.1 client-credentials 授权类型（附带 RFC 8707 资源指示符）进行身份验证，并通过将工具所需的 scope 与 Duo 授予的权限进行匹配，或调用显式的 Duo decision endpoint，来授权每次工具调用。设置 DUO_ENABLED=true 以及 DUO_TOKEN_URL / DUO_CLIENT_ID / DUO_CLIENT_SECRET（参见 .env.example）。未配置 Duo 时，调用会被允许，但标记为 governed: false；在 enforce 模式下，授权错误会默认拒绝。

Stripe 按用量计费（变现）

每次经过授权且成功的工具调用都会生成一个 Stripe meter event（v2 计费计量事件 API），因此可以按操作向用户出售此 Agent。先在 Stripe 中配置一个计量器，然后设置 STRIPE_ENABLED=true、STRIPE_API_KEY、STRIPE_CUSTOMER_ID 和 STRIPE_METER_EVENT_NAME。每种工具的权重可以不同，从而让高风险操作的费用更高。计费尽力而为：计量失败会记录日志，但绝不会阻止工具调用或导致其失败（结果会标注 billed: true|false）。

工具

工具	风险	说明
system_status	低	主机、CPU、内存、运行时间
disk_usage	低	各分区磁盘使用情况
list_processes	低	按内存 / CPU 使用量排列的主要进程
run_command	高*	Shell 命令；拒绝列表 + 审批 + 审计
github_get_repo	低	仓库元数据（仅限允许列表中的仓库）
github_list_issues	低	允许列表中仓库的问题
github_create_issue_comment	高	写入；需要审批 + GITHUB_ALLOW_WRITES
security_status	—	报告当前生效的防护配置

* 仅当 run_command 的基础命令位于 command_allowlist 中时，风险才为低；否则为高（需要 confirm=true）。

安装

尚未发布到 PyPI。可直接从 git 安装：

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

从克隆的仓库安装：

需要 Python 3.10+。

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

配置

将 .env.example 复制为 .env（或使用 YAML 文件，参见 superuser.example.yaml）， 然后设置相应的值。主要设置：

• SUPERUSER_HUMAN_OWNER — 对 Agent 行为负责的人。
• SUPERUSER_APPROVAL_AT — 审批关卡的风险阈值（LOW…CRITICAL）。
• AI_DEFENSE_* — Cisco AI Defense 凭据/模式（见下文）。
• DUO_* — Cisco Duo Agentic Identity 授权（见下文）。
• STRIPE_* — Stripe 按用量计费（见下文）。
• GITHUB_TOKEN、GITHUB_ALLOWED_REPOS、GITHUB_ALLOW_WRITES — 遵循最小权限原则的 GitHub 设置。

如需查看这三项服务中控制台值与环境变量的完整映射，请参见 docs/INTEGRATIONS.md。

Cisco AI Defense

安装 SDK（pip install 'superuser[security]'）并提供凭据：

• 显式检查此服务自身的工具调用/响应： 设置 AI_DEFENSE_INSPECTION_API_KEY。
• 运行时保护（agentsec.protect() 会自动为 LLM 和 MCP 客户端打补丁）： 设置 AI_DEFENSE_API_MODE_LLM_ENDPOINT 和 AI_DEFENSE_API_MODE_LLM_API_KEY， 或将 AI_DEFENSE_AGENTSEC_CONFIG 指向一个 agentsec.yaml （参见 agentsec.example.yaml）。
• AI_DEFENSE_MODE：enforce（拦截）、monitor（仅记录）或 off。

如果未安装 SDK 或未设置凭据，Agent 仍会运行，但每个结果都会标注 protected: false / UNPROTECTED——这一保护缺口绝不会被隐藏。在 enforce 模式下，检查错误会默认拒绝（调用会被拦截）；在 monitor 模式下则会默认放行（记录错误并允许调用）。

环境变量

区域	变量
核心	SUPERUSER_CONFIG、SUPERUSER_HUMAN_OWNER、SUPERUSER_APPROVAL_AT、SUPERUSER_COMMAND_TIMEOUT、SUPERUSER_AUDIT_LOG
Cisco AI Defense	AI_DEFENSE_ENABLED（默认为 true；本地开发时设为 false）、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

未设置密钥时，服务仍会运行：Duo 和 Stripe 默认关闭；如果缺少 SDK 或密钥，Cisco AI Defense 会在未受保护的状态下运行（并明确标注）。

运行

# 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

注册到 MCP 客户端

客户端配置示例（stdio）：

{
  "mcpServers": {
    "superuser": {
      "command": "superuser",
      "env": {
        "SUPERUSER_HUMAN_OWNER": "[email protected]",
        "AI_DEFENSE_MODE": "enforce",
        "AI_DEFENSE_INSPECTION_API_KEY": "..."
      }
    }
  }
}

测试

pytest

安全说明

• 危险命令拒绝列表是兜底措施，而非主要控制。主要控制措施是 Cisco AI Defense 检查和审批关卡。
• GitHub 访问默认拒绝：没有令牌或仓库允许列表为空时，无法访问。请使用遵循最小权限原则的细粒度令牌。
• 审计日志中的机密信息会被脱敏。请勿将 .env / *.yaml 配置文件纳入版本控制（这些文件已列入 .gitignore）。

许可证

Apache-2.0。