---

name: bouncer description: Execute AWS CLI commands with Telegram approval. Safe commands auto-execute, dangerous commands require human approval via Telegram. Supports trust sessions, batch uploads, and grant sessions. metadata: {"openclaw": {"emoji": "🔐", "requires": {"bins": ["mcporter"]}}}

Bouncer - AWS Command Approval System

Use mcporter to execute AWS CLI commands through the Bouncer approval system.

API: https://n8s3f1mus6.execute-api.us-east-1.amazonaws.com/prod/ GitHub: https://github.com/qwer2003tw/bouncer MCP Source: /home/ec2-user/projects/bouncer/bouncer_mcp.py

異步設計（重要！必讀！）

所有需要審批的操作預設異步返回，避免 API Gateway 29 秒超時：

# 1. 發送請求（立即返回 request_id）
mcporter call bouncer bouncer_execute \
  command="aws s3 mb s3://test" \
  reason="建桶" \
  source="Private Bot (task)" \
  trust_scope="private-bot-main"
# 返回: {"status": "pending_approval", "request_id": "abc123", ...}

# 2. 輪詢結果（必須！不會自動通知！）
mcporter call bouncer bouncer_status request_id="abc123"
# 返回: {"status": "approved", "result": "..."} 或 {"status": "pending_approval"}

⚠️ 審批輪詢規則（強制）

收到 pending_approval 後，你必須主動輪詢 bouncer_status，Bouncer 不會主動通知你結果：

1. 等 10 秒後第一次查 bouncer_status
2. 如果還是 pending，每 10-15 秒查一次
3. 最多輪詢 5 分鐘
4. 超過 5 分鐘仍 pending → 回報「等待審批中，request_id: xxx」

⚠️ 必填參數

trust_scope（bouncer_execute 必填）

trust_scope 是穩定的呼叫者識別符，用於信任匹配。bouncer_execute 必須帶此參數。

• 使用 session key 或其他穩定 ID（不要用 source，source 是顯示用）
• 同一個 bot 不同任務應有不同 trust_scope
• 上傳 tools（bouncer_upload / bouncer_upload_batch）trust_scope 是 optional

source（所有操作必填）

source 是顯示用的來源描述，出現在 Telegram 通知中。

格式：{Bot名稱} ({專案/任務})

• ✅ source="Private Bot (Bouncer 部署)"
• ❌ source="Private Bot"（太模糊）

---

Core Tools

bouncer_execute

執行 AWS CLI 命令。安全命令自動執行，危險命令需要 Telegram 審批。

mcporter call bouncer bouncer_execute \
  command="aws ec2 describe-instances" \
  reason="檢查 EC2 狀態" \
  source="Private Bot (infra check)" \
  trust_scope="private-bot-main"

Parameters: | 參數 | 必填 | 說明 | |------|------|------| | command | ✅ | AWS CLI 命令 | | reason | ✅ | 執行原因（顯示在審批通知） | | source | ✅ | 來源標識 | | trust_scope | ✅ | 穩定呼叫者 ID（session key） | | account | ❌ | 目標 AWS 帳號 ID（預設 190825685292） | | sync | ❌ | 同步模式（不推薦） |

Returns:

• auto_approved — 安全命令，已自動執行
• pending_approval — 需要 Telegram 審批
• blocked — 被封鎖（含 block_reason 和 suggestion）
• trust_auto_approved — 信任期間自動執行

bouncer_status

查詢審批請求狀態。

mcporter call bouncer bouncer_status request_id="abc123"

bouncer_list_pending

列出待審批的請求。

mcporter call bouncer bouncer_list_pending source="Private Bot"

---

Upload Tools

bouncer_upload

上傳單一檔案到 S3。

CONTENT=$(base64 -w0 config.json)
mcporter call bouncer bouncer_upload \
  filename="config.json" \
  content="$CONTENT" \
  content_type="application/json" \
  reason="上傳設定檔" \
  source="Private Bot (config)" \
  trust_scope="private-bot-main"

Parameters: | 參數 | 必填 | 說明 | |------|------|------| | filename | ✅ | 檔案名稱 | | content | ✅ | 檔案內容（base64 encoded） | | reason | ✅ | 上傳原因 | | source | ✅ | 來源標識 | | content_type | ❌ | MIME type（預設 application/octet-stream） | | trust_scope | ❌ | 信任範圍 ID（帶了才能走信任上傳） | | account | ❌ | 目標帳號 |

信任上傳（Trust Upload）：

• 信任期間 + 帶 trust_scope → 自動上傳（不需審批）
• 每個信任時段最多 5 次上傳
• 每檔 5MB、每 session 20MB 上限
• 副檔名黑名單：.sh .exe .py .jar .zip .tar.gz .7z .bat .ps1 .rb .war .bin .bash
• Custom s3_uri 不會走信任（只允許預設路徑）

bouncer_upload_batch

批量上傳多個檔案，一次審批。

mcporter call bouncer bouncer_upload_batch \
  files='[
    {"filename":"index.html","content":"'$(base64 -w0 index.html)'"},
    {"filename":"style.css","content":"'$(base64 -w0 style.css)'"},
    {"filename":"app.js","content":"'$(base64 -w0 app.js)'"}
  ]' \
  reason="前端部署" \
  source="Private Bot (ZTP Files deploy)" \
  trust_scope="private-bot-main"

Parameters: | 參數 | 必填 | 說明 | |------|------|------| | files | ✅ | JSON array: [{filename, content, content_type?}] | | reason | ✅ | 上傳原因 | | source | ✅ | 來源標識 | | trust_scope | ❌ | 信任範圍 ID | | account | ❌ | 目標帳號 |

Limits:

• 最多 50 個檔案
• 每檔 5MB、總計 20MB
• 副檔名黑名單（同 bouncer_upload）
• 檔名自動消毒（path traversal、null bytes 等）

審批按鈕：

• [📁 批准上傳] — 只批准這批
• [🔓 批准 + 信任10分鐘] — 批准 + 開信任（含 5 次上傳 quota）
• [❌ 拒絕]

信任 batch： 如果有 active trust session + 足夠 quota → 全部自動執行

---

Trust Session

審批時選「🔓 信任10分鐘」，期間同 trust_scope 的操作自動執行。

特性

• 時長：10 分鐘
• 命令上限：20 次/session
• 上傳上限：5 次/session（5MB/檔, 20MB/session total）
• 匹配方式：trust_scope + account_id（不是 source）

排除（即使信任中仍需審批）

• 高危服務：iam, sts, organizations, kms, secretsmanager, cloudformation, cloudtrail
• 高危操作：delete-, terminate-, stop-, modify-, s3 rm, update-function-code 等
• 危險旗標：--force, --recursive, --skip-final-snapshot 等
• 上傳排除：blocked 副檔名、custom s3_uri

Tools

mcporter call bouncer bouncer_trust_status
mcporter call bouncer bouncer_trust_status source="Private Bot"
mcporter call bouncer bouncer_trust_revoke trust_id="trust-xxx-yyy"

---

Grant Session（批次授權）

預先申請一組命令的執行權限，審批後可在 TTL 內重複或一次性執行。

bouncer_request_grant

mcporter call bouncer bouncer_request_grant \
  commands='["aws ec2 describe-instances", "aws s3 ls"]' \
  reason="基礎設施檢查" \
  source="Private Bot (infra)" \
  trust_scope="private-bot-main" \
  ttl_minutes=30 \
  allow_repeat=true

Parameters: | 參數 | 必填 | 說明 | |------|------|------| | commands | ✅ | JSON array of AWS CLI commands | | reason | ✅ | 授權原因 | | source | ✅ | 來源標識 | | trust_scope | ✅ | 呼叫者 ID | | ttl_minutes | ❌ | 授權時長（1-60 分鐘，預設 30） | | allow_repeat | ❌ | 可重複執行（預設 true） | | account | ❌ | 目標帳號 |

bouncer_grant_execute

在已批准的 grant 內執行命令（精確匹配）。

mcporter call bouncer bouncer_grant_execute \
  grant_id="grant-abc123" \
  command="aws ec2 describe-instances" \
  trust_scope="private-bot-main"

bouncer_grant_status

mcporter call bouncer bouncer_grant_status grant_id="grant-abc123"

Grant vs Trust

| 維度 | Grant Session | Trust Session | |------|---------------|---------------| | 模式 | 白名單（精確命令） | 黑名單（排除高危） | | 觸發 | Agent 主動申請 | 審批者選擇信任 | | 匹配 | 命令精確匹配 | trust_scope + account | | 適用 | 可預測的命令清單 | 互動式探索 | | 上傳 | 不支援 | 支援（quota 限制） |

---

SAM Deployer

bouncer_deploy

mcporter call bouncer bouncer_deploy \
  project="bouncer" \
  reason="更新功能" \
  source="Private Bot (Bouncer deploy)"

bouncer_deploy_status / bouncer_deploy_cancel / bouncer_deploy_history / bouncer_project_list

mcporter call bouncer bouncer_deploy_status deploy_id="deploy-xxx"
mcporter call bouncer bouncer_deploy_cancel deploy_id="deploy-xxx"
mcporter call bouncer bouncer_deploy_history project="bouncer" limit=5
mcporter call bouncer bouncer_project_list

---

Account Management

bouncer_list_accounts / bouncer_add_account / bouncer_remove_account

mcporter call bouncer bouncer_list_accounts
mcporter call bouncer bouncer_add_account account_id="111111111111" name="Production" role_arn="arn:aws:iam::111111111111:role/BouncerRole" source="Bot"
mcporter call bouncer bouncer_remove_account account_id="111111111111" source="Bot"

AWS 帳號

| 帳號 | ID | 說明 | |------|-----|------| | 2nd (主帳號) | 190825685292 | 直接使用 Lambda execution role | | Dev | 992382394211 | 透過 assume role BouncerExecutionRole | | 1st | 841882238387 | 透過 assume role BouncerExecutionRole |

---

Other Tools

bouncer_get_page

當命令輸出超過 3500 字元自動分頁，用此 tool 取後續頁面。

mcporter call bouncer bouncer_get_page page_id="abc123:page:2"

bouncer_list_safelist

列出命令分類規則。

---

Command Classification

| Type | Behavior | Examples | |------|----------|----------| | BLOCKED | 永遠拒絕（含原因 + 建議） | iam create-*, sts assume-role | | DANGEROUS | 特殊審批（⚠️ 高危警告） | delete-bucket, terminate-instances | | SAFELIST | 自動執行 | describe-*, list-*, get-* | | APPROVAL | 需要 Telegram 審批 | start-*, stop-*, create-* |

---

CloudFormation Stacks

• clawdbot-bouncer - 主要 Bouncer
• bouncer-deployer - SAM Deployer 基礎建設