CyberStrikeAI/docs/zh-CN/webshell.md

WebShell 管理

WebShell 管理用于保存授权目标的 WebShell 连接，并通过 Web 页面或 Agent 工具执行命令、文件操作和上下文分析。

基本流程

1. 在 WebShell 页面新增连接。
2. 填写名称、URL、密码或请求参数。
3. 测试连接。
4. 执行命令或文件操作。
5. 在对话中选择 WebShell 连接，让 AI 基于该连接辅助排查。

连接数据保存在 SQLite 中。

接口

主要 API：

• GET /api/webshell/connections
• POST /api/webshell/connections
• PUT /api/webshell/connections/:id
• DELETE /api/webshell/connections/:id
• GET /api/webshell/connections/:id/state
• PUT /api/webshell/connections/:id/state
• POST /api/webshell/exec
• POST /api/webshell/file
• GET /api/webshell/connections/:id/ai-history
• GET /api/webshell/connections/:id/ai-conversations

MCP 工具

系统会注册 WebShell MCP 工具，例如：

• webshell_exec：在连接上执行命令。
• webshell_file_list：列目录。
• webshell_file_read：读取文件。
• webshell_file_write：写文件。
• WebShell 连接管理工具。

Agent 使用这些工具时需要 connection_id。前端通常会把当前选中的连接注入上下文。

命令执行

执行命令前确认：

• 当前连接属于授权目标。
• 命令不会破坏业务。
• 输出中可能包含敏感信息。
• 长命令和交互式命令不适合 WebShell 通道。

建议先执行只读命令确认环境：

whoami
pwd
uname -a
id

Windows 目标可用：

whoami
cd
ver
ipconfig

文件操作

文件操作包括列目录、读取、写入。建议：

• 写入前先备份原文件。
• 不在生产目标写入未经确认的脚本或二进制。
• 大文件优先通过专用下载/上传通道处理。
• 注意目标编码和换行符。

AI 辅助

AI 可以帮助：

• 识别操作系统和当前权限。
• 规划只读枚举步骤。
• 分析命令输出。
• 汇总风险和修复建议。

不建议让 AI 自动执行：

• 删除文件。
• 修改业务配置。
• 持久化。
• 凭证抓取。
• 大范围扫描内网。

这些操作应由人工确认，并配合 HITL。

安全建议

• 仅保存授权目标连接。
• 给连接命名时包含项目、环境、目标。
• 演练结束后删除连接。
• 不把 WebShell 写入工具加入全局免审批白名单。
• 重要输出及时纳入项目事实或报告，随后清理敏感原始数据。

排错

连接失败：

• URL 不可达。
• 参数名或密码错误。
• 目标 WAF 拦截。
• 代理或 TLS 配置异常。

命令乱码：

• 检查目标系统编码。
• 尝试切换命令输出编码或使用 base64 包装。

AI 找不到连接：

• 确认前端已选中 WebShell 连接。
• 确认连接未被删除。
• 检查 connection_id 是否正确。

操作分层

WebShell 操作建议分成四层，不同层级使用不同审批策略：

层级	操作	风险	建议
识别	whoami、pwd、系统版本	低	可自动
枚举	目录、进程、环境变量	中	限定路径和命令
读取	配置、日志、源码	中高	人工确认敏感性
写入/执行	写文件、运行脚本、删除	高	人工审批，说明回滚

不要把“WebShell 已经拿到了”理解成“后续操作都低风险”。WebShell 通常位于业务系统内部，误操作成本很高。

连接命名规范

建议命名：

<项目>-<环境>-<目标>-<权限>-<日期>

示例：

acme-staging-web01-www-20260707

糟糕命名：

test
shell1
客户机器

AI 和人类审批都依赖上下文，连接名称含糊会直接放大误操作概率。

AI 使用约束模板

给 WebShell 相关角色加一段约束：

使用 WebShell 前先确认 connection_id、目标名称、当前目录和权限。默认只执行只读命令。任何写入、删除、上传、权限修改、持久化、凭证读取、内网探测都必须先给出目的、影响和回滚方式，并等待审批。

源码锚点

• Handler：internal/handler/webshell.go
• 连接上下文：internal/handler/webshell_context.go
• 探测逻辑：internal/handler/webshell_probe.go
• OS/编码处理测试：internal/handler/webshell_os_test.go、internal/handler/webshell_encoding_test.go
• MCP 工具注册：internal/app/app.go 中 registerWebshellTools