Add files via upload

2026-07-14 07:57:26 +02:00 · 2026-07-10 21:35:49 +08:00
parent 0251230654
commit c33e5f2026
9 changed files with 1032 additions and 43 deletions
@@ -2,7 +2,7 @@

 [中文](../zh-CN/robot.md)

-This document explains how to chat with CyberStrikeAI from **personal WeChat**, **DingTalk**, **Lark (Feishu)**, and **WeCom (Enterprise WeChat)** using long-lived connections or HTTP callbacks—no need to open a browser on the server. Following the steps below helps avoid common mistakes.
+This guide covers **Personal WeChat, WeCom, DingTalk, Lark, Telegram, Slack, Discord, and QQ Bot**, including platform connectivity, RBAC identity binding, service-account allowlists, commands, verification, and troubleshooting.

 ---

@@ -15,10 +15,18 @@ This document explains how to chat with CyberStrikeAI from **personal WeChat**,
   - **Personal WeChat**: Open **WeChat / iLink** → **Generate QR code and bind**, then scan with WeChat (see [Section 3.4](#34-personal-wechat-wechat--ilink))
   - **DingTalk**: Enable and fill in Client ID / Client Secret
   - **Lark**: Enable and fill in App ID / App Secret
-5. Click **Apply configuration** to save (WeChat binding saves and enables automatically on success—usually no extra click needed)
-6. **Restart the CyberStrikeAI process** (DingTalk/Lark: saving alone does not establish the connection; WeChat auto-restarts the iLink poll after binding—usually no manual restart needed)
+5. Click **Apply configuration** to save and automatically restart the corresponding bot connection. WeChat binding saves and enables automatically on success.

-Settings are written to the `robots` section of `config.yaml`; you can also edit the file directly. **After changing DingTalk or Lark config, you must restart for the long-lived connection to take effect.** Personal WeChat binding automatically writes `robots.wechat` and restarts the iLink long poll.
+Settings are written to the `robots` section of `config.yaml`; you can also edit the file directly. Web-based **Apply configuration** restarts the corresponding connection automatically. Restart the CyberStrikeAI process only when editing YAML directly. Personal WeChat binding automatically writes `robots.wechat` and restarts the iLink long poll.
+
+### Shortest path to first use
+
+After the platform connection works, configure the business identity before sending normal prompts:
+
+- **Multiple users**: choose User binding → each user generates a code from the top-right Web user menu → sends the bind command to the bot → runs `whoami` to verify.
+- **Only you**: run `whoami` first and copy the sender ID → choose Service account → set User ID to `admin` or another RBAC user → paste the exact sender allowlist → apply configuration → run `whoami` again.
+
+Start normal AI chat only after the response shows an authorized status and the expected effective identity.

 ---

@@ -82,7 +90,7 @@ If you only have a **custom bot** Webhook URL (`oapi.dingtalk.com/robot/send?acc
   - In CyberStrikeAI: System settings → Robot settings → DingTalk.  
   - Enable “Enable DingTalk robot”.  
   - Paste the Client ID and Client Secret from step 3.  
-   - Click **Apply configuration**, then **restart CyberStrikeAI**.
+   - Click **Apply configuration**; CyberStrikeAI restarts the DingTalk connection automatically.

 ---

@@ -105,7 +113,7 @@ If you only have a **custom bot** Webhook URL (`oapi.dingtalk.com/robot/send?acc
 | App Secret | From Lark open platform app credentials |
 | Verify Token | Optional; for event subscription |

-**Lark setup in short**: Log in to [Lark Open Platform](https://open.feishu.cn) → Create an enterprise app → In “Credentials and basic info” get **App ID** and **App Secret** → In “Application capabilities” enable **Robot** and the right permissions → Add **event subscription** and **permissions** below → Publish the app → Enter App ID and App Secret in CyberStrikeAI robot settings → Save and **restart** the app.
+**Lark setup in short**: Log in to [Lark Open Platform](https://open.feishu.cn) → Create an enterprise app → In “Credentials and basic info” get **App ID** and **App Secret** → In “Application capabilities” enable **Robot** and the right permissions → Add **event subscription** and **permissions** below → Publish the app → Enter App ID and App Secret in CyberStrikeAI robot settings → **Apply configuration**.

 **Event subscription**  
 The long-lived connection only receives message events if you subscribe to them. In the app’s **Events and callbacks** (事件与回调) → **Event subscription** (事件订阅), add the event **Receive message** (**im.message.receive_v1**). Without it, the connection succeeds but no message events are delivered (no logs when users send messages).
@@ -272,12 +280,79 @@ In **Permission management** (权限管理), enable the following (names and ide

 ---

-## 4. Bot commands
+## 4. RBAC authorization and bot commands
+
+Platform credentials and callback signatures authenticate the messaging platform. CyberStrikeAI RBAC determines what the sender can actually do. Each bot instance uses one authorization mode.
+
+### 4.1 Choose an authorization mode
+
+| Scenario | Recommended mode | Identity and data behavior |
+|----------|------------------|----------------------------|
+| Shared WeCom, Lark, DingTalk, or Slack bot | `user_binding` | Each sender binds their own Web user; permissions and resources remain isolated |
+| Personal WeChat, single-user bot, fixed automation entry | `service_account` | Allowlisted senders share the configured RBAC user's permissions and owned resources |
+
+Both modes resolve user status, roles, per-permission scope, and resource assignments before every message. Basic AI chat requires:
+
+```text
+agent:execute
+chat:read
+chat:write
+```
+
+Grant project, role, local execution, WebShell, C2, or MCP permissions only when those features are required. Conversation deletion also requires `chat:delete`.
+
+### 4.2 User-binding mode (default)
+
+Administrator:
+
+1. Open System settings → Robot settings → select a platform.
+2. Set Authorization policy to `user_binding` and apply the configuration.
+
+Each user:
+
+1. Sign in to the Web UI and open the top-right user menu → **Bind robot account**.
+2. Generate a binding code; a five-minute countdown starts.
+3. Send the full command to the target bot, for example `bind 7C6E-BD4C`.
+4. Send `whoami` and confirm the effective RBAC identity is their own Web user.
+
+Codes are stored only as hashes and are single-use. When the countdown ends, the UI marks the code expired, disables copying, and refreshes the binding list; the server also rejects it. Generating a new code immediately invalidates the previous unused code. Users can send `unbind` or revoke a binding from the Web dialog.
+
+### 4.3 Service-account mode
+
+1. Connect the bot to its messaging platform.
+2. Have each intended sender run `whoami` and copy the exact sender ID. For Personal WeChat it usually resembles `xxxx@im.wechat`; never substitute `ilink_bot_id` or configured `ilink_user_id`.
+3. In Robot settings, select `service_account`.
+4. Enter the RBAC **User ID**, not its display name. `admin` is allowed; every allowlisted sender then receives full platform permissions and the UI shows a red warning.
+5. Add one exact sender ID per line. Matching is case-sensitive and `*` wildcards are rejected.
+6. Apply configuration and run `whoami` again to verify the effective user, roles, and scope.
+
+Example:
+
+```yaml
+robots:
+  wechat:
+    auth:
+      mode: service_account
+      service_user_id: admin
+      allowed_external_users:
+        - "o9cq806s32Sm2_kyOmkyaV7Rn1lU@im.wechat"
+```
+
+Service-account mode rejects `bind` and `unbind`. All allowlisted senders share conversations, projects, and other resources owned by the service account. Use `user_binding` when that sharing is undesirable.
+
+### 4.4 Inspect the effective identity
+
+Send `whoami`. The response includes platform, exact sender ID, authorization mode and status, effective RBAC user and ID, roles, scope, and permission count. A non-allowlisted sender sees only the denial status and no service-account details.
+
+### 4.5 Command list

 Send these **text commands** to the bot on any connected platform (text only):

 | Command | Description |
 |---------|-------------|
+| **绑定 \<code\>** or **bind \<code\>** | Bind the verified platform sender to the RBAC user that generated the code |
+| **解绑** or **unbind** | Remove the current platform identity binding |
+| **身份** or **whoami** | Show sender ID, authorization mode, binding status, and the effective RBAC user, roles, and scope |
 | **帮助** (help) | Show command help |
 | **列表** or **对话列表** (list) | List all conversation titles and IDs |
 | **切换 \<conversationID\>** or **继续 \<conversationID\>** | Continue in the given conversation |
@@ -292,6 +367,8 @@ Send these **text commands** to the bot on any connected platform (text only):

 Any other text is sent to the AI as a user message, same as in the web UI (e.g. penetration testing, security analysis).

+Group messages are authorized as the actual sender, never as a group ID. In service-account mode, explicitly allowlisted senders intentionally share the configured account.
+
 ---

 ## 5. How to use (do I need to @ the bot?)
@@ -310,14 +387,17 @@ Summary: **Personal WeChat and direct chat**—just send; **DingTalk/Lark in a g

 1. CyberStrikeAI web UI → System settings → Robot settings → **WeChat / iLink** → **Generate QR code and bind**.  
 2. Scan with WeChat and confirm (enter pairing code on the web page if prompted).  
-3. After binding, send “帮助” in the WeChat private chat to test.
+3. Send `whoami` in the WeChat private chat and copy the sender ID.
+4. Choose `user_binding`, or configure `service_account` with the RBAC user and exact sender allowlist.
+5. Apply configuration, run `whoami` again, then send a normal message.

 **DingTalk / Lark**

 1. **In the open platform**: Complete app creation, copy credentials, enable the bot (DingTalk: **Stream mode**), set permissions, and publish (Section 3).  
 2. **In CyberStrikeAI**: System settings → Robot settings → Enable the platform, paste Client ID/App ID and Client Secret/App Secret → **Apply configuration**.  
-3. **Restart the CyberStrikeAI process** (otherwise the long-lived connection is not established).  
-4. **On your phone**: Open DingTalk or Lark, find the bot (direct chat or @ in a group), send “帮助” or any message to test.
+3. **Choose authorization**: use `user_binding` for multiple users, or configure a service account and exact allowlist for a dedicated bot.
+4. **Apply configuration**; the Web UI restarts the corresponding connection automatically.
+5. **On your phone**: Open the bot, run `whoami` first, then send a normal message.

 If the bot does not respond, see **Section 9 (troubleshooting)** and **Section 10 (common pitfalls)**.

@@ -331,6 +411,11 @@ Example `robots` section in `config.yaml`:
 robots:
  wechat: # Personal WeChat iLink (auto-filled after QR bind; usually no manual edit)
    enabled: true
+    auth:
+      mode: service_account
+      service_user_id: admin
+      allowed_external_users:
+        - "exact sender ID copied from whoami"
    bot_token: "your_bot_token@im.bot:..."
    ilink_bot_id: "your_bot_id@im.bot"
    ilink_user_id: "your_user_id@im.wechat"
@@ -339,10 +424,14 @@ robots:
    bot_agent: "CyberStrikeAI/1.0"
  dingtalk:
    enabled: true
+    auth:
+      mode: user_binding
    client_id: "your_dingtalk_app_key"
    client_secret: "your_dingtalk_app_secret"
  lark:
    enabled: true
+    auth:
+      mode: user_binding
    app_id: "your_lark_app_id"
    app_secret: "your_lark_app_secret"
    verify_token: ""
@@ -372,7 +461,7 @@ robots:
    sandbox: true
 ```

-After changing DingTalk/Lark/WeCom/Telegram/Slack/Discord/QQ settings, **Apply configuration** restarts the corresponding connections. Personal WeChat QR binding saves and restarts automatically.
+Authorization is configured independently per platform; omitting `auth` defaults to `user_binding`. **Apply configuration** restarts the corresponding connections. Restart the process only after editing YAML directly. Personal WeChat QR binding saves and restarts automatically.

 ---

@@ -380,20 +469,24 @@ After changing DingTalk/Lark/WeCom/Telegram/Slack/Discord/QQ settings, **Apply c

 You can verify bot logic with the **test API** (no DingTalk/Lark client needed):

-1. Log in to the CyberStrikeAI web UI (so you have a session).
-2. Call the test endpoint with curl (include your session Cookie):
+1. Sign in with an account that has global `robot:write` permission and obtain a Bearer token.
+2. Call the test endpoint with curl:

 ```bash
-# Replace YOUR_COOKIE with the Cookie from your browser (F12 → Network → any request → Request headers → Cookie)
+# Adjust the URL, username, and password for your deployment
+TOKEN=$(curl -s -X POST "http://localhost:8080/api/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"YOUR_PASSWORD"}' | jq -r '.token')
+
 curl -X POST "http://localhost:8080/api/robot/test" \
  -H "Content-Type: application/json" \
-  -H "Cookie: YOUR_COOKIE" \
+  -H "Authorization: Bearer $TOKEN" \
  -d '{"platform":"dingtalk","user_id":"test_user","text":"帮助"}'
 ```

-If the JSON response contains `"reply":"【CyberStrikeAI 机器人命令】..."`, command handling works. You can also try `"text":"列表"` or `"text":"当前"`.
+If the JSON response contains `"reply":"【CyberStrikeAI 机器人命令】..."`, command handling works. `help`, `version`, and `whoami` work before binding. `list`, `current`, and normal AI messages enforce RBAC: the test `platform + user_id` must already be bound or exactly match the service-account allowlist.

-API: `POST /api/robot/test` (requires login). Body: `{"platform":"optional","user_id":"optional","text":"required"}`. Response: `{"reply":"..."}`.
+API: `POST /api/robot/test` (requires global `robot:write`). Body: `{"platform":"optional","user_id":"optional","text":"required"}`. Response: `{"reply":"..."}`. This endpoint simulates bot business logic only; it does not validate a third-party callback signature or long-lived connection.

 ---

@@ -407,7 +500,7 @@ Check in this order:
   Robot settings should show “Connected” or a bound Bot ID; `robots.wechat.bot_token` in `config.yaml` must not be empty.

 2. **Enabled?**  
-   Confirm “Enable WeChat robot” is checked; restart CyberStrikeAI if you just changed settings.
+   Confirm “Enable WeChat robot” is checked and click **Apply configuration** if you just changed settings.

 3. **Application logs**  
   - On startup: `微信 iLink 长轮询已启动`;  
@@ -430,8 +523,8 @@ Check in this order:
 1. **Client ID / Client Secret match the open platform exactly**  
   Copy from “Credentials and basic info”; avoid typing. Watch **0** vs **o** and **1** vs **l** (e.g. `ding9gf9tiozuc504aer` has **504**, not 5o4).

-2. **Did you restart after saving?**  
-   The long-lived connection is created at **startup**. “Apply configuration” only updates the config file; you **must restart the CyberStrikeAI process** for the DingTalk connection to start.
+2. **Did you apply the configuration?**  
+   Web changes require **Apply configuration**, which restarts the corresponding connection automatically. Restart the process only after editing `config.yaml` directly.

 3. **Application logs**  
   - On startup you should see: `钉钉 Stream 正在连接…`, `钉钉 Stream 已启动（无需公网），等待收消息`.  
@@ -441,6 +534,15 @@ Check in this order:
 4. **Open platform**  
   The app must be **published**. Under “Robot” you must enable **Stream** for receiving messages (HTTP callback only is not enough). Permission management must include robot receive/send message permissions.

+### 9.3 Reply says unbound, sender denied, or permission missing
+
+1. Run `whoami` and inspect the authorization mode and status.
+2. In `user_binding`, generate a code from the top-right Web user menu and send the complete bind command from the same platform identity. Regenerate expired or already-used codes.
+3. In `service_account`, copy the exact sender ID from `whoami` into that platform's allowlist. Preserve case, tenant prefixes, and suffixes such as `@im.wechat`.
+4. If an effective user is shown but permissions are missing, grant at least `agent:execute`, `chat:read`, and `chat:write` for normal AI chat.
+5. A missing or disabled service user is rejected when applying configuration.
+6. If `admin` is denied, the usual cause is an allowlist mismatch—not insufficient admin permissions.
+
 ---

 ## 10. Common pitfalls
@@ -448,7 +550,11 @@ Check in this order:
 - **Personal WeChat vs WeCom**: Personal WeChat uses `robots.wechat` + web QR bind; WeCom uses `robots.wecom` + admin callback URL—they are completely different.  
 - **WeChat QR expired**: QR codes last ~5 minutes; regenerate instead of reusing an old one.  
 - **Wrong bot type**: The “Custom” bot added in a DingTalk **group** (Webhook + sign secret) **cannot** be used for two-way chat. Only the **enterprise internal app** bot from the open platform is supported.  
- **Saved but not restarted**: After changing DingTalk/Lark robot settings you **must restart** the app (WeChat QR bind restarts the connection automatically).  
+- **Configuration not applied**: Click **Apply configuration** after Web changes; connections restart automatically. A process restart is needed only for direct YAML edits.  
+- **Bot ID used as sender ID**: Copy the sender ID from `whoami`; do not use `ilink_bot_id`, configured `ilink_user_id`, a group ID, or a display name.  
+- **Reusing an expired code**: Codes last five minutes and are single-use; generating a new code immediately invalidates the old one.  
+- **Assuming service-account users are isolated**: All allowlisted senders share that account's conversations and owned resources. Use `user_binding` for isolation.  
+- **Assuming admin removes the allowlist**: It does not. The sender must still match exactly, but every matching sender gets full permissions.  
 - **Client ID typo**: If the platform shows `504`, use `504` (not `5o4`); prefer copy/paste.  
 - **DingTalk: only HTTP callback, no Stream**: This app receives messages via **Stream**. In the open platform, message reception must be **Stream mode**.  
 - **App not published**: After changing the bot or permissions in the open platform, **publish a new version** under “Version management and release”, or changes won’t apply.
@@ -459,5 +565,5 @@ Check in this order:

 - All platforms: **text messages only**; other types (e.g. image, voice) are not supported and may be ignored.  
 - Personal WeChat: **private chat only**—group @-bot is not supported.  
- Conversations are shared with the web UI: conversations created from the bot appear in the web “Conversations” list and vice versa.  
+- Bot data is shared with the web UI: under `user_binding` it belongs to the bound user; under `service_account` it belongs to the service account and is shared by allowlisted senders.  
 - Bot execution uses the same **Eino single/multi-agent** path as the web UI (`ProcessMessageForRobot`, with progress callbacks and process details stored in the DB); only the final reply is sent back to personal WeChat/DingTalk/Lark/WeCom in one message (no SSE). Default: `robot_default_agent_mode: eino_single`.