CalvinBackup/CyberStrikeAI

Fork 0

mirror of https://github.com/Ed1s0nZ/CyberStrikeAI.git synced 2026-07-13 15:37:26 +02:00

Files

T

公明 c33e5f2026 Add files via upload

2026-07-10 21:35:49 +08:00

30 KiB

Raw Blame History

CyberStrikeAI Robot / Chatbot Guide

中文

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.

1. Where to configure in CyberStrikeAI

Log in to the CyberStrikeAI web UI.
Open System Settings in the left sidebar.
Click Robot settings (between “Basic” and “Security”).
Configure per platform:
- Personal WeChat: Open WeChat / iLink → Generate QR code and bind, then scan with WeChat (see Section 3.4)
- DingTalk: Enable and fill in Client ID / Client Secret
- Lark: Enable and fill in App ID / App Secret
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. 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.

2. Supported platforms (long-lived / callback)

Platform	Description
Personal WeChat	WeChat iLink protocol; scan QR in the web UI to bind, then long-poll for messages—no public callback URL needed
DingTalk	Stream long-lived connection; the app connects to DingTalk to receive messages
Lark (Feishu)	Long-lived connection; the app connects to Lark to receive messages
WeCom (Qiye WX)	HTTP callback to receive messages; CyberStrikeAI replies via WeCom’s message sending API
Telegram	Bot API long polling (`getUpdates`); no public callback URL needed
Slack	Socket Mode (outbound WebSocket); no public callback URL needed
Discord	Gateway WebSocket; no public callback URL needed
QQ Bot	QQ Open Platform WebSocket (C2C / group @); no public callback URL needed

Section 3 below describes, per platform, what to do in the developer console and which fields to copy into CyberStrikeAI.

3. Configuration and step-by-step setup

3.1 DingTalk

Important: two types of DingTalk bots

Type	Where it’s created	Can do “user sends message → bot replies”?	Supported here?
Custom bot (Webhook)	In a DingTalk group: Group settings → Add robot → Custom (Webhook)	No; you can only post to the group	No
Enterprise internal app bot	DingTalk Open Platform: create an app and enable the bot	Yes	Yes

If you only have a custom bot Webhook URL (oapi.dingtalk.com/robot/send?access_token=...) and sign secret (SEC...), do not put them into CyberStrikeAI. You must create an enterprise internal app in the open platform and obtain Client ID and Client Secret as below.

DingTalk setup (in order)

Open DingTalk Open Platform
Go to https://open.dingtalk.com and log in with an enterprise admin account.
Create or select an app
In the left menu: Application development → Enterprise internal development → Create application (or choose an existing app). Fill in the app name and create.
Get Client ID and Client Secret
- In the left menu open Credentials and basic info (under “Basic information”).
- Copy Client ID (formerly AppKey) and Client Secret (formerly AppSecret).
- Use copy/paste; avoid typing by hand. Watch for 0 vs o and 1 vs l (e.g. ding9gf9tiozuc504aer has the digits 504, not 5o4).
Enable the bot and choose Stream mode
- Left menu: Application capabilities → Robot.
- Turn on “Robot configuration”.
- Fill in robot name, description, etc. as required.
- Critical: set message reception to “Stream mode” (流式接入). If you only enable “HTTP callback” or do not select Stream, CyberStrikeAI will not receive messages.
- Save.
Permissions and release
- Left menu: Permission management — search for “robot”, “message”, etc., and enable receive message, send message, and other bot-related permissions; confirm.
- Left menu: Version management and release — if there are unpublished changes, click Release new version / Publish; otherwise changes do not take effect.
Fill in CyberStrikeAI
- In CyberStrikeAI: System settings → Robot settings → DingTalk.
- Enable “Enable DingTalk robot”.
- Paste the Client ID and Client Secret from step 3.
- Click Apply configuration; CyberStrikeAI restarts the DingTalk connection automatically.

Field mapping (DingTalk)

Field in CyberStrikeAI	Source in DingTalk Open Platform
Enable DingTalk robot	Check to enable
Client ID (AppKey)	Credentials and basic info → Client ID (formerly AppKey)
Client Secret	Credentials and basic info → Client Secret (formerly AppSecret)

3.2 Lark (Feishu)

Field	Description
Enable Lark robot	Check to start the Lark long-lived connection
App ID	From Lark open platform app credentials
App Secret	From Lark open platform app credentials
Verify Token	Optional; for event subscription

Lark setup in short: Log in to Lark Open Platform → 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).

Lark permissions (required)
In Permission management (权限管理), enable the following (names and identifiers match the Lark console). After changes, publish a new version in Version management and release so they take effect.

Permission name (as shown in console)	Identifier	Notes
获取与发送单聊、群组消息 (Get and send direct & group messages)	`im:message`	Base permission for sending and receiving; required.
接收群聊中@机器人消息事件 (Receive @bot messages in group chat)	`im:message.group_at_msg:readonly`	Required for group chat when users @ the bot.
读取用户发给机器人的单聊消息 (Read direct messages from users to bot)	`im:message.p2p_msg:readonly`	Required for 1:1 chat; otherwise no response in private chat.
获取单聊、群组消息 (Get direct & group messages)	`im:message:readonly`	Required to read message content.

Event subscription (configured separately): In Event subscription (事件订阅), add Receive message (im.message.receive_v1). Without it, the long-lived connection will not receive message events.

1:1 chat: Open the bot’s private chat in Lark and send e.g. “帮助” or “help”; no @ needed.
Group chat: Only messages that @ the bot are received and replied to.

3.3 WeCom (Enterprise WeChat)

WeCom uses a “HTTP callback + active message send API” model:

User sends a message → WeCom sends an encrypted XML callback to your server (CyberStrikeAI’s /api/robot/wecom).

CyberStrikeAI decrypts it, calls the AI, then uses WeCom’s message/send API to actively push the reply to the user.

Configuration overview:

In the WeCom admin console, create or select a custom app (自建应用).
In that app’s settings, configure the message callback URL, Token, and EncodingAESKey.
In CyberStrikeAI’s config.yaml, fill in:
- robots.wecom.corp_id: your CorpID (企业 ID)
- robots.wecom.agent_id: the app’s AgentId
- robots.wecom.token: the Token used for message callbacks
- robots.wecom.encoding_aes_key: the EncodingAESKey used for callbacks
- robots.wecom.secret: the app’s Secret (used when calling WeCom APIs to send messages)

Important: IP allowlist (errcode 60020)
CyberStrikeAI calls https://qyapi.weixin.qq.com/cgi-bin/message/send to actively send AI replies.
If logs show errcode 60020 not allow to access from your ip:

Your server’s outbound IP is not in WeCom’s IP allowlist.

In the WeCom admin console, open the custom app’s Security / IP allowlist settings (name may vary slightly), and add the public IP of the machine running CyberStrikeAI (e.g. 110.xxx.xxx.xxx).

Save and wait for it to take effect, then test again.

If the IP is not whitelisted, WeCom will reject active message sending. You will see that /api/robot/wecom receives and processes callbacks, but users never see AI replies, and logs contain not allow to access from your ip.

3.4 Personal WeChat (WeChat / iLink)

Personal WeChat uses “web QR binding + iLink long polling”:

Generate a QR code in the CyberStrikeAI web UI → scan and confirm with WeChat on your phone;

On success, robots.wechat in config.yaml is updated automatically and iLink long polling starts (the app connects outbound to ilinkai.weixin.qq.com);

No public callback URL on your server and no WeChat Open Platform app registration required.

Personal WeChat vs WeCom

Item	Personal WeChat (iLink)	WeCom (Enterprise WeChat)
Use case	Private chat in personal WeChat	Custom app in WeCom
Setup	QR scan in web UI	Admin console callback URL + Token
Public IP needed?	No (outbound long poll only)	Yes (HTTPS callback reachable by WeCom)
Config key	`robots.wechat`	`robots.wecom`

Binding steps (in order)

Log in to CyberStrikeAI web UI
System settings → Robot settings → click the WeChat / iLink card.
(Optional) Enable “Enable WeChat robot”
You can skip this on first bind; it is checked automatically after a successful bind.
Generate QR code
Click “Generate QR code and bind”. The QR code is valid for about 5 minutes; regenerate if it expires.
Scan and confirm in WeChat
- Scan the QR code with WeChat on your phone;
- Complete confirmation on the phone;
- If WeChat shows a pairing code, enter it on the web page and click Submit (only some accounts need this).
Wait for binding to complete
When the page shows “Binding successful, WeChat robot enabled”, you’re done. bot_token, ilink_bot_id, etc. are saved to config.yaml and the iLink poll restarts automatically—usually no manual service restart.
Test in WeChat
Open the private chat with the CyberStrikeAI bot in WeChat and send “帮助” (help) or any text.

Field reference (WeChat)

Field	Description
Enable WeChat robot	Starts iLink long polling when checked; auto-enabled after bind
Generate QR code and bind	Starts the scan-to-bind flow
Advanced (defaults are fine)
API Base URL	Default `https://ilinkai.weixin.qq.com`
Bot Type	Default `3`
Bot Agent	Default `CyberStrikeAI/1.0`
iLink Bot ID	Filled automatically after bind (read-only)

How to use

Private chat only—send text directly; no @ needed.
Group @-bot is not supported (unlike DingTalk/Lark groups).
Text messages only; images, voice, etc. are ignored or not supported.

Re-bind

To bind a different WeChat account, click “Re-bind” on the robot settings page and scan again.
If you see “This WeChat account is already bound”, that account was bound before.

Common issues

Symptom	What to do
QR code expired	Click “Generate QR code and bind” again (~5 min TTL)
Phone asks for a pairing code	Enter the digits shown in WeChat on the web page
Bound but no replies	Check logs for `微信 iLink 长轮询已启动` and `微信收到消息`; ensure “Enable WeChat robot” is on
No reply after sleep / network drop	Auto-reconnect in ~5–60 s; restart CyberStrikeAI if still stuck
Cannot generate QR code	Ensure outbound HTTPS to `https://ilinkai.weixin.qq.com`

3.5 Telegram

Telegram uses Bot API long polling (getUpdates): the app connects outbound to api.telegram.org—no public callback URL needed.

Create a bot via @BotFather (/newbot) and copy the Bot Token.
CyberStrikeAI → System settings → Robot settings → Telegram.
Enable, paste the token, optionally allow group @ mentions → Apply configuration.

3.6 Slack

Slack uses Socket Mode (outbound WebSocket): requires Bot Token (xoxb-) and App-Level Token (xapp-) with connections:write.

Create an app at api.slack.com → enable Socket Mode.
Create an App-Level Token; install the app to get a Bot Token.
Subscribe to message.im and app_mention events.
Paste both tokens in CyberStrikeAI → Apply configuration.

3.7 Discord

Discord uses Gateway WebSocket—no public callback URL needed.

Discord Developer Portal → create app → Bot → copy Token.
Enable Message Content Intent under Privileged Gateway Intents.
Invite the bot with Send Messages permission.
Paste token in CyberStrikeAI; optionally allow guild @ mentions → Apply configuration.

3.8 QQ Bot

QQ Bot uses QQ Open Platform WebSocket (official botgo SDK) for C2C and group @—no public callback URL needed.

Create a bot at q.qq.com → get App ID and Client Secret.
Add sandbox testers before going live.
Subscribe to C2C and group @ events (WebSocket).
Fill in CyberStrikeAI; use Sandbox for testing → Apply configuration.

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:

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:

Open System settings → Robot settings → select a platform.
Set Authorization policy to user_binding and apply the configuration.

Each user:

Sign in to the Web UI and open the top-right user menu → Bind robot account.
Generate a binding code; a five-minute countdown starts.
Send the full command to the target bot, for example bind 7C6E-BD4C.
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

Connect the bot to its messaging platform.
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.
In Robot settings, select service_account.
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.
Add one exact sender ID per line. Matching is case-sensitive and * wildcards are rejected.
Apply configuration and run whoami again to verify the effective user, roles, and scope.

Example:

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
新对话 (new)	Start a new conversation
清空 (clear)	Clear current context (same effect as new conversation)
当前 (current)	Show current conversation ID and title
停止 (stop)	Abort the currently running task
角色 or 角色列表 (roles)	List all available roles (penetration testing, CTF, Web scan, etc.)
角色 <roleName> or 切换角色 <roleName>	Switch to the specified role
删除 <conversationID>	Delete the specified conversation
版本 (version)	Show current CyberStrikeAI version

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?)

Personal WeChat: Send directly in the private chat with the bot; no @ needed (group chat not supported).
DingTalk / Lark direct chat (recommended): Search for the bot and open a direct chat. Type “帮助” or any message; no @ needed.
DingTalk / Lark group chat: If the bot is in a group, only messages that @ the bot are received and answered; other group messages are ignored.

Summary: Personal WeChat and direct chat—just send; DingTalk/Lark in a group—@ the bot first, then send.

6. Recommended flow (so you don’t skip steps)

Personal WeChat (simplest—no open platform)

CyberStrikeAI web UI → System settings → Robot settings → WeChat / iLink → Generate QR code and bind.
Scan with WeChat and confirm (enter pairing code on the web page if prompted).
Send whoami in the WeChat private chat and copy the sender ID.
Choose user_binding, or configure service_account with the RBAC user and exact sender allowlist.
Apply configuration, run whoami again, then send a normal message.

DingTalk / Lark

In the open platform: Complete app creation, copy credentials, enable the bot (DingTalk: Stream mode), set permissions, and publish (Section 3).
In CyberStrikeAI: System settings → Robot settings → Enable the platform, paste Client ID/App ID and Client Secret/App Secret → Apply configuration.
Choose authorization: use user_binding for multiple users, or configure a service account and exact allowlist for a dedicated bot.
Apply configuration; the Web UI restarts the corresponding connection automatically.
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).

7. Config file example

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"
    base_url: "https://ilinkai.weixin.qq.com"
    bot_type: "3"
    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: ""
  wecom:
    enabled: false
    corp_id: ""
    agent_id: 0
    token: ""
    encoding_aes_key: ""
    secret: ""
  telegram:
    enabled: false
    bot_token: ""
    allow_group_messages: false
  slack:
    enabled: false
    bot_token: ""
    app_token: ""
  discord:
    enabled: false
    bot_token: ""
    allow_guild_messages: false
  qq:
    enabled: false
    app_id: ""
    client_secret: ""
    sandbox: true

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.

8. Testing without DingTalk/Lark installed

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

Sign in with an account that has global robot:write permission and obtain a Bearer token.
Call the test endpoint with curl:

# 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 "Authorization: Bearer $TOKEN" \
  -d '{"platform":"dingtalk","user_id":"test_user","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 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.

9. Troubleshooting: no response when sending messages

9.1 Personal WeChat

Check in this order:

Binding completed?
Robot settings should show “Connected” or a bound Bot ID; robots.wechat.bot_token in config.yaml must not be empty.
Enabled?
Confirm “Enable WeChat robot” is checked and click Apply configuration if you just changed settings.
Application logs
- On startup: 微信 iLink 长轮询已启动;
- After sending a message: 微信收到消息; if missing, binding may have failed or bot_token is invalid—try Re-bind.
- 微信 iLink 长轮询异常，将自动重连: wait for auto-reconnect or restart.
Network
The server must reach https://ilinkai.weixin.qq.com (outbound HTTPS). If QR generation fails, check this first.
After sleep or network drop
Same as DingTalk/Lark: auto-reconnect in ~5–60 s; restart if still no response.

9.2 DingTalk