388 lines
9.8 KiB
Markdown
388 lines
9.8 KiB
Markdown
# 内网沙盒操作员运行手册
|
||
|
||
本手册供能够访问内网测试沙盒的操作员使用；该沙盒中可以人工打开并登录 iSphere / IMPlatformClient。
|
||
|
||
目标是为外网协调环境生成一个“已登录状态下的只读现场采集包”。
|
||
|
||
## 1. 安全边界
|
||
|
||
只允许执行以下动作：
|
||
|
||
```text
|
||
人工打开 iSphere / IMPlatformClient
|
||
人工正常登录
|
||
保持主窗口可见
|
||
运行 version
|
||
运行 self_check
|
||
运行 scan_windows
|
||
运行 dump_uia
|
||
把 JSON / 文本文档输出复制进采集包
|
||
```
|
||
|
||
禁止执行以下动作：
|
||
|
||
```text
|
||
自动登录
|
||
搜索联系人
|
||
打开会话
|
||
发送消息
|
||
发送文件
|
||
接收/下载文件
|
||
使用复制出来的凭据
|
||
提取密码/token/cookie/私钥
|
||
注入进程
|
||
hook
|
||
读取目标进程内存
|
||
绕过终端安全/安防
|
||
运行离线证据包中复制出来的可执行文件
|
||
```
|
||
|
||
## 2. 在内网沙盒中准备仓库
|
||
|
||
在仓库根目录打开 PowerShell。
|
||
|
||
示例：
|
||
|
||
```powershell
|
||
cd E:\isphere-ai-bridge
|
||
```
|
||
|
||
如果仓库路径不同，请使用实际路径。下面所有命令都假设当前目录是仓库根目录。
|
||
|
||
检查仓库状态：
|
||
|
||
```powershell
|
||
git status --short --branch
|
||
```
|
||
|
||
建议稍后把该输出记录到采集包中，文件名为：
|
||
|
||
```text
|
||
metadata/repo-status.txt
|
||
```
|
||
|
||
## 3. 验证 helper 和 Go MCP 准备情况
|
||
|
||
运行 helper 验证：
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1
|
||
```
|
||
|
||
期望的高层结果：
|
||
|
||
```text
|
||
ok=true
|
||
helper version=0.1.0
|
||
uia_available=true 或有效布尔值
|
||
```
|
||
|
||
如果内网沙盒已安装 Go，也运行：
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
|
||
```
|
||
|
||
期望的高层结果：
|
||
|
||
```text
|
||
ok=true
|
||
tool_count=4
|
||
helper_name=ISphereWinHelper
|
||
action_tools_present=false
|
||
```
|
||
|
||
如果没有 Go，不要在采集窗口内临时安装无关工具，除非操作员已获得批准。下面的 C# helper 兜底流程足以采集同样四个只读 helper 操作。
|
||
|
||
## 4. 创建采集目录
|
||
|
||
选择一个采集编号。推荐格式：
|
||
|
||
```text
|
||
YYYY-MM-DD-internal-sandbox-<short-name>
|
||
```
|
||
|
||
示例：
|
||
|
||
```powershell
|
||
$captureId = "2026-07-08-internal-sandbox-a"
|
||
$captureRoot = "runs\internal-sandbox-live-capture\$captureId"
|
||
New-Item -ItemType Directory -Force -Path `
|
||
"$captureRoot\metadata", `
|
||
"$captureRoot\helper", `
|
||
"$captureRoot\windows", `
|
||
"$captureRoot\uia", `
|
||
"$captureRoot\notes" | Out-Null
|
||
```
|
||
|
||
## 5. 记录元数据
|
||
|
||
记录操作系统版本：
|
||
|
||
```powershell
|
||
Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsBuildNumber, CsUserName |
|
||
Format-List | Out-File -FilePath "$captureRoot\metadata\os-version.txt" -Encoding UTF8
|
||
```
|
||
|
||
记录进程列表：
|
||
|
||
```powershell
|
||
Get-Process | Sort-Object ProcessName |
|
||
Select-Object ProcessName, Id, MainWindowTitle, Path |
|
||
Format-Table -AutoSize | Out-File -FilePath "$captureRoot\metadata\process-list.txt" -Encoding UTF8
|
||
```
|
||
|
||
记录仓库状态：
|
||
|
||
```powershell
|
||
git status --short --branch | Out-File -FilePath "$captureRoot\metadata\repo-status.txt" -Encoding UTF8
|
||
```
|
||
|
||
创建来源说明：
|
||
|
||
```powershell
|
||
@"
|
||
capture_id: $captureId
|
||
source_environment: 内网测试沙盒
|
||
operator: <填写操作员姓名或角色>
|
||
capture_time_local: $(Get-Date -Format "yyyy-MM-dd HH:mm:ss zzz")
|
||
iSphere manually logged in: 是/否
|
||
client opened before capture: 是/否
|
||
main window visible: 是/否
|
||
operations used: version, self_check, scan_windows, dump_uia
|
||
forbidden actions performed: no
|
||
this package is N12R live evidence, not current-environment N12 pass
|
||
"@ | Set-Content -Path "$captureRoot\metadata\source-notes.txt" -Encoding UTF8
|
||
```
|
||
|
||
打包前，请把 `是/否` 字段改成真实情况。
|
||
|
||
## 6. 人工登录
|
||
|
||
1. 使用内网沙盒的正常方式打开 iSphere / IMPlatformClient。
|
||
2. 按公司正常流程人工登录。
|
||
3. 如需 SSO/MFA，请正常完成。
|
||
4. 不要使用复制出来的凭据，也不要使用离线证据文件。
|
||
5. 保持 iSphere 主窗口可见，不要最小化。
|
||
|
||
除非正常登录流程本身需要，否则不要点击联系人或会话。不要发送或接收任何内容。
|
||
|
||
## 7. 设置 helper 路径变量
|
||
|
||
运行 `verify-win-helper.ps1` 后，helper 应位于：
|
||
|
||
```text
|
||
runs\win-helper\ISphereWinHelper.exe
|
||
```
|
||
|
||
设置变量：
|
||
|
||
```powershell
|
||
$helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe"
|
||
```
|
||
|
||
## 8. 采集 helper 版本
|
||
|
||
```powershell
|
||
@{
|
||
protocol = "isphere.helper.v1"
|
||
request_id = "n12r-version"
|
||
op = "version"
|
||
timeout_ms = 5000
|
||
args = @{}
|
||
} | ConvertTo-Json -Depth 8 -Compress |
|
||
& $helper --json |
|
||
Set-Content -Path "$captureRoot\helper\version.json" -Encoding UTF8
|
||
```
|
||
|
||
## 9. 采集 self_check
|
||
|
||
```powershell
|
||
@{
|
||
protocol = "isphere.helper.v1"
|
||
request_id = "n12r-self-check"
|
||
op = "self_check"
|
||
timeout_ms = 5000
|
||
args = @{}
|
||
} | ConvertTo-Json -Depth 8 -Compress |
|
||
& $helper --json |
|
||
Set-Content -Path "$captureRoot\helper\self-check.json" -Encoding UTF8
|
||
```
|
||
|
||
## 10. 扫描可见窗口
|
||
|
||
```powershell
|
||
@{
|
||
protocol = "isphere.helper.v1"
|
||
request_id = "n12r-scan-windows"
|
||
op = "scan_windows"
|
||
timeout_ms = 5000
|
||
args = @{ include_all_visible = $true }
|
||
} | ConvertTo-Json -Depth 8 -Compress |
|
||
& $helper --json |
|
||
Set-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8
|
||
```
|
||
|
||
打开扫描结果，根据进程名、标题、类名、可见性、边界和评分识别最可能的 iSphere / IMPlatformClient 窗口：
|
||
|
||
```powershell
|
||
Get-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8 | ConvertFrom-Json |
|
||
Select-Object -ExpandProperty data |
|
||
Select-Object -ExpandProperty windows |
|
||
Where-Object { $_.process_name -match "iSphere|IMPlatform|IMPP" -or $_.title -match "iSphere|IMPlatform|IMPP" } |
|
||
Format-Table hwnd,pid,process_name,title,class_name,visible,score -AutoSize
|
||
```
|
||
|
||
## 11. 保存所选窗口元数据
|
||
|
||
把 `<HWND>` 替换为扫描输出中的目标窗口句柄，例如 `0x001A0B2C`。
|
||
|
||
```powershell
|
||
$selectedHwnd = "<HWND>"
|
||
|
||
$scanObj = Get-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8 | ConvertFrom-Json
|
||
$selected = $scanObj.data.windows | Where-Object { $_.hwnd -eq $selectedHwnd } | Select-Object -First 1
|
||
if (-not $selected) { throw "selected hwnd not found in scan result: $selectedHwnd" }
|
||
$selected | ConvertTo-Json -Depth 8 | Set-Content -Path "$captureRoot\windows\selected-window.json" -Encoding UTF8
|
||
```
|
||
|
||
## 12. 采集 UIA dump
|
||
|
||
先使用保守限制：
|
||
|
||
```powershell
|
||
@{
|
||
protocol = "isphere.helper.v1"
|
||
request_id = "n12r-dump-uia-main"
|
||
op = "dump_uia"
|
||
timeout_ms = 15000
|
||
args = @{
|
||
hwnd = $selectedHwnd
|
||
max_depth = 8
|
||
include_text = $true
|
||
max_children = 100
|
||
}
|
||
} | ConvertTo-Json -Depth 12 -Compress |
|
||
& $helper --json |
|
||
Set-Content -Path "$captureRoot\uia\dump-uia-main.json" -Encoding UTF8
|
||
```
|
||
|
||
如果 dump 过大或被截断，可以调整限制后再重复一次，并另存为附加文件，例如：
|
||
|
||
```text
|
||
uia/dump-uia-main-depth10-children150.json
|
||
```
|
||
|
||
采集期间不要点击、输入、发送、上传、下载或修改 iSphere 客户端状态。
|
||
|
||
## 13. 创建脱敏 UIA 副本
|
||
|
||
创建用于共享的副本：
|
||
|
||
```powershell
|
||
Copy-Item -LiteralPath "$captureRoot\uia\dump-uia-main.json" -Destination "$captureRoot\uia\dump-uia-main-redacted.json" -Force
|
||
```
|
||
|
||
然后人工检查 `dump-uia-main-redacted.json`，在广泛共享前脱敏可见敏感文本。
|
||
|
||
需要脱敏：
|
||
|
||
```text
|
||
人员姓名
|
||
电话号码
|
||
邮箱
|
||
消息文本
|
||
联系人名称
|
||
组织敏感内容
|
||
类似凭据/token 的字符串
|
||
敏感业务文档标题
|
||
```
|
||
|
||
尽量保留结构性 selector 字段：
|
||
|
||
```text
|
||
control_type
|
||
automation_id
|
||
class_name
|
||
framework_id
|
||
bounds
|
||
is_enabled
|
||
is_offscreen
|
||
children shape
|
||
```
|
||
|
||
## 14. 写操作员备注
|
||
|
||
```powershell
|
||
@"
|
||
打开的客户端: <iSphere / IMPlatformClient>
|
||
登录方式: 人工正常公司流程
|
||
是否使用 MFA/SSO: 是/否，不包含任何秘密
|
||
所选窗口 hwnd: $selectedHwnd
|
||
选择该窗口的原因: <进程/标题/类名/评分原因>
|
||
已做脱敏: <简要列表>
|
||
采集问题: <简要列表>
|
||
forbidden actions performed: no
|
||
"@ | Set-Content -Path "$captureRoot\notes\operator-notes.txt" -Encoding UTF8
|
||
```
|
||
|
||
## 15. 复制出去前验证采集包
|
||
|
||
运行：
|
||
|
||
```powershell
|
||
$required = @(
|
||
"$captureRoot\metadata\source-notes.txt",
|
||
"$captureRoot\helper\version.json",
|
||
"$captureRoot\helper\self-check.json",
|
||
"$captureRoot\windows\scan-windows.json",
|
||
"$captureRoot\windows\selected-window.json",
|
||
"$captureRoot\uia\dump-uia-main.json",
|
||
"$captureRoot\uia\dump-uia-main-redacted.json",
|
||
"$captureRoot\notes\operator-notes.txt"
|
||
)
|
||
foreach ($path in $required) {
|
||
if (-not (Test-Path -LiteralPath $path)) { throw "missing required file: $path" }
|
||
}
|
||
"N12R package files present: $captureRoot" | Tee-Object -FilePath "$captureRoot\metadata\verification-summary.txt"
|
||
```
|
||
|
||
检查 JSON 是否可解析：
|
||
|
||
```powershell
|
||
Get-Content "$captureRoot\helper\version.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null
|
||
Get-Content "$captureRoot\helper\self-check.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null
|
||
Get-Content "$captureRoot\windows\scan-windows.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null
|
||
Get-Content "$captureRoot\windows\selected-window.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null
|
||
Get-Content "$captureRoot\uia\dump-uia-main.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null
|
||
Get-Content "$captureRoot\uia\dump-uia-main-redacted.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null
|
||
```
|
||
|
||
## 16. 打包传输
|
||
|
||
压缩采集目录：
|
||
|
||
```powershell
|
||
Compress-Archive -LiteralPath $captureRoot -DestinationPath "$captureRoot.zip" -Force
|
||
```
|
||
|
||
把目录或 zip 复制回外网仓库环境，并放到：
|
||
|
||
```text
|
||
runs/internal-sandbox-live-capture/<capture-id>/
|
||
```
|
||
|
||
## 17. 回报内容
|
||
|
||
告知协调会话：
|
||
|
||
```text
|
||
N12R 采集包已准备好。
|
||
路径: runs/internal-sandbox-live-capture/<capture-id>/
|
||
人工 iSphere 登录: 是
|
||
采集期间主窗口可见: 是
|
||
forbidden actions performed: no
|
||
```
|
||
|
||
随后由协调会话验证返回包。不要把原始当前环境 N12 标记为通过。
|