isphere-ai-bridge/docs/offline-evidence-intake-plan.md

# Offline Evidence Intake Plan

## 1. Conclusion

The current environment cannot log in to iSphere / IMPlatformClient. Therefore the original N12 live gate is still blocked.

The replacement route before N12 is:

```text
N12-pre: Offline evidence intake
```

N12-pre now supports two intake modes:

1. **A. Full sandbox artifact bundle (recommended)**
   - The user does not need to understand JSON.
   - The user copies the logged-in test sandbox's relevant installation and user-data directories into a structured evidence folder.
   - This is the preferred route when the user can only log in in another sandbox.

2. **B. Minimal redacted UIA package (optional, advanced users only)**
   - The user/operator already knows how to run the four read-only helper/MCP operations and produce `manifest.json`, `scan_windows-redacted.json`, and `dump_uia-main-redacted.json`.
   - This remains useful for controlled UIA-only capture, but it is no longer the default request to the user.

Neither mode is N12 pass. In both cases this is **not N12 pass** because the current repository environment still has not shown a live, manually logged-in iSphere main window through `win_helper_scan_windows` and `win_helper_dump_uia`.

## 2. Scope and boundary source

Boundary documents and implementation facts used by this plan:

- `docs/go-csharp-helper-boundary.md`: Go calls C# helper through `isphere.helper.v1`; the first phase only has four read-only ops.
- `docs/go-mcp-runbook.md`: current phase exposes four read-only tools and forbids search/send/file/login automation/security-bypass behavior.
- `native/ISphereWinHelper/Program.cs`: the helper dispatches only `version`, `self_check`, `scan_windows`, and `dump_uia` in the current implementation.
- `native/ISphereWinHelper/UiaDumper.cs`: `dump_uia` accepts `hwnd`, `max_depth`, `include_text`, and `max_children`.
- `native/ISphereWinHelper/WindowScanner.cs`: `scan_windows` accepts `include_all_visible`.

Allowed live helper/tool boundary remains exactly:

```text
version
self_check
scan_windows
dump_uia
```

N12-pre may include copied files from a separate test sandbox for offline reverse engineering, but it still must not design or perform: send message, send file, receive file, automatic login, injection, hook, target-process memory reading, endpoint-security bypass, stealth, persistence, or security evasion.

## 3. Why original N12 is still not satisfied

Original N12 requires all of the following in the current environment:

1. The user manually opens and logs in to iSphere / IMPlatformClient.
2. The main iSphere window is visible.
3. The Go MCP read-only tools run against that live window.
4. `win_helper_scan_windows` finds the candidate window.
5. `win_helper_dump_uia` returns a UIA control tree for that current-environment window.
6. No clicking, typing, sending, uploading, receiving/downloading, automatic login, injection, hook, target-process memory reading, or endpoint-security bypass occurs.

A copied test sandbox bundle does not satisfy N12 because:

- It proves only that files existed in another logged-in sandbox.
- It does not prove the current helper can see a current logged-in window.
- It does not produce a current-environment `hwnd`, live process id, or live UIA tree.
- It supports offline reverse analysis only.

Therefore all copied evidence is N12-pre context and **not N12 pass**.

## 4. Intake mode A: Full sandbox artifact bundle (recommended)

### 4.1 Purpose

Use this mode when the user says: "I can log in in another sandbox and copy files, but I do not know what manifest/scan/dump JSON is."

The user only needs to copy folders. The user does not need to run helper commands, does not need to create JSON, and does not need to understand UIA.

### 4.2 What to copy

Copy from the logged-in test sandbox after normal manual login has succeeded. Preserve the original directory structure as much as possible.

Recommended destination in this repository:

```text
runs/offline-evidence-intake/<evidence-id>/
  copy-notes.txt
  raw/
    install/
    user-profile/
    programdata/
    shortcuts/
    temp-importal-localcache/
    other-candidates/
  metadata/
    directory-tree.txt
    file-list.txt
    installed-programs.txt
    process-list.txt
    services.txt
    environment.txt
  notes/
    operator-notes.txt
```

Minimum useful bundle:

```text
runs/offline-evidence-intake/<evidence-id>/
  copy-notes.txt
  raw/install/
  raw/user-profile/
  raw/programdata/
  raw/shortcuts/
  metadata/
```

Recommended archive format:

```text
<evidence-id>.zip
```

or:

```text
<evidence-id>.7z
```

### 4.3 Windows candidate paths to collect

The exact install path may differ. Copy every matching candidate that exists in the logged-in test sandbox.

Installation directories:

```text
C:\Program Files\iSphere\
C:\Program Files\IMPlatformClient\
C:\Program Files (x86)\iSphere\
C:\Program Files (x86)\IMPlatformClient\
C:\Program Files\IMPP\
C:\Program Files (x86)\IMPP\
<custom install path containing iSphere, IMPlatformClient, IMPP, importal>
```

User data directories:

```text
%APPDATA%\iSphere\
%APPDATA%\IMPlatformClient\
%APPDATA%\IMPP\
%APPDATA%\importal\
%LOCALAPPDATA%\iSphere\
%LOCALAPPDATA%\IMPlatformClient\
%LOCALAPPDATA%\IMPP\
%LOCALAPPDATA%\importal\
%USERPROFILE%\Documents\iSphere\
%USERPROFILE%\Documents\IMPlatformClient\
```

Program data directories:

```text
%PROGRAMDATA%\iSphere\
%PROGRAMDATA%\IMPlatformClient\
%PROGRAMDATA%\IMPP\
%PROGRAMDATA%\importal\
```

Shortcut locations:

```text
%USERPROFILE%\Desktop\
%APPDATA%\Microsoft\Windows\Start Menu\Programs\
%PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\
```

Temp/cache candidates:

```text
%TEMP%\importal\
%TEMP%\importal\localcache\
%LOCALAPPDATA%\Temp\importal\
%LOCALAPPDATA%\Temp\importal\localcache\
C:\Users\<user>\AppData\Local\Temp\importal\localcache\
```

Historical clues to pay attention to, but not mandatory:

```text
importal\localcache
LoginLog
IMPP.Util.dll
IMPP.Util.Log.LogSecurityPolicy
IMPlatformClient
iSphere
IMPP
csimlog.dll
WriteLog
```

These names are useful search anchors during offline inventory. They are not a requirement for the user to understand.

### 4.4 Suggested copy layout mapping

Use this mapping when placing copied files into the evidence package:

| Source in test sandbox | Destination in package |
| --- | --- |
| iSphere / IMPlatformClient install folder | `raw/install/<original-folder-name>/` |
| `%APPDATA%` matching folders | `raw/user-profile/AppData/Roaming/<folder-name>/` |
| `%LOCALAPPDATA%` matching folders | `raw/user-profile/AppData/Local/<folder-name>/` |
| `%PROGRAMDATA%` matching folders | `raw/programdata/<folder-name>/` |
| Desktop and Start Menu shortcuts | `raw/shortcuts/<source-location>/` |
| `%TEMP%\importal` or localcache | `raw/temp-importal-localcache/<source-location>/` |
| Any extra matching folder | `raw/other-candidates/<short-description>/` |

### 4.5 `copy-notes.txt`

Ask the user to include a simple text file. No JSON required.

Template:

```text
Evidence ID: <evidence-id>
Source sandbox: test sandbox, manually logged in
Capture time: <local time if known>
iSphere was logged in before copy: yes/no/unknown
Copied install folders: <brief list>
Copied user folders: <brief list>
Copied temp/localcache folders: <brief list>
Anything missing or unavailable: <brief note>
This is N12-pre only, not N12 pass.
```

### 4.6 Metadata folder

The metadata folder is helpful but should stay simple. It can be generated by the sandbox operator or by manually exporting lists.

Suggested files:

```text
metadata/directory-tree.txt
metadata/file-list.txt
metadata/installed-programs.txt
metadata/process-list.txt
metadata/services.txt
metadata/environment.txt
```

Examples of acceptable metadata content:

- Directory trees for copied folders.
- File names, sizes, timestamps, and extensions.
- Installed program names related to iSphere / IMPlatformClient.
- Process list showing `IMPlatformClient`, `iSphere`, `IMPP`, or `importal` if present.
- Environment basics such as Windows version and username placeholder.

Metadata is not a tool implementation requirement. If the user cannot produce it, the raw folder bundle is still the priority.

## 5. Intake mode B: Minimal redacted UIA package (optional, advanced)

Use this only if the operator already understands the helper/MCP tools and can produce JSON.

Recommended directory:

```text
runs/offline-evidence-intake/<evidence-id>/
  manifest.json
  scan_windows-redacted.json
  dump_uia-main-redacted.json
  version.json                 # optional
  self_check.json              # optional
  notes.md                     # optional
```

Required files:

1. `manifest.json`
2. `scan_windows-redacted.json`
3. `dump_uia-main-redacted.json`

Required manifest status:

```text
offline_pre_only_not_n12_pass
```

The minimal UIA package may be useful when the operator can call only:

```text
version
self_check
scan_windows
dump_uia
```

### 5.1 `manifest.json` simple shape

```json
{
  "schema_version": "offline-evidence-intake.v1",
  "evidence_id": "2026-07-05-sandbox-a",
  "n12_status": "offline_pre_only_not_n12_pass",
  "source_environment": "separate_logged_in_test_sandbox",
  "operations_used": ["version", "self_check", "scan_windows", "dump_uia"],
  "files": [
    "manifest.json",
    "scan_windows-redacted.json",
    "dump_uia-main-redacted.json"
  ]
}
```

### 5.2 `scan_windows-redacted.json` requirements

Required concept:

- Output derived from `scan_windows`.
- Include iSphere / IMPlatformClient candidate windows.
- Preserve process name, class name, visible flag, bounds, and score when available.
- It is acceptable to replace raw `hwnd` and `pid` with placeholders because they do not work outside the source sandbox.

Example:

```json
{
  "schema_version": "offline-evidence-intake.v1",
  "source_op": "scan_windows",
  "n12_status": "offline_pre_only_not_n12_pass",
  "windows": [
    {
      "window_id": "win-main-1",
      "hwnd": "HWND_SOURCE_SANDBOX_1",
      "pid": "PID_SOURCE_SANDBOX_1",
      "process_name": "IMPlatformClient",
      "title": "iSphere main window",
      "class_name": "WindowsForms10.Window.8.app.example",
      "visible": true,
      "bounds": { "x": 0, "y": 0, "width": 1200, "height": 800 },
      "score": 110,
      "candidate_role": "main_window"
    }
  ]
}
```

### 5.3 `dump_uia-main-redacted.json` requirements

Required concept:

- Output derived from `dump_uia`.
- Preserve tree shape and selector fields: `name`, `control_type`, `automation_id`, `class_name`, `localized_control_type`, `framework_id`, `is_enabled`, `is_offscreen`, `bounds`, `children`, and `truncated_children`.
- If the operator wants to keep the package small, use `max_depth` and `max_children` limits.

Example:

```json
{
  "schema_version": "offline-evidence-intake.v1",
  "source_op": "dump_uia",
  "n12_status": "offline_pre_only_not_n12_pass",
  "window_id": "win-main-1",
  "hwnd": "HWND_SOURCE_SANDBOX_1",
  "dump_args": {
    "max_depth": 8,
    "include_text": true,
    "max_children": 80
  },
  "root": {
    "name": "iSphere main window",
    "control_type": "Window",
    "automation_id": "",
    "class_name": "WindowsForms10.Window.8.app.example",
    "localized_control_type": "window",
    "framework_id": "WinForm",
    "is_enabled": true,
    "is_offscreen": false,
    "bounds": { "x": 0, "y": 0, "width": 1200, "height": 800 },
    "children": []
  }
}
```

## 6. What we do after receiving a full bundle

Initial handling is read-only inventory:

1. Keep the uploaded archive or copied folder as the original evidence.
2. Do not directly run unknown binaries from the bundle.
3. Do not modify original copied files.
4. Inventory file names, sizes, timestamps, and directory layout.
5. Identify candidate config, cache, log, database, DLL, executable, and shortcut files.
6. Classify readable formats such as JSON, XML, INI, SQLite, plain text, compressed archives, and .NET assemblies.
7. If a file appears encrypted or proprietary, record the evidence and likely owner DLL/class; do not turn that into automatic login, injection, hook, target-process memory reading, or bypass behavior.
8. Produce a short offline evidence report listing what exists and which later analysis is safe.

Read-only inventory can inspect file metadata and parse copied files offline. It must not launch the copied client as the user's live client, send messages, transfer files, alter caches, or attempt automatic login.

## 7. Allowed offline analysis

After intake, offline analysis may:

- Build an inventory of installation files, configs, caches, logs, DLLs, shortcuts, and local databases.
- Identify likely startup entry points and installed executable names.
- Identify likely log/cache folders such as `importal\localcache` and `LoginLog`.
- Inspect .NET assembly metadata and strings from copied DLLs, including names like `IMPP.Util.dll`, without modifying the files.
- Parse readable copied logs/configs/databases in read-only mode.
- Draft hypotheses for future live UIA capture and selector design.

Offline analysis must not:

- Mark N12 passed.
- Implement search contacts, open conversation, send message, send file, receive file, automatic login, injection, hook, target-process memory reading, endpoint-security bypass, stealth, persistence, or security evasion.
- Run unknown copied binaries as part of intake.
- Modify the original bundle.
- Use any copied credential-like material to log in or impersonate a user.

## 8. Conditions to enter true N12

True N12 can start only when all of these are true:

1. N11 is accepted.
2. The current repository environment can manually open and log in to iSphere / IMPlatformClient using the normal approved process.
3. The current environment shows the main iSphere window visibly.
4. `scripts\verify-win-helper.ps1` and `scripts\verify-go-mcp.ps1` pass in the current environment.
5. The operator uses only `win_helper_scan_windows` and `win_helper_dump_uia` against the current visible logged-in window.
6. The output is saved under `runs\real-loggedin-lab\uia-dumps\`.
7. No clicking, typing, sending, uploading, receiving/downloading, automatic login, injection, hook, target-process memory reading, or endpoint-security bypass occurs.

If the current environment still cannot log in, only N12-pre offline analysis is allowed. N12 remains blocked and must not be marked passed.

## 9. Coordinator request checklist for the user

Use this final user-facing request. It intentionally avoids asking the user to understand JSON.

```text
请在能登录 iSphere 的测试沙盒里，先正常手动登录一次，然后把相关文件夹复制出来，打成 zip 或 7z。

放到本仓库时建议路径：
runs/offline-evidence-intake/<evidence-id>/

推荐目录结构：
raw/install/                 放安装目录
raw/user-profile/            放 %APPDATA% 和 %LOCALAPPDATA% 里相关目录
raw/programdata/             放 %PROGRAMDATA% 里相关目录
raw/shortcuts/               放桌面和开始菜单快捷方式
raw/temp-importal-localcache/ 放 %TEMP%\importal 或 localcache 相关目录
metadata/                    放目录树、文件列表、进程列表等，有就放，没有也可以
notes/copy-notes.txt         简单写明从哪里复制、是否登录后复制

优先找这些路径或名字：
- C:\Program Files 或 C:\Program Files (x86) 下包含 iSphere、IMPlatformClient、IMPP、importal 的目录
- %APPDATA% 下包含 iSphere、IMPlatformClient、IMPP、importal 的目录
- %LOCALAPPDATA% 下包含 iSphere、IMPlatformClient、IMPP、importal 的目录
- %PROGRAMDATA% 下包含 iSphere、IMPlatformClient、IMPP、importal 的目录
- Documents 里相关目录
- Desktop 和 Start Menu 里的快捷方式
- %TEMP%\importal\localcache 或类似 localcache 目录
- 特别关注但不强制：importal\localcache、LoginLog、IMPP.Util.dll、IMPlatformClient、iSphere

要求：
- 保留原目录结构，最好整体压缩成 zip/7z。
- 附一个 copy-notes.txt，写明大概复制了哪些目录。
- 这只是 N12-pre 离线证据，不是 N12 通过。
- 不需要生成 manifest/scan/dump JSON；那些是高级可选路径。
- 不要做自动登录、发送消息、发送文件、接收文件、注入、hook、读内存或规避安防。
```