From 1c99bfbeffff04529f6f669601fdf835a73778da Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Fri, 2 Oct 2026 11:44:31 -0400 Subject: rename (cosmetic): green-eye -> risc-v-gsp-rm-debugger in user-facing names, docs, CLI, launcher and CI workflow; internal greeneye package/module identifiers unchanged (includes in-flight greeneye module edits present in the tree) --- .../docs/14-ADVERSARIAL-INTEROP-GUIDE.md | 46 +++++++++++----------- 1 file changed, 23 insertions(+), 23 deletions(-) (limited to 'debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md') diff --git a/debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md b/debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md index fb78265..f5b2568 100644 --- a/debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md +++ b/debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md @@ -1,4 +1,4 @@ -# 14 — Firmware adversarial interoperability research guide (green-eye + Ghidra) +# 14 — Firmware adversarial interoperability research guide (risc-v-gsp-rm-debugger + Ghidra) > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. @@ -8,10 +8,10 @@ Open-IOV's hard problem is not writing the GSP emulation once; it is keeping `open-iov-vfio` accurate while the firmware changes underneath it. New GSP images, device pairings and architectures arrive stripped, signed and hardware-coupled, and some actively resist analysis. This guide is the -practical companion to `GREEN-EYE-ROADMAP.md` H4: how to move from "the new +practical companion to `RISC-V-GSP-RM-DEBUGGER-ROADMAP.md` H4: how to move from "the new image does something different" to a reviewed product change with evidence. -Ghidra is the **static map**; green-eye is the **dynamic ground truth**; +Ghidra is the **static map**; risc-v-gsp-rm-debugger is the **dynamic ground truth**; recorded sessions are the **shared evidence**. Recipes use only the v0.1 surface, plus items explicitly labelled roadmap; see also docs/06-ACCURACY.md. @@ -41,16 +41,16 @@ hardware coupling a simulator cannot yet exercise. not proof of dead code. 4. Every claim carries its fidelity level (L0–L3, docs/06) and provenance. -## 3. The joint workflow: Ghidra, green-eye, sessions +## 3. The joint workflow: Ghidra, risc-v-gsp-rm-debugger, sessions ``` question > Ghidra (static): decompile, dispatcher tables, symbols - > green-eye (dynamic): same stimulus, hooks, watchpoints, trace + > risc-v-gsp-rm-debugger (dynamic): same stimulus, hooks, watchpoints, trace > sessions + hits TSV: greeneye compare -> triage -> evidence pack > open-iov-vfio change (with evidence) ``` -| Question | Ghidra answers | green-eye answers | Shared artifact | +| Question | Ghidra answers | risc-v-gsp-rm-debugger answers | Shared artifact | |---|---|---|---| | What is this code? | decompilation, call graph, xrefs | — | symbol DB (docs/05) | | Did it execute here? | hypothesis from xrefs | `bp_hit`/`watch_hit` events | `greeneye_hits.tsv` | @@ -73,22 +73,22 @@ emulation is touched. `addrnamesize`, which `symbols export --index` accepts: ```bash - ./greeneye.sh symbols export --index --bias 0 -o symbols-new.json - ./greeneye.sh symbols export --index --bias 0 -o symbols-old.json + ./risc-v-gsp-rm-debugger.sh symbols export --index --bias 0 -o symbols-new.json + ./risc-v-gsp-rm-debugger.sh symbols export --index --bias 0 -o symbols-old.json ``` 2. Probe each image for first-touch structure changes (docs/07 P1.2): ```bash - ./greeneye.sh probe --symbols symbols-old.json --record - ./greeneye.sh probe --symbols symbols-new.json --record + ./risc-v-gsp-rm-debugger.sh probe --symbols symbols-old.json --record + ./risc-v-gsp-rm-debugger.sh probe --symbols symbols-new.json --record ``` 3. Run the **same stimulus** against the re-hosted build of each version. Put it in a script so it is identical across runs: ```python - # run_stimulus.py -- ./greeneye.sh run run_stimulus.py --kernel + # run_stimulus.py -- ./risc-v-gsp-rm-debugger.sh run run_stimulus.py --kernel import greeneye as ge s = ge.launch(kernel="", record=True, name="stim") ctrl = s.symbols.lookup("") # demo: gsp_ctrl @@ -109,7 +109,7 @@ emulation is touched. delta and written-page delta: ```bash - ./greeneye.sh compare dumps/ dumps/ --symbols + ./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --symbols ``` 5. Triage with a decision table rather than intuition: @@ -134,7 +134,7 @@ with the capability model the emulation assumes. 1. Instrument the object ranges the service owns (kinds `w`, `r`, `a`): ```python - # capability_probe.py -- ./greeneye.sh run capability_probe.py --kernel + # capability_probe.py -- ./risc-v-gsp-rm-debugger.sh run capability_probe.py --kernel import greeneye as ge s = ge.launch(kernel="", record=True, name="caps") base = s.symbols.lookup("") @@ -155,7 +155,7 @@ with the capability model the emulation assumes. -serial file:/tmp/uart.log -bios none -kernel -S \ -gdb tcp:127.0.0.1:4444 \ -plugin qemu/greeneye-trace.so,path=/tmp/ge-trace.jsonl,start=0x80000000,end=0x81000000,exec=on - ./greeneye.sh attach --port 4444 --kernel --plugin + ./risc-v-gsp-rm-debugger.sh attach --port 4444 --kernel --plugin ``` `start=`/`end=` bound the trace, `exec=on` adds per-instruction records and @@ -183,7 +183,7 @@ roadmap R5; until then, bounded mutation over existing primitives is honest. 1. Mutate single fields deterministically and record each attempt: ```python - # mutate.py -- ./greeneye.sh run mutate.py --kernel + # mutate.py -- ./risc-v-gsp-rm-debugger.sh run mutate.py --kernel import greeneye as ge s = ge.launch(kernel="", record=True, name="mutate") ctrl = s.symbols.lookup("") @@ -205,12 +205,12 @@ roadmap R5; until then, bounded mutation over existing primitives is honest. ``` 3. Capture error paths with hooks/watchpoints on the dispatcher, fault - handlers and assert sites (symbol DB); `./greeneye.sh demo` records a trap. + handlers and assert sites (symbol DB); `./risc-v-gsp-rm-debugger.sh demo` records a trap. 4. Compare clean vs mutated sessions, keeping the mutation value in a `note` so the pack is self-describing: ```bash - ./greeneye.sh compare dumps/ dumps/ --symbols + ./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --symbols ``` Every corpus entry needs the firmware hash; never run mutation against @@ -225,7 +225,7 @@ timing or integrity state, or contains bogus code paths. require the comparison to be empty: ```bash - ./greeneye.sh compare dumps/ dumps/ --symbols + ./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --symbols ``` Any delta is a non-determinism candidate (scheduler, uninitialised read, time); record it. @@ -284,7 +284,7 @@ Goal: measure, not narrate. The contract is the M1–M6 table from docs/06: Procedure: (1) capture the reference on hardware/VFIO (docs/07 P4); (2) capture the simulator side with `record`/scripted `run`, hooks, watchpoints and -snapshots; (3) `./greeneye.sh compare dumps/ dumps/ +snapshots; (3) `./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --symbols`, with a script or plugin for per-control M2/M3 payload events; (4) repeat with the injected-service path to test the service boundary; (5) escalate — divergence that would change emulation behaviour must be @@ -293,7 +293,7 @@ reproduced physically; simulator-only divergence becomes a fidelity gap. ### 4.6 From observation to reimplementation The canonical accuracy loop (roadmap H4.5): (1) observe on hardware/VFIO; -(2) observe in green-eye (replayable session); (3) `compare` + M1–M6; +(2) observe in risc-v-gsp-rm-debugger (replayable session); (3) `compare` + M1–M6; (4) implement in `open-iov-vfio` with the session directories attached as evidence; (5) re-run the same stimulus and require the metric table to improve or stay equal. @@ -307,7 +307,7 @@ changed; decoy or low-fidelity observations never justify a product change. Start the live bridge and drive it from the decompiler: ```bash -./greeneye.sh ghidra --kernel --bridge-port 7000 +./risc-v-gsp-rm-debugger.sh ghidra --kernel --bridge-port 7000 $GHIDRA/support/analyzeHeadless -process -noanalysis \ -scriptPath debug/risc-v-gsp-rm-vm/ghidra \ -postScript GreenEyeControl.java 7000 0x @@ -320,13 +320,13 @@ the bridge (`watch_set`) without a Java wrapper: `send("watch_set", {...})`. Address conventions and bias pitfalls (docs/05 §1): -* Ghidra shows **program addresses**; green-eye resolves **runtime addresses**. +* Ghidra shows **program addresses**; risc-v-gsp-rm-debugger resolves **runtime addresses**. For firmware linked at its load address they coincide; otherwise supply `--bias` when building the symbol DB (`ExportForGreenEye.java` emits program addresses). * The classic mistake is passing a program address to `hook()` when the image base is non-zero; prefer `s.hook("")` and pass raw numbers through - `resolve`. `decompiled_index.tsv` carries both spaces; green-eye keeps the + `resolve`. `decompiled_index.tsv` carries both spaces; risc-v-gsp-rm-debugger keeps the program address in `symbol.extras["program_addr"]` for `bucket:line` mapping. * Wrapper-generated functions are re-laid-out between versions: transfer names, never raw wrapper addresses (docs/05 §6). -- cgit v1.2.3