admin/isphere-ai-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: translate internal sandbox runbook to Chinese

Browse Source
This commit is contained in:
石头
2026-07-08 16:40:36 +08:00
parent c54f7c447a
commit 08516ed35a
1 changed files with 109 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
docs/internal-sandbox-operator-runbook.md
View File

@@ -1,89 +1,89 @@
# Internal Sandbox Operator Runbook # 内网沙盒操作员运行手册
This runbook is for the operator who has access to an internal-network test sandbox where iSphere / IMPlatformClient can be manually opened and logged in. 本手册供能够访问内网测试沙盒的操作员使用；该沙盒中可以人工打开并登录 iSphere / IMPlatformClient。
The goal is to produce a live read-only capture package for the outer-network coordination environment. 目标是为外网协调环境生成一个“已登录状态下的只读现场采集包”。
## 1. Safety boundary ## 1. 安全边界
Do only these actions: 只允许执行以下动作：
```text ```text
manual open iSphere / IMPlatformClient 人工打开 iSphere / IMPlatformClient
manual normal login 人工正常登录
keep main window visible 保持主窗口可见
run version 运行 version
run self_check 运行 self_check
run scan_windows 运行 scan_windows
run dump_uia 运行 dump_uia
copy JSON/text outputs into a package 把 JSON / 文本文档输出复制进采集包
``` ```
Do not do these actions: 禁止执行以下动作：
```text ```text
automatic login 自动登录
search contacts 搜索联系人
open conversation 打开会话
send message 发送消息
send file 发送文件
receive/download file 接收/下载文件
use copied credentials 使用复制出来的凭据
extract password/token/cookie/private key 提取密码/token/cookie/私钥
inject process 注入进程
hook hook
read target process memory 读取目标进程内存
bypass endpoint security 绕过终端安全/安防
run executables copied from offline evidence packages 运行离线证据包中复制出来的可执行文件
``` ```
## 2. Prepare repository in the internal sandbox ## 2. 在内网沙盒中准备仓库
Open PowerShell in the repository root. 在仓库根目录打开 PowerShell。
Example: 示例：
```powershell ```powershell
cd E:\isphere-ai-bridge cd E:\isphere-ai-bridge
``` ```
If the repository path is different, use that actual path. All commands below assume the repository root is the current directory. 如果仓库路径不同，请使用实际路径。下面所有命令都假设当前目录是仓库根目录。
Check repository status: 检查仓库状态：
```powershell ```powershell
git status --short --branch git status --short --branch
``` ```
Recommended: record this output into the package later as: 建议稍后把该输出记录到采集包中，文件名为：
```text ```text
metadata/repo-status.txt metadata/repo-status.txt
``` ```
## 3. Verify helper and Go MCP readiness ## 3. 验证 helper 和 Go MCP 准备情况
Run helper verification: 运行 helper 验证：
```powershell ```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1
``` ```
Expected high-level result: 期望的高层结果：
```text ```text
ok=true ok=true
helper version=0.1.0 helper version=0.1.0
uia_available=true or valid boolean uia_available=true 或有效布尔值
``` ```
If Go is installed in the internal sandbox, also run: 如果内网沙盒已安装 Go，也运行：
```powershell ```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
``` ```
Expected high-level result: 期望的高层结果：
```text ```text
ok=true ok=true
@@ -92,17 +92,17 @@ helper_name=ISphereWinHelper
action_tools_present=false action_tools_present=false
``` ```
If Go is unavailable, do not install unrelated tooling during the capture window unless the operator has approval. The C# helper fallback below is enough to capture the same four read-only helper operations. 如果没有 Go，不要在采集窗口内临时安装无关工具，除非操作员已获得批准。下面的 C# helper 兜底流程足以采集同样四个只读 helper 操作。
## 4. Create capture directory ## 4. 创建采集目录
Choose a capture id. Recommended format: 选择一个采集编号。推荐格式：
```text ```text
YYYY-MM-DD-internal-sandbox-<short-name> YYYY-MM-DD-internal-sandbox-<short-name>
``` ```
Example: 示例：
```powershell ```powershell
$captureId = "2026-07-08-internal-sandbox-a" $captureId = "2026-07-08-internal-sandbox-a"
@@ -115,16 +115,16 @@ New-Item -ItemType Directory -Force -Path `
"$captureRoot\notes" | Out-Null "$captureRoot\notes" | Out-Null
``` ```
## 5. Record metadata ## 5. 记录元数据
Record OS version: 记录操作系统版本：
```powershell ```powershell
Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsBuildNumber, CsUserName | Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsBuildNumber, CsUserName |
Format-List | Out-File -FilePath "$captureRoot\metadata\os-version.txt" -Encoding UTF8 Format-List | Out-File -FilePath "$captureRoot\metadata\os-version.txt" -Encoding UTF8
``` ```
Record process list: 记录进程列表：
```powershell ```powershell
Get-Process | Sort-Object ProcessName | Get-Process | Sort-Object ProcessName |
@@ -132,56 +132,56 @@ Get-Process | Sort-Object ProcessName |
Format-Table -AutoSize | Out-File -FilePath "$captureRoot\metadata\process-list.txt" -Encoding UTF8 Format-Table -AutoSize | Out-File -FilePath "$captureRoot\metadata\process-list.txt" -Encoding UTF8
``` ```
Record repo status: 记录仓库状态：
```powershell ```powershell
git status --short --branch | Out-File -FilePath "$captureRoot\metadata\repo-status.txt" -Encoding UTF8 git status --short --branch | Out-File -FilePath "$captureRoot\metadata\repo-status.txt" -Encoding UTF8
``` ```
Create source notes: 创建来源说明：
```powershell ```powershell
@" @"
capture_id: $captureId capture_id: $captureId
source_environment: internal-network test sandbox source_environment: 内网测试沙盒
operator: <fill operator name or role> operator: <填写操作员姓名或角色>
capture_time_local: $(Get-Date -Format "yyyy-MM-dd HH:mm:ss zzz") capture_time_local: $(Get-Date -Format "yyyy-MM-dd HH:mm:ss zzz")
iSphere manually logged in: yes/no iSphere manually logged in: 是/否
client opened before capture: yes/no client opened before capture: 是/否
main window visible: yes/no main window visible: 是/否
operations used: version, self_check, scan_windows, dump_uia operations used: version, self_check, scan_windows, dump_uia
forbidden actions performed: no forbidden actions performed: no
this package is N12R live evidence, not current-environment N12 pass this package is N12R live evidence, not current-environment N12 pass
"@ | Set-Content -Path "$captureRoot\metadata\source-notes.txt" -Encoding UTF8 "@ | Set-Content -Path "$captureRoot\metadata\source-notes.txt" -Encoding UTF8
``` ```
Before packaging, edit the `yes/no` fields so they are accurate. 打包前，请把 `是/否` 字段改成真实情况。
## 6. Manual login ## 6. 人工登录
1. Open iSphere / IMPlatformClient using the normal internal sandbox method. 1. 使用内网沙盒的正常方式打开 iSphere / IMPlatformClient。
2. Log in manually using the normal company process. 2. 按公司正常流程人工登录。
3. Complete SSO/MFA if required. 3. 如需 SSO/MFA，请正常完成。
4. Do not use copied credentials or offline evidence files. 4. 不要使用复制出来的凭据，也不要使用离线证据文件。
5. Keep the main iSphere window visible and not minimized. 5. 保持 iSphere 主窗口可见，不要最小化。
Do not click into contacts or conversations unless normal login itself requires it. Do not send or receive anything. 除非正常登录流程本身需要，否则不要点击联系人或会话。不要发送或接收任何内容。
## 7. Build helper path variable ## 7. 设置 helper 路径变量
After `verify-win-helper.ps1`, the helper should exist at: 运行 `verify-win-helper.ps1` 后，helper 应位于：
```text ```text
runs\win-helper\ISphereWinHelper.exe runs\win-helper\ISphereWinHelper.exe
``` ```
Set: 设置变量：
```powershell ```powershell
$helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe" $helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe"
``` ```
## 8. Capture helper version ## 8. 采集 helper 版本
```powershell ```powershell
@{ @{
@@ -195,7 +195,7 @@ $helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe"
Set-Content -Path "$captureRoot\helper\version.json" -Encoding UTF8 Set-Content -Path "$captureRoot\helper\version.json" -Encoding UTF8
``` ```
## 9. Capture self check ## 9. 采集 self_check
```powershell ```powershell
@{ @{
@@ -209,7 +209,7 @@ $helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe"
Set-Content -Path "$captureRoot\helper\self-check.json" -Encoding UTF8 Set-Content -Path "$captureRoot\helper\self-check.json" -Encoding UTF8
``` ```
## 10. Scan visible windows ## 10. 扫描可见窗口
```powershell ```powershell
@{ @{
@@ -223,7 +223,7 @@ $helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe"
Set-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8 Set-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8
``` ```
Open the scan result and identify the likely iSphere / IMPlatformClient window by process name, title, class name, visibility, bounds, and score: 打开扫描结果，根据进程名、标题、类名、可见性、边界和评分识别最可能的 iSphere / IMPlatformClient 窗口：
```powershell ```powershell
Get-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8 | ConvertFrom-Json | Get-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8 | ConvertFrom-Json |
@@ -233,9 +233,9 @@ Get-Content -Path "$captureRoot\windows\scan-windows.json" -Encoding UTF8 | Conv
Format-Table hwnd,pid,process_name,title,class_name,visible,score -AutoSize Format-Table hwnd,pid,process_name,title,class_name,visible,score -AutoSize
``` ```
## 11. Save selected window metadata ## 11. 保存所选窗口元数据
Replace `<HWND>` with the selected window handle from the scan output, such as `0x001A0B2C`. 把 `<HWND>` 替换为扫描输出中的目标窗口句柄，例如 `0x001A0B2C`。
```powershell ```powershell
$selectedHwnd = "<HWND>" $selectedHwnd = "<HWND>"
@@ -246,9 +246,9 @@ if (-not $selected) { throw "selected hwnd not found in scan result: $selectedHw
$selected | ConvertTo-Json -Depth 8 | Set-Content -Path "$captureRoot\windows\selected-window.json" -Encoding UTF8 $selected | ConvertTo-Json -Depth 8 | Set-Content -Path "$captureRoot\windows\selected-window.json" -Encoding UTF8
``` ```
## 12. Capture UIA dump ## 12. 采集 UIA dump
Use conservative limits first: 先使用保守限制：
```powershell ```powershell
@{ @{
@@ -267,38 +267,38 @@ Use conservative limits first:
Set-Content -Path "$captureRoot\uia\dump-uia-main.json" -Encoding UTF8 Set-Content -Path "$captureRoot\uia\dump-uia-main.json" -Encoding UTF8
``` ```
If the dump is too large or truncated, repeat once with adjusted limits and save as an additional file, for example: 如果 dump 过大或被截断，可以调整限制后再重复一次，并另存为附加文件，例如：
```text ```text
uia/dump-uia-main-depth10-children150.json uia/dump-uia-main-depth10-children150.json
``` ```
Do not click, type, send, upload, download, or modify the iSphere client during capture. 采集期间不要点击、输入、发送、上传、下载或修改 iSphere 客户端状态。
## 13. Create a redacted UIA copy ## 13. 创建脱敏 UIA 副本
Create a copy for sharing: 创建用于共享的副本：
```powershell ```powershell
Copy-Item -LiteralPath "$captureRoot\uia\dump-uia-main.json" -Destination "$captureRoot\uia\dump-uia-main-redacted.json" -Force Copy-Item -LiteralPath "$captureRoot\uia\dump-uia-main.json" -Destination "$captureRoot\uia\dump-uia-main-redacted.json" -Force
``` ```
Then manually review `dump-uia-main-redacted.json` and redact sensitive visible text before sharing broadly. 然后人工检查 `dump-uia-main-redacted.json`，在广泛共享前脱敏可见敏感文本。
Redact: 需要脱敏：
```text ```text
person names 人员姓名
phone numbers 电话号码
emails 邮箱
message text 消息文本
contact names 联系人名称
organization-sensitive content 组织敏感内容
credential/token-like strings 类似凭据/token 的字符串
business document titles if sensitive 敏感业务文档标题
``` ```
Keep structural selector fields when possible: 尽量保留结构性 selector 字段：
```text ```text
control_type control_type
@@ -311,24 +311,24 @@ is_offscreen
children shape children shape
``` ```
## 14. Write operator notes ## 14. 写操作员备注
```powershell ```powershell
@" @"
What client was opened: <iSphere / IMPlatformClient> 打开的客户端: <iSphere / IMPlatformClient>
How login was performed: manual normal company process 登录方式: 人工正常公司流程
Any MFA/SSO used: yes/no, no secrets included 是否使用 MFA/SSO: 是/否，不包含任何秘密
Selected window hwnd: $selectedHwnd 所选窗口 hwnd: $selectedHwnd
Selected window reason: <process/title/class/score reason> 选择该窗口的原因: <进程/标题/类名/评分原因>
Redactions applied: <brief list> 已做脱敏: <简要列表>
Any capture problems: <brief list> 采集问题: <简要列表>
Forbidden actions performed: no forbidden actions performed: no
"@ | Set-Content -Path "$captureRoot\notes\operator-notes.txt" -Encoding UTF8 "@ | Set-Content -Path "$captureRoot\notes\operator-notes.txt" -Encoding UTF8
``` ```
## 15. Verify package before copying out ## 15. 复制出去前验证采集包
Run: 运行：
```powershell ```powershell
$required = @( $required = @(
@@ -347,7 +347,7 @@ foreach ($path in $required) {
"N12R package files present: $captureRoot" | Tee-Object -FilePath "$captureRoot\metadata\verification-summary.txt" "N12R package files present: $captureRoot" | Tee-Object -FilePath "$captureRoot\metadata\verification-summary.txt"
``` ```
Check JSON parseability: 检查 JSON 是否可解析：
```powershell ```powershell
Get-Content "$captureRoot\helper\version.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null Get-Content "$captureRoot\helper\version.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null
@@ -358,30 +358,30 @@ Get-Content "$captureRoot\uia\dump-uia-main.json" -Encoding UTF8 | ConvertFrom-J
Get-Content "$captureRoot\uia\dump-uia-main-redacted.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null Get-Content "$captureRoot\uia\dump-uia-main-redacted.json" -Encoding UTF8 | ConvertFrom-Json | Out-Null
``` ```
## 16. Package for transfer ## 16. 打包传输
Compress the capture directory: 压缩采集目录：
```powershell ```powershell
Compress-Archive -LiteralPath $captureRoot -DestinationPath "$captureRoot.zip" -Force Compress-Archive -LiteralPath $captureRoot -DestinationPath "$captureRoot.zip" -Force
``` ```
Copy either the directory or zip back to the outer-network repository environment under: 把目录或 zip 复制回外网仓库环境，并放到：
```text ```text
runs/internal-sandbox-live-capture/<capture-id>/ runs/internal-sandbox-live-capture/<capture-id>/
``` ```
## 17. What to report back ## 17. 回报内容
Tell the coordinating session: 告知协调会话：
```text ```text
N12R package is ready. N12R 采集包已准备好。
Path: runs/internal-sandbox-live-capture/<capture-id>/ 路径: runs/internal-sandbox-live-capture/<capture-id>/
Manual iSphere login: yes 人工 iSphere 登录: 是
Main window visible during capture: yes 采集期间主窗口可见: 是
Forbidden actions performed: no forbidden actions performed: no
``` ```
The coordinating session will then validate the returned package. Do not mark original current-environment N12 as passed. 随后由协调会话验证返回包。不要把原始当前环境 N12 标记为通过。