Files
reverse-engineering-anything/docs/adr/evidence/target-identity.md
T
morluto 48b4bcd19a feat!: name process capture, Rizin and gdb Evidence by their target identities (#11568)
* feat(process)!: name process capture Evidence by its launched root process

The capture result now carries the launched root process in
`manifest.root_process`: its PID with the start identity that
`observeProcessStartIdentity` read for that PID at launch, bound to the
capture's run token. The harness reads that identity once and shares it
between finalization signalling and the manifest, so the read no longer
depends on a positive finalization interval.

Capture Evidence names the root as its subject,
`{ kind: "process", pid, start_time, executable_sha256 }`. A PID without
its start identity is not an identity, so an unread start identity leaves
the subject `unknown`/`not-observed`. When the caller selects PID
normalization, the raw PID and start identity are not recorded:
`root_process` is `withheld-by-caller` and the subject is
`unknown`/`withheld-by-caller`, a new unknown reason. Capture validation
requires the withheld state exactly when PID normalization is selected.

Refs #11417

BREAKING CHANGE: process capture Evidence IDs change: captures without PID
normalization name `{ kind: "process", pid, start_time, executable_sha256 }`
as their subject, and captures with PID normalization name
`{ kind: "unknown", reason: "withheld-by-caller" }`. Capture results
require `manifest.root_process`; captures without it are refused.
Recreate stored process capture Evidence.

* fix(process): join the launch identity read and let cancellation interrupt its wait

The root's launch identity read now runs for every capture and the
manifest awaits it. The read stays unsignalled, because finalization
signals after a cancellation still need the retained identity, so the
manifest's wait observes cancellation through `waitForAbortable` instead.
`finishProcessRun` and the startup-failure path join the read, so a
capture never returns while it is still running.

* feat(rizin)!: bind Rizin command Evidence to its session and launch file (#11570)

* feat(rizin)!: bind Rizin command Evidence to its session and launch file

Rizin command Evidence was subject-less (`unknown`/`not-observed`). A new
`session` target identity names the debugger session REA minted and the
target it launched: `{ kind: "session", session_kind, id, target }`, where
`target` is a file identity or an explicit unknown. The Evidence subject
validates the nested launch file with the format-owned subject
declaration.

`start_rizin_debug_session` hashes the launch file with the shared stable
file hasher before Rizin starts and binds the session to it (`format:
"file"`, no architecture or selection). Later debugger commands do not
rebind it. A descriptor whose close fails is retained in the startup
resource scope, like the inferior TTY lease, and fails the start, as does
cancellation; any other hash failure leaves the target
`unknown`/`not-observed` and records the reason as a limitation. The
"target identity is not established" limitation is replaced by the
binding's meaning.

Refs #11417

BREAKING CHANGE: `rizin_debug_command` Evidence IDs change: its subject is
`{ kind: "session", session_kind: "rizin", id: <session_id>, target }`
with `target` the launch file hashed at start (`{ kind: "file", sha256,
format: "file", architecture: null, selection: null }`) or
`{ kind: "unknown", reason: "not-observed" }`. Recreate stored Rizin
command Evidence.

* feat(gdb)!: name GDB command Evidence by its debugger session (#11572)

GDB startup and console Evidence was subject-less (`unknown`/`not-observed`).
It now names the session REA minted with the shared `session` identity:
`{ kind: "session", session_kind: "gdb", id, target }`. One projection,
`gdbSessionSubject`, replaces the six `unknownTarget("not-observed")` sites.

`start_gdb_session` launches no program file; programs are loaded or
attached by console commands that REA does not hash, so the session target
stays `unknown`/`not-observed`. REA does not infer a file from a PID or a
path. The existing limitation that the active inferior identity is not
established still applies.

Refs #11417

BREAKING CHANGE: `start_gdb_session` startup Evidence and `gdb_console`
Evidence IDs change: their subject is `{ kind: "session", session_kind:
"gdb", id: <session_id>, target: { kind: "unknown", reason: "not-observed" } }`.
Recreate stored GDB Evidence.

* fix(rizin): keep the launch file read failure when its close also fails

When hashing the launch file failed and closing its descriptor failed
too, the start error kept only the close failure; the retained lease
retries only the close, so the read failure was lost. The cleanup error
now carries it as `launch_file_hash_failure`.

The session-binding test now rewrites the launch file after spawn and
between two commands, and checks that both records keep the digest read
before launch.

* fix(process): keep the descriptor a failed launch identity read could not close

The launch identity read reduced every rejection to an unverified reason, so an inspection-owner failure carrying an unclosed descriptor was dropped and the capture could succeed without retaining it. The retained identity now keeps that owner's failure; startup cleanup and finishProcessRun pass it through the same secondary inspection-failure path as the sampler, which fails the capture and keeps the descriptor owned for cleanup retry.

* refactor(rizin): describe a launch-file hash failure through errorMessage

* test(rizin): create launch-file fixtures through createTestTempDirectory

* fix(process): keep the descriptor a finalization signal's identity check left open (#11603)

* fix(process): keep the descriptor a finalization signal's identity check left open

The root signaller now catches a delivery whose identity check fails through the inspection owner, records the attempt as unverified, and keeps the inspection failure. finishProcessRun joins every delivery (including one that outlasted the finalization grace) and retains those failures through the same secondary inspection-failure path as the launch identity read, so the capture fails with the descriptor still owned for a cleanup retry.

* test(process): release descriptor-retention captures when an assertion fails

Both descriptor-retention regressions register their resource-scope release before the capture starts and use the project deadline instead of a fixed 15 s timeout.
2026-11-16 08:06:35 +08:00

8.0 KiB

Evidence names its subject with one tagged target identity

Status

Accepted (2026-11-15). Implementation lands in slices: the first slice does not change Evidence IDs, and the slice that does is breaking (marked !, with recreate-observations migration notes) and ships with the next Evidence format revision.

Context

"The target" is defined three ways, with different fields:

Definition Fields Owner
Evidence subject identity digest.sha256, format, architecture evidenceSubjectIdentity in src/domain/evidence.ts
Snapshot target sha256, kind, architecture, format, plus entry_point (raw, DOL) or flash offsets (ESP) snapshotTarget in src/domain/analysisSnapshot.ts
Snapshot cache stage compare JSON.stringify of the snapshot target (key-order sensitive) AnalysisSnapshotCache.stage

The Evidence subject schema can only describe a hashed local file. Of 120 non-test createEvidence calls, 50 pass no subject and receive the generic limitation "Artifact identity is unavailable for this observation." (measured on main at c56fffcd75): application 29, contracts 7, gdb 6, server 3, domain 3, rizin 1, cutter 1. Every gdb, rizin, live-browser and process-capture record is subject-less, because a URL, a running process or a debugger session cannot be a subject. Comparison and workflow records are subject-less because they derive from several linked records.

Consequences today:

  • Two raw-binary observations of the same bytes at different entry points share an Evidence subject identity unless the operation echoes the entry point into parameters. The snapshot target keeps them apart.
  • Debugger, browser and process Evidence cannot be bound to what it observed. A rebuilt binary under the same path, or a different page at the same tool input, is indistinguishable in the record.
  • Consumers that compare targets each reimplement the comparison.

The Evidence format revision (src/domain/evidenceFormat.ts, #10861) gives Evidence one place to evolve. Phase 5 deferred two items to this decision: the target identity, and a per-record format marker. A standalone record (outside a bundle) does not declare its format today.

Decision

  1. One tagged identity. src/domain/targetIdentity.ts owns TargetIdentity, discriminated by kind:

    • file: sha256, format, architecture (nullable) and selection. selection holds the facts that select what was analysed in the bytes: the raw or DOL entry point, ESP flash and partition-table offsets, and a universal-binary slice. It is null when nothing is selected.
    • url: the URL with userinfo removed and its origin. Userinfo is a transport credential and is never part of an identity.
    • process: pid, start_time (the platform start identity the src/process/ identity primitives read for that PID), and executable_sha256 (nullable when the executable could not be read stably). A PID alone does not identify a process after exit or reuse, so the start time is required: a producer that did not read it names an unknown (not-observed) target rather than claiming an identity it does not have.
    • session: the session_kind (rizin, gdb; later kinds such as browser-scenario are added when a producer needs them), the session id REA minted, and the target the session was opened on: the launch file hashed when the session started, or unknown. Later debugger commands do not rebind the session.
    • unknown: a reason from a closed set: derived-from-linked-evidence (comparisons and workflows; their sources are already committed through evidence_links), not-observed, unsupported-subject, and withheld-by-caller (REA observed the identity and the caller chose not to record it, for example process capture PID normalization).

    Display facts (name, local_path) stay beside the identity and are not committed, as today.

  2. One key. targetIdentityKey(identity) is the RFC 8785 canonical digest of the identity. Evidence, analysis snapshots, caches and session binding compare targets only through it. evidenceSubjectIdentity, sameEvidenceSubjectTargetIdentity, snapshotTarget's field-by-field snapshotMatchesTarget and the JSON.stringify compare are deleted.

  3. Every record has a subject. createEvidence takes a TargetIdentity, not undefined. A producer that cannot name its subject passes unknown with a reason, so "no identity" is an explicit, reasoned value. MISSING_EVIDENCE_SUBJECT_LIMITATION is removed; the reason replaces it.

  4. Evidence format revision 2. The new subject changes the committed content of every Evidence ID, including file subjects (which gain kind and selection). It therefore ships as one breaking revision:

    • EVIDENCE_FORMAT_REVISION becomes 2 and its revision note names the subject change.
    • Every Evidence record carries evidence_format: 2, so a standalone record declares its format too. The marker is not part of the ID's committed content; it selects the reader, and admitEvidenceBundleFormat gains a per-record check with the same refusal.
    • Analysis snapshots embed Evidence and target identities, so snapshot files from revision 1 are refused at open.
  5. No migration of stored Evidence. An Evidence ID is a content commitment. Rewriting a revision 1 record under a new subject would claim an observation REA did not make. Revision 1 bundles, records and snapshots are refused with RECREATE_EVIDENCE_GUIDANCE (recreate the observations with the current release). The bundle reader already does this for pre-revision bundles.

Slices

  1. Introduce TargetIdentity and targetIdentityKey. Use them for snapshot and cache comparison (replacing the JSON.stringify compare), and let BinaryTargetResolver produce the file identity through the shared stable file hasher. No Evidence ID changes; not breaking.
  2. Evidence format revision 2 (breaking, !): the subject becomes TargetIdentity plus display facts; the per-record marker is added; the 50 subject-less sites pass an explicit identity: unknown (derived-from-linked-evidence) for comparisons and workflows, and the best identity each producer already holds for the rest.
  3. Producers gain real identities where they have the facts: gdb and rizin session identities bound to the opened file, live browser url, process capture process. Each is its own PR and changes only that producer's IDs, which is still within revision 2 if it lands before the release; otherwise it needs its own revision.

Consequences

  • Every Evidence ID changes once, in the release that ships revision 2. Callers that stored Evidence IDs or bundles must recreate them; the release notes carry the BREAKING CHANGE footer and this migration.
  • Debugger, browser and process Evidence can be bound to what it observed, and two observations that differ only in their selection (entry point, slice, flash offset) no longer share a subject.
  • Target comparison has one owner. Session registries can store the identity at open and revalidate it before each call (a follow-up, not part of this decision).
  • unknown keeps "the identity was not observed" visible as a fact with a reason, instead of an absent field with a generic limitation.
  • Revision 2 also takes the remaining fields that are optional only because older Evidence may omit them. Those that every producer writes become required in the same revision.