docs: add N12R internal sandbox handoff workflow
This commit is contained in:
石头
387
docs/internal-sandbox-operator-runbook.md
Normal file
387
docs/internal-sandbox-operator-runbook.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# 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.
|
||||
|
||||
The goal is to produce a live read-only capture package for the outer-network coordination environment.
|
||||
|
||||
## 1. Safety boundary
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
hook
|
||||
read target process memory
|
||||
bypass endpoint security
|
||||
run executables copied from offline evidence packages
|
||||
```
|
||||
|
||||
## 2. Prepare repository in the internal sandbox
|
||||
|
||||
Open PowerShell in the repository root.
|
||||
|
||||
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
|
||||
|
||||
Run helper verification:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
If Go is installed in the internal sandbox, also run:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
|
||||
```
|
||||
|
||||
Expected high-level result:
|
||||
|
||||
```text
|
||||
ok=true
|
||||
tool_count=4
|
||||
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.
|
||||
|
||||
## 4. Create capture directory
|
||||
|
||||
Choose a capture id. Recommended format:
|
||||
|
||||
```text
|
||||
YYYY-MM-DD-internal-sandbox-<short-name>
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```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. Record metadata
|
||||
|
||||
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 |
|
||||
Select-Object ProcessName, Id, MainWindowTitle, Path |
|
||||
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: <fill operator name or role>
|
||||
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
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
Do not click into contacts or conversations unless normal login itself requires it. Do not send or receive anything.
|
||||
|
||||
## 7. Build helper path variable
|
||||
|
||||
After `verify-win-helper.ps1`, the helper should exist at:
|
||||
|
||||
```text
|
||||
runs\win-helper\ISphereWinHelper.exe
|
||||
```
|
||||
|
||||
Set:
|
||||
|
||||
```powershell
|
||||
$helper = Resolve-Path -LiteralPath "runs\win-helper\ISphereWinHelper.exe"
|
||||
```
|
||||
|
||||
## 8. Capture helper version
|
||||
|
||||
```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. Capture 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. Scan visible windows
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Open the scan result and identify the likely iSphere / IMPlatformClient window by process name, title, class name, visibility, bounds, and score:
|
||||
|
||||
```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. Save selected window metadata
|
||||
|
||||
Replace `<HWND>` with the selected window handle from the scan output, such as `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. Capture UIA dump
|
||||
|
||||
Use conservative limits first:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
If the dump is too large or truncated, repeat once with adjusted limits and save as an additional file, for example:
|
||||
|
||||
```text
|
||||
uia/dump-uia-main-depth10-children150.json
|
||||
```
|
||||
|
||||
Do not click, type, send, upload, download, or modify the iSphere client during capture.
|
||||
|
||||
## 13. Create a redacted UIA copy
|
||||
|
||||
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.
|
||||
|
||||
Redact:
|
||||
|
||||
```text
|
||||
person names
|
||||
phone numbers
|
||||
emails
|
||||
message text
|
||||
contact names
|
||||
organization-sensitive content
|
||||
credential/token-like strings
|
||||
business document titles if sensitive
|
||||
```
|
||||
|
||||
Keep structural selector fields when possible:
|
||||
|
||||
```text
|
||||
control_type
|
||||
automation_id
|
||||
class_name
|
||||
framework_id
|
||||
bounds
|
||||
is_enabled
|
||||
is_offscreen
|
||||
children shape
|
||||
```
|
||||
|
||||
## 14. Write operator notes
|
||||
|
||||
```powershell
|
||||
@"
|
||||
What client was opened: <iSphere / IMPlatformClient>
|
||||
How login was performed: manual normal company process
|
||||
Any MFA/SSO used: yes/no, no secrets included
|
||||
Selected window hwnd: $selectedHwnd
|
||||
Selected window reason: <process/title/class/score reason>
|
||||
Redactions applied: <brief list>
|
||||
Any capture problems: <brief list>
|
||||
Forbidden actions performed: no
|
||||
"@ | Set-Content -Path "$captureRoot\notes\operator-notes.txt" -Encoding UTF8
|
||||
```
|
||||
|
||||
## 15. Verify package before copying out
|
||||
|
||||
Run:
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
Check JSON parseability:
|
||||
|
||||
```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. Package for transfer
|
||||
|
||||
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:
|
||||
|
||||
```text
|
||||
runs/internal-sandbox-live-capture/<capture-id>/
|
||||
```
|
||||
|
||||
## 17. What to report back
|
||||
|
||||
Tell the coordinating session:
|
||||
|
||||
```text
|
||||
N12R package is ready.
|
||||
Path: runs/internal-sandbox-live-capture/<capture-id>/
|
||||
Manual iSphere login: yes
|
||||
Main window visible during capture: yes
|
||||
Forbidden actions performed: no
|
||||
```
|
||||
|
||||
The coordinating session will then validate the returned package. Do not mark original current-environment N12 as passed.
|
||||
Reference in New Issue
Block a user