1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
# 08 — green-eye roadmap
> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status.
> This is the **near-term, committed** roadmap (rungs R0–R7 below). The
> **long-term program** — adversarial firmware navigation, adjacent
> microcontrollers, a non-QEMU custom simulator, a Verilog soft-processor
> environment and the agentic platform — lives in
> [`../GREEN-EYE-ROADMAP.md`](../GREEN-EYE-ROADMAP.md).
> Items here are **not** v0.1. Do not start them ad hoc; each has a gate.
## R0. Product principles
* green-eye stays a **development tool**: no shipped dependencies, no guest
presence, no kernel-module coupling.
* Fidelity improvements must be *measurable* (metrics table in 06) and must
not slow the fast path (demo + probe) below usefulness.
* Every new backend must satisfy the same `Session` contract so scripts,
probes, plugins and recordings survive.
## R1. Platform device model (raise L3)
**Why:** a bare `qemu virt` cannot boot the real fwimage; the probe shows the
first unmapped access and stops.
**Scope:** model the minimum GSP environment:
falcon windows (FALCON/CSB/TRANSCOM registers), WPR2/FWSEC state registers
with read-back semantics, PTIMER, PMU/SEC2 mailbox stubs, FB DMA/IOMMU
address translation for the firmware's DMA descriptors, and interrupt
routing. QEMU `qemu-system-riscv64` with a custom device (`-device`) is the
preferred vehicle; TCG plugins provide the observation points.
**Gate:** R1 starts only when a portability task (P2/P3) or an accuracy
measurement (P1.6) requires booting real firmware in-simulator. Until then,
use the probe + rehosted uproc paths.
**Exit criteria:** `greeneye probe <fwimage>` reaches a stable address and
reports "waiting for host message" rather than a fault; the first host↔GSP
RPC records are captured in a session; M3 ordering can be measured against
the physical backend.
## R2. Custom simulator (explicitly requested; not first version)
**Why:** QEMU is an excellent execution engine but a poor *workflow* engine
for this project: no in-process API, RSP serialisation for every access,
limited snapshotting, and a device model designed for whole boards rather
than firmware servers. A custom simulator can be deterministic, replayable
and scriptable at native speed.
**Shape (to build later, not now):**
* an RV64IMAC interpreter/JIT with a **pluggable memory map** (RAM, MMIO
hooks, DMA windows) and a **deterministic scheduler** (no realtime claim);
* native `Session` integration — replace the RSP transport with a
`Backend` interface, keep hooks/watchpoints/memory/recording identical;
* first-class **snapshot/restore** of full machine state (time-travel
debugging, branch-flip experiments);
* an **event bus** feeding the existing `events.jsonl` schema;
* a **stub DSL** for device registers (read/write scripts with state), so a
new GPU generation is configuration, matching the project's portability
direction.
**Candidates to evaluate at that time:** extending QEMU TCG with a thin
in-process backdoor, `libriscv`, `rv8`, or a from-scratch interpreter.
Realtime is explicitly *not* a requirement; determinism and introspection are.
**Gate:** R1 must have stabilised the device semantics (otherwise the custom
simulator inherits an unvalidated model). Estimated multi-week work; schedule
only after the guest-bridge work (PLAN B) no longer depends on it.
## R3. MCP server plugin
**Why:** expose green-eye sessions to AI harnesses and other agents under the
plugin model the user requested.
**Shape:** a plugin (`plugins/mcp_server.py` when built) that wraps the
session/analysis API as MCP tools: `list_sessions`, `open_session`,
`symbols_resolve`, `set_breakpoint`, `run`, `memory_read`, `memory_hexdump`,
`snapshot`, `compare_sessions`, `export_hits`. Transport local stdio first;
no network exposure by default. The plugin depends on an MCP library only at
plugin load time; the core stays stdlib-only.
**Gate:** v0.1 must be stable (acceptance list in 00) and the session format
frozen. Explicitly deferred by the owner; do not add MCP code before then.
## R4. Full-memory trace (TCG plugin integration)
The optional `qemu/greeneye_trace.c` plugin records instruction execution and
memory accesses. Roadmap: build it against the vendored QEMU headers, stream
its JSONL into the session format as `exec`/`access` events, and teach
`analyze` to render coverage/heatmaps and written-page timelines. This is the
"complete map" upgrade from stop-based observation to full access tracing.
**Gate:** available once the QEMU plugin headers are vendored (or the build
environment provides them). Does not block v0.1 — watchpoint recording plus
step traces already cover the common cases.
## R5. Fuzzing and mutation harness
Use AFL++ QEMU mode (or a custom mutator) against the rehosted firmware's
RPC input surface, with green-eye recording crash/trap paths and symbol
annotation. Requires R1/R2 for stable input plumbing. Output: a corpus of
malformed controls and the firmware's error paths, feeding the emulation's
fail-closed rules (project security hygiene).
## R6. Multi-version orchestration
Scripts that, given a set of firmware images and device profiles, run the
probe + rehost + compare pipeline for the whole matrix and emit the M1–M6
tables. This automates `07-PORTABILITY-PLAYBOOKS` P1–P3.
## R7. Ghidra two-way console
A Ghidra script/plugin that talks to a live green-eye session (via the CLI or
a local socket) to toggle breakpoints/watchpoints from the decompiler and to
highlight hit addresses. Until then, the hit-TSV + `MarkGreenEyeHits.java`
flow is the supported path.
## Not on the green-eye roadmap
* Graphics/display emulation, Windows guest internals, multi-tenant policy —
these belong to the main project roadmap, not to this analysis tool.
* Replacing Ghidra: green-eye is the dynamic complement, never a decompiler.
|
