superuser

Super

Model Context Protocol (MCP) 経由で公開される、権限ゲート付きのスーパーユーザーエージェントです。このマシン上でシェルコマンドを実行したり、システムの状態を確認したり、GitHub を操作したりする、実際のシステム管理権限を AI エージェントに提供します。その一方で、危険なコマンドの拒否リスト、リスクの高い操作に対する人間の承認ゲート、最小権限の GitHub アクセス、追記専用の監査ログ、そしてすべてのツール呼び出しと応答を対象とする Cisco AI Defense のランタイム検査によって、あらゆる操作にガードレールを設けています。

設計目標は、実際にリリースできる「スーパーユーザーエージェント」を実現することです。強力でありながら、安全で、監査可能で、エンタープライズのガードレールに対応します。

ランディングサイト： https://fitzyracing1.github.io/super-landing/ （ソース：fitzyracing1/super-landing）。 このリポジトリの以前の Pages サイトは、タグ site-v1 ／ブランチ site-archive に保存されています。

このように設計した理由

root として何でも実行できるエージェントは、製品ではなくリスクです。購入者（およびマーケットプレイスのセキュリティ審査）からは、スコープ設定、承認、監査証跡が求められます。そのため、ここでの機能はすべて、単一の制御点である 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 が判断し、ゲートウェイが適用する」モデルに従います。このエージェントは非人間 ID として登録され、RFC 8707 リソースインジケーターを使用する OAuth 2.1 client-credentials グラントで認証し、ツールに必要な 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 課金 meter events API）が発行されるため、エージェントをアクションごとに販売できます。Stripe で meter を設定してから、STRIPE_ENABLED=true、STRIPE_API_KEY、STRIPE_CUSTOMER_ID、STRIPE_METER_EVENT_NAME を設定してください。ツールごとの重み付けにより、リスクの高いアクションほど料金を高くできます。課金処理はベストエフォートです。計測の失敗はログに記録されますが、ツール呼び出しをブロックしたり失敗させたりすることはありません（結果には billed: true|false が注記されます）。

ツール

ツール	リスク	備考
system_status	LOW	ホスト、CPU、メモリ、稼働時間
disk_usage	LOW	パーティションごとのディスク使用量
list_processes	LOW	メモリ／CPU 使用量の上位プロセス
run_command	HIGH*	シェルコマンド。拒否リスト + 承認 + 監査
github_get_repo	LOW	リポジトリのメタデータ（許可リストに登録されたリポジトリのみ）
github_list_issues	LOW	許可リストに登録されたリポジトリの Issue
github_create_issue_comment	HIGH	書き込み。承認 + GITHUB_ALLOW_WRITES が必要
security_status	—	有効なガードレール設定を報告

* run_command は、ベースコマンドが command_allowlist に含まれる場合に限り LOW リスクです。それ以外の場合は HIGH となります（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 — エージェントのアクションに責任を負う人間。
• 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 アクセス。

3 つのサービスすべてについて、コンソールの値と環境変数の完全な対応表は 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 がインストールされていないか、認証情報が設定されていない場合でもエージェントは動作しますが、 すべての結果に 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。