diff --git a/docs/internal-sandbox-operator-runbook.md b/docs/internal-sandbox-operator-runbook.md index 9543c95..0f3400f 100644 --- a/docs/internal-sandbox-operator-runbook.md +++ b/docs/internal-sandbox-operator-runbook.md @@ -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 -manual open iSphere / IMPlatformClient -manual normal login -keep main window visible -run version -run self_check -run scan_windows -run dump_uia -copy JSON/text outputs into a package +人工打开 iSphere / IMPlatformClient +人工正常登录 +保持主窗口可见 +运行 version +运行 self_check +运行 scan_windows +运行 dump_uia +把 JSON / 文本文档输出复制进采集包 ``` -Do not do these actions: +禁止执行以下动作: ```text -automatic login -search contacts -open conversation -send message -send file -receive/download file -use copied credentials -extract password/token/cookie/private key -inject process +自动登录 +搜索联系人 +打开会话 +发送消息 +发送文件 +接收/下载文件 +使用复制出来的凭据 +提取密码/token/cookie/私钥 +注入进程 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 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 git status --short --branch ``` -Recommended: record this output into the package later as: +建议稍后把该输出记录到采集包中,文件名为: ```text metadata/repo-status.txt ``` -## 3. Verify helper and Go MCP readiness +## 3. 验证 helper 和 Go MCP 准备情况 -Run helper verification: +运行 helper 验证: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1 ``` -Expected high-level result: +期望的高层结果: ```text ok=true 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 -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1 ``` -Expected high-level result: +期望的高层结果: ```text ok=true @@ -92,17 +92,17 @@ helper_name=ISphereWinHelper 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 YYYY-MM-DD-internal-sandbox- ``` -Example: +示例: ```powershell $captureId = "2026-07-08-internal-sandbox-a" @@ -115,16 +115,16 @@ New-Item -ItemType Directory -Force -Path ` "$captureRoot\notes" | Out-Null ``` -## 5. Record metadata +## 5. 记录元数据 -Record OS version: +记录操作系统版本: ```powershell Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsBuildNumber, CsUserName | Format-List | Out-File -FilePath "$captureRoot\metadata\os-version.txt" -Encoding UTF8 ``` -Record process list: +记录进程列表: ```powershell 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 ``` -Record repo status: +记录仓库状态: ```powershell git status --short --branch | Out-File -FilePath "$captureRoot\metadata\repo-status.txt" -Encoding UTF8 ``` -Create source notes: +创建来源说明: ```powershell @" capture_id: $captureId -source_environment: internal-network test sandbox -operator: +source_environment: 内网测试沙盒 +operator: <填写操作员姓名或角色> capture_time_local: $(Get-Date -Format "yyyy-MM-dd HH:mm:ss zzz") -iSphere manually logged in: yes/no -client opened before capture: yes/no -main window visible: yes/no +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 ``` -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. -2. Log in manually using the normal company process. -3. Complete SSO/MFA if required. -4. Do not use copied credentials or offline evidence files. -5. Keep the main iSphere window visible and not minimized. +1. 使用内网沙盒的正常方式打开 iSphere / IMPlatformClient。 +2. 按公司正常流程人工登录。 +3. 如需 SSO/MFA,请正常完成。 +4. 不要使用复制出来的凭据,也不要使用离线证据文件。 +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 runs\win-helper\ISphereWinHelper.exe ``` -Set: +设置变量: ```powershell $helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe" ``` -## 8. Capture helper version +## 8. 采集 helper 版本 ```powershell @{ @@ -195,7 +195,7 @@ $helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe" Set-Content -Path "$captureRoot\helper\version.json" -Encoding UTF8 ``` -## 9. Capture self check +## 9. 采集 self_check ```powershell @{ @@ -209,7 +209,7 @@ $helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe" Set-Content -Path "$captureRoot\helper\self-check.json" -Encoding UTF8 ``` -## 10. Scan visible windows +## 10. 扫描可见窗口 ```powershell @{ @@ -223,7 +223,7 @@ $helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe" 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 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 ``` -## 11. Save selected window metadata +## 11. 保存所选窗口元数据 -Replace `` with the selected window handle from the scan output, such as `0x001A0B2C`. +把 `` 替换为扫描输出中的目标窗口句柄,例如 `0x001A0B2C`。 ```powershell $selectedHwnd = "" @@ -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 ``` -## 12. Capture UIA dump +## 12. 采集 UIA dump -Use conservative limits first: +先使用保守限制: ```powershell @{ @@ -267,38 +267,38 @@ Use conservative limits first: 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 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 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 -person names -phone numbers -emails -message text -contact names -organization-sensitive content -credential/token-like strings -business document titles if sensitive +人员姓名 +电话号码 +邮箱 +消息文本 +联系人名称 +组织敏感内容 +类似凭据/token 的字符串 +敏感业务文档标题 ``` -Keep structural selector fields when possible: +尽量保留结构性 selector 字段: ```text control_type @@ -311,24 +311,24 @@ is_offscreen children shape ``` -## 14. Write operator notes +## 14. 写操作员备注 ```powershell @" -What client was opened: -How login was performed: manual normal company process -Any MFA/SSO used: yes/no, no secrets included -Selected window hwnd: $selectedHwnd -Selected window reason: -Redactions applied: -Any capture problems: -Forbidden actions performed: no +打开的客户端: +登录方式: 人工正常公司流程 +是否使用 MFA/SSO: 是/否,不包含任何秘密 +所选窗口 hwnd: $selectedHwnd +选择该窗口的原因: <进程/标题/类名/评分原因> +已做脱敏: <简要列表> +采集问题: <简要列表> +forbidden actions performed: no "@ | Set-Content -Path "$captureRoot\notes\operator-notes.txt" -Encoding UTF8 ``` -## 15. Verify package before copying out +## 15. 复制出去前验证采集包 -Run: +运行: ```powershell $required = @( @@ -347,7 +347,7 @@ foreach ($path in $required) { "N12R package files present: $captureRoot" | Tee-Object -FilePath "$captureRoot\metadata\verification-summary.txt" ``` -Check JSON parseability: +检查 JSON 是否可解析: ```powershell 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 ``` -## 16. Package for transfer +## 16. 打包传输 -Compress the capture directory: +压缩采集目录: ```powershell Compress-Archive -LiteralPath $captureRoot -DestinationPath "$captureRoot.zip" -Force ``` -Copy either the directory or zip back to the outer-network repository environment under: +把目录或 zip 复制回外网仓库环境,并放到: ```text runs/internal-sandbox-live-capture// ``` -## 17. What to report back +## 17. 回报内容 -Tell the coordinating session: +告知协调会话: ```text -N12R package is ready. -Path: runs/internal-sandbox-live-capture// -Manual iSphere login: yes -Main window visible during capture: yes -Forbidden actions performed: no +N12R 采集包已准备好。 +路径: runs/internal-sandbox-live-capture// +人工 iSphere 登录: 是 +采集期间主窗口可见: 是 +forbidden actions performed: no ``` -The coordinating session will then validate the returned package. Do not mark original current-environment N12 as passed. +随后由协调会话验证返回包。不要把原始当前环境 N12 标记为通过。