mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 13:12:26 +00:00
* 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.
272 lines
9.2 KiB
TypeScript
272 lines
9.2 KiB
TypeScript
import canonicalize from "canonicalize";
|
|
import { z } from "zod";
|
|
|
|
import type {
|
|
BinaryTarget,
|
|
UniversalMachOSliceIdentity,
|
|
} from "./binaryTargetTypes.js";
|
|
import { digestSchema } from "./digests.js";
|
|
import { rawBinaryEntryPointSchema } from "./rawBinary.js";
|
|
import { sha256Hex } from "../kernel/sha256Hex.js";
|
|
|
|
const flashOffsetSchema = z.number().int().min(0).max(0xffff_ffff).nullable();
|
|
const fatCpuSchema = z.number().int().min(0).max(0xffff_ffff).nullable();
|
|
|
|
/** Persisted facts inside a file's bytes that select what was analysed. */
|
|
export const fileTargetSelectionSchema = z.discriminatedUnion("kind", [
|
|
z.strictObject({
|
|
kind: z.literal("entry-point"),
|
|
entry_point: rawBinaryEntryPointSchema,
|
|
}),
|
|
z.strictObject({
|
|
kind: z.literal("esp-flash"),
|
|
flash_offset: flashOffsetSchema,
|
|
partition_table_offset: flashOffsetSchema,
|
|
}),
|
|
// One slice of a universal Mach-O. The FAT CPU declaration is null when
|
|
// target admission did not supply the validated FAT table.
|
|
z.strictObject({
|
|
kind: z.literal("universal-slice"),
|
|
offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
|
|
size: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
|
|
cpu_type: fatCpuSchema,
|
|
cpu_subtype: fatCpuSchema,
|
|
}),
|
|
]);
|
|
|
|
/**
|
|
* Facts inside a file's bytes that select what was analysed. Two observations
|
|
* of the same bytes with different selections are different targets.
|
|
*/
|
|
export type FileTargetSelection = z.infer<typeof fileTargetSelectionSchema>;
|
|
|
|
/**
|
|
* A hashed local file, path-free. Format and architecture are validated by
|
|
* the persistence format that embeds the identity (for Evidence, the
|
|
* format-owned subject declaration).
|
|
*/
|
|
export const fileTargetIdentitySchema = z.strictObject({
|
|
kind: z.literal("file"),
|
|
sha256: digestSchema,
|
|
format: z.string().min(1),
|
|
architecture: z.string().min(1).nullable(),
|
|
selection: fileTargetSelectionSchema.nullable(),
|
|
});
|
|
|
|
/** A hashed local file, path-free. */
|
|
export interface FileTargetIdentity {
|
|
readonly kind: "file";
|
|
readonly sha256: string;
|
|
readonly format: string;
|
|
readonly architecture: string | null;
|
|
readonly selection: FileTargetSelection | null;
|
|
}
|
|
|
|
/**
|
|
* Why an observation names no target: it derives from linked Evidence that
|
|
* already commits to its sources, the producer did not observe the target's
|
|
* identity, the target is not a kind REA can identify, or REA observed the
|
|
* identity and the caller chose not to record it (for example PID
|
|
* normalization).
|
|
*/
|
|
export const unknownTargetReasonSchema = z.enum([
|
|
"derived-from-linked-evidence",
|
|
"not-observed",
|
|
"unsupported-subject",
|
|
"withheld-by-caller",
|
|
]);
|
|
|
|
/** A target whose identity is unknown, with the reason it is unknown. */
|
|
export const unknownTargetIdentitySchema = z.strictObject({
|
|
kind: z.literal("unknown"),
|
|
reason: unknownTargetReasonSchema,
|
|
});
|
|
|
|
/** A target whose identity is unknown, with the reason it is unknown. */
|
|
export interface UnknownTargetIdentity {
|
|
readonly kind: "unknown";
|
|
readonly reason: z.infer<typeof unknownTargetReasonSchema>;
|
|
}
|
|
|
|
/** The explicit identity of a target REA did not identify. */
|
|
export const unknownTarget = (
|
|
reason: UnknownTargetIdentity["reason"],
|
|
): UnknownTargetIdentity => ({ kind: "unknown", reason });
|
|
|
|
/** The origin a URL serializes to, or null for an opaque origin. */
|
|
const urlOrigin = (parsed: URL): string | null =>
|
|
parsed.origin === "null" ? null : parsed.origin;
|
|
|
|
/**
|
|
* A live document's URL with userinfo removed, and its origin. Userinfo is a
|
|
* transport credential, so an identity that carries it is refused rather
|
|
* than committed.
|
|
*/
|
|
export const urlTargetIdentitySchema = z
|
|
.strictObject({
|
|
kind: z.literal("url"),
|
|
url: z.string().min(1),
|
|
origin: z.string().min(1).nullable(),
|
|
})
|
|
.superRefine((identity, context) => {
|
|
const parsed = URL.parse(identity.url);
|
|
if (parsed === null) {
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["url"],
|
|
message: "A URL target identity must be a parseable URL",
|
|
});
|
|
return;
|
|
}
|
|
if (parsed.username !== "" || parsed.password !== "")
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["url"],
|
|
message: "A URL target identity must not carry userinfo",
|
|
});
|
|
if (urlOrigin(parsed) !== identity.origin)
|
|
context.addIssue({
|
|
code: "custom",
|
|
path: ["origin"],
|
|
message: "A URL target identity's origin must be its URL's origin",
|
|
});
|
|
});
|
|
|
|
/** A live document's URL with userinfo removed, and its origin. */
|
|
export interface UrlTargetIdentity {
|
|
readonly kind: "url";
|
|
readonly url: string;
|
|
readonly origin: string | null;
|
|
}
|
|
|
|
/**
|
|
* A live process named by its PID and the start identity the `src/process`
|
|
* identity primitives read for that PID. A PID alone does not identify a
|
|
* process after exit or reuse, so the start identity is required. The
|
|
* executable digest is null when the executable could not be read stably
|
|
* across launch.
|
|
*/
|
|
export const processTargetIdentitySchema = z.strictObject({
|
|
kind: z.literal("process"),
|
|
pid: z.int().positive(),
|
|
start_time: z.string().min(1),
|
|
executable_sha256: digestSchema.nullable(),
|
|
});
|
|
|
|
/** A live process named by its PID and start identity. */
|
|
export interface ProcessTargetIdentity {
|
|
readonly kind: "process";
|
|
readonly pid: number;
|
|
/** Platform start identity from `src/process`; opaque, compared only for equality. */
|
|
readonly start_time: string;
|
|
readonly executable_sha256: string | null;
|
|
}
|
|
|
|
/** Debugger sessions REA mints and can bind to a launch target. */
|
|
export const debuggerSessionKindSchema = z.enum(["rizin", "gdb"]);
|
|
|
|
/**
|
|
* A debugger session REA minted, bound to the target it launched: the launch
|
|
* file hashed when the session started, or an explicit unknown when REA did
|
|
* not observe it (an attach, or a launch file that could not be hashed).
|
|
* Later debugger commands do not rebind the session.
|
|
*/
|
|
export const sessionTargetIdentitySchema = z.strictObject({
|
|
kind: z.literal("session"),
|
|
session_kind: debuggerSessionKindSchema,
|
|
id: z.string().min(1),
|
|
target: z.union([fileTargetIdentitySchema, unknownTargetIdentitySchema]),
|
|
});
|
|
|
|
/** A debugger session REA minted, bound to the target it launched. */
|
|
export interface SessionTargetIdentity {
|
|
readonly kind: "session";
|
|
readonly session_kind: z.infer<typeof debuggerSessionKindSchema>;
|
|
readonly id: string;
|
|
readonly target: FileTargetIdentity | UnknownTargetIdentity;
|
|
}
|
|
|
|
/**
|
|
* What an observation or cache entry is about. Tagged by `kind`; see
|
|
* docs/adr/evidence/target-identity.md for the kinds later slices add.
|
|
*/
|
|
export type TargetIdentity =
|
|
| FileTargetIdentity
|
|
| UrlTargetIdentity
|
|
| ProcessTargetIdentity
|
|
| SessionTargetIdentity
|
|
| UnknownTargetIdentity;
|
|
|
|
/** A target identity that names no file, and so has no file display facts. */
|
|
export type NonFileTargetIdentity = Exclude<TargetIdentity, FileTargetIdentity>;
|
|
|
|
/**
|
|
* The identities without a nested target that a subject without file display
|
|
* facts can commit to. A session identity nests its target, so a persistence
|
|
* format validates it with its own file declaration.
|
|
*/
|
|
export const nonFileTargetIdentitySchema = z.union([
|
|
unknownTargetIdentitySchema,
|
|
urlTargetIdentitySchema,
|
|
processTargetIdentitySchema,
|
|
]);
|
|
|
|
/** The universal Mach-O slice a target selects, with its FAT CPU declaration when admitted. */
|
|
const universalSliceSelection = (
|
|
slice: { readonly offset: number; readonly size: number },
|
|
declarations: readonly UniversalMachOSliceIdentity[] | undefined,
|
|
): FileTargetSelection => {
|
|
const declared = declarations?.find(
|
|
(candidate) =>
|
|
candidate.offset === slice.offset && candidate.size === slice.size,
|
|
);
|
|
return {
|
|
kind: "universal-slice",
|
|
offset: slice.offset,
|
|
size: slice.size,
|
|
cpu_type: declared?.cpuType ?? null,
|
|
cpu_subtype: declared?.cpuSubtype ?? null,
|
|
};
|
|
};
|
|
|
|
/** The selection an open binary target makes inside its bytes, if any. */
|
|
export const binaryTargetSelection = (
|
|
target: BinaryTarget,
|
|
): FileTargetSelection | null =>
|
|
target.format === "raw-binary" || target.format === "gamecube-dol"
|
|
? { kind: "entry-point", entry_point: target.entryPoint }
|
|
: target.format === "esp-flash-image"
|
|
? {
|
|
kind: "esp-flash",
|
|
flash_offset: target.espFlash.flashOffset,
|
|
partition_table_offset: target.espFlash.partitionTableOffset,
|
|
}
|
|
: target.format === "mach-o-universal"
|
|
? universalSliceSelection(target.universalSlice, target.universalSlices)
|
|
: null;
|
|
|
|
/** The one projection of an open binary target into its target identity. */
|
|
export const binaryTargetIdentity = (
|
|
target: BinaryTarget,
|
|
): FileTargetIdentity => ({
|
|
kind: "file",
|
|
sha256: target.sha256,
|
|
format: target.format,
|
|
architecture: target.architecture ?? null,
|
|
selection: binaryTargetSelection(target),
|
|
});
|
|
|
|
/** The only comparison of two target identities: an RFC 8785 canonical digest. */
|
|
export const targetIdentityKey = (identity: TargetIdentity): string => {
|
|
const encoded = canonicalize(identity);
|
|
if (encoded === undefined)
|
|
throw new TypeError("RFC 8785 canonicalization rejected a target identity");
|
|
return `target_${sha256Hex(encoded)}`;
|
|
};
|
|
|
|
/** Whether two identities name the same target. */
|
|
export const sameTargetIdentity = (
|
|
left: TargetIdentity,
|
|
right: TargetIdentity,
|
|
): boolean => targetIdentityKey(left) === targetIdentityKey(right);
|