mirror of
https://github.com/morluto/rea.git
synced 2026-10-26 17:35:11 +00:00
781760a195
* feat(apple): inspect IPS crash reports Add inspect_apple_ips for caller-selected Apple .ips files. Parse the first-line metadata object and, when bug_type is the string 309, the crash body: process identity, exception and termination facts, threads, usedImages, lossless integer registers, and documented classification rules. Other bug types including 288 stackshots return no crash result. Opened Mach-O and dSYM UUID joins remain unobserved. Related to #4297 * fix(apple): keep IPS register literals exact Use the arm64e fixture integer that matches 0x8527000193ed4944 instead of an IEEE-754-rounded decimal, and count the lossless JSON example length from the source text. * fix(apple): budget IPS parsing and keep typed presence Parse the IPS metadata and crash body through a projection of the documented members. Members the report does not interpret are syntax-checked without being materialized, and thread, frame, image and the new max_registers budgets run before each row is parsed, so a large selected file fails with a typed resource error instead of first expanding every row. Fixed allowances bound JSON nesting, unlisted key names and termination reasons. Present values whose JSON type differs from the documented one are no longer read as absence: they are listed in coverage.type_mismatches and coverage becomes partial, including wrong-type or missing threads and usedImages collections. osVersion keeps the producer dictionary or the string form. Frame roles follow physical frame depth, so the top frame of a non-faulting thread is current_instruction and inlined rows share the following frame's role. SIGKILL classes compare the canonical hex once, so 0xdeadd0cc no longer matches dead10cc. Invalid UTF-8 is refused instead of being replaced, and JSON strings are decoded by copying unescaped spans. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ra7LM2NyQ7DumdssxbUq5g * fix(apple): bound integer text expansion and reconcile coverage * refactor(apple): retain image metadata at its owning row * refactor(apple): validate row capacity through reconciled coverage * test(apple): verify resource recovery at the public error boundary * docs(apple): record complete IPS task and corpus measurements * docs(apple): record integrated checks and stdio corpus evidence * docs(apple): record PE integration and baseline cleanup controls * fix(native): bound IPS string decoding and preserve invalid identities * refactor(native): use exact optional IPS source evidence * docs(native): verify IPS escape capacity and complete-task costs * test(native): verify IPS through production stdio MCP * style(tests): format IPS advertised schema bindings * fix(native): preserve unresolved IPS references and recorded frame semantics * docs(native): record IPS reference review evidence * fix(apple-ips): enforce JSON and report consistency * docs(apple-ips): record final consistency verification --------- Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
153 lines
9.6 KiB
Markdown
153 lines
9.6 KiB
Markdown
# Recorded crash evidence
|
|
|
|
`inspect_recorded_crash` / `rea inspect-recorded-crash` inspect a caller-selected
|
|
Linux ELF64 little-endian core independently of an active binary target. Apple
|
|
`.ips` crash reports use the separate [Apple IPS](apple-ips.md) workflow. Two
|
|
architecture profiles are interpreted, x86-64 and AArch64; each binds registers
|
|
to its own `NT_PRSTATUS` layout, and any other `e_machine` is refused as
|
|
`unsupported_target` before note interpretation.
|
|
|
|
```sh
|
|
export REA_PWNTOOLS_PYTHON=/absolute/existing/venv/bin/python
|
|
rea inspect-recorded-crash ./crash.core --json
|
|
```
|
|
|
|
The selected Python needs unchanged pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2.
|
|
REA does not install these dependencies. ELFFile/its original ELF structures and
|
|
pwntools' original Linux amd64 and aarch64 ctypes provide parsing and ABI layout.
|
|
The adapter adds bounds, representation preservation and lifecycle ownership.
|
|
The initial Linux note profile accepts System V/unspecified and GNU/Linux OSABI
|
|
with ABI version zero. Other declared ABIs return `unsupported_target` before
|
|
note interpretation; an unspecified OSABI alone does not prove OS origin.
|
|
|
|
## Recorded observations
|
|
|
|
- Artifact path, original SHA-256 and size; full normalized result and Evidence
|
|
are inline through CLI and MCP.
|
|
- Original program headers and recorded segment file/memory ranges. Undumped
|
|
memory and current executable/library identity remain unknown.
|
|
- Program headers and notes retain their original numeric `type_id` separately
|
|
from the decoder's `type` label. Source binding and semantic decisions use the
|
|
numeric identity; an architecture-specific display name does not establish
|
|
support for that segment's payload semantics.
|
|
Header `type` names follow the pinned parser's machine-specific projection:
|
|
`PT_AARCH64_ARCHEXT` and `PT_AARCH64_UNWIND` denote `0x70000000` and
|
|
`0x70000001` only for AArch64. The same codes on x86-64 remain numeric, as
|
|
does AArch64's `0x70000002` in pyelftools 0.33. These display projections
|
|
are checked against the architecture and source-bound `type_id`; they do not
|
|
decode architecture compatibility, unwind or MTE payloads.
|
|
- Every note's original identity, owner/descriptor bytes and source ranges,
|
|
including unfamiliar owners and note kinds.
|
|
CORE symbolic note labels apply only to the exact `CORE\0` owner. Other
|
|
owners keep numeric types, so GNU/type 3 remains opaque instead of acquiring
|
|
CORE process-info semantics, and a GNU-owned numeric NT_FILE collision does
|
|
not acquire debugger mapping authority.
|
|
- Every exact Linux CORE PRSTATUS note as a separate recorded thread, with
|
|
historical PID, signal and lossless uint64 registers bound to source bytes.
|
|
Each supported note has exactly one interpretation; each thread contains the
|
|
complete ABI register set for its architecture (27 registers for amd64,
|
|
34 for AArch64), with names bound to their original ABI offsets.
|
|
Physical note ranges cannot overlap or leave segment gaps. ELF and note headers
|
|
are independently bound to the snapshot, including extended program counts.
|
|
- Signed SIGINFO number/code/errno. Initially only SIGSEGV codes 1/2 establish the
|
|
fault-address union; other variants retain raw bytes and unknown meaning.
|
|
|
|
Historical PIDs are metadata. They never select a live process or authorize
|
|
attach/control. Missing notes do not establish absence at the crash; note
|
|
interpretation completeness and signal-thread association remain unknown.
|
|
|
|
## Optional debugger mapping context
|
|
|
|
```sh
|
|
export REA_PWNDBG_GDB=/absolute/existing/gdb
|
|
export REA_PWNDBG_GDBINIT=/absolute/unchanged/pwndbg/gdbinit.py
|
|
export REA_PWNDBG_VENV_PATH=/absolute/existing/pwndbg-venv
|
|
rea inspect-recorded-crash ./crash.core --debugger-context --json
|
|
```
|
|
|
|
MCP uses `{ "path": "/artifacts/crash.core", "include_debugger_context": true }`.
|
|
Omitting this meaningful facet requests only recorded evidence. Requested but
|
|
unavailable context returns an actionable failure; it never silently claims
|
|
debugger coverage. GDB defaults to `/usr/bin/gdb`; the plugin and virtual
|
|
environment require explicit absolute paths. Initial local verification covers
|
|
Linux x64, GDB 13.1 and unchanged pwndbg 2026.09.15.
|
|
|
|
The outer provider owns both processes and one stable core snapshot. An owned
|
|
Python launcher lowers inherited soft limits before replacing itself with GDB.
|
|
GDB starts without initfiles, auto-load, debuginfod or automatic shared-library
|
|
loading. Owned empty library search paths and caches are used, with plugin
|
|
updates disabled. Debug-file lookup is also restricted to the owned empty
|
|
search directory. GDB 16 can otherwise locate the recorded executable independently
|
|
of these settings. While opening the core, fixed package code temporarily selects
|
|
`/proc/self/exe` (the already running debugger) with `exec-file`, without loading
|
|
symbols or running an inferior. This occupies GDB's executable slot and prevents
|
|
its automatic executable discovery. The validated decoder profile selects the
|
|
core architecture explicitly, so the placeholder cannot select it instead. The
|
|
bridge discards that selection with `file` before querying mapping candidates,
|
|
and verifies the core connection and absence of a main symbol file. Before launching GDB, the provider also checks
|
|
source-bound `NT_FILE` descriptors: mapping names must be absolute Unix paths
|
|
without dot segments. Relative names bypass GDB's sysroot, and traversal can
|
|
escape it. Unresolved or unsafe mapping coverage refuses debugger enrichment
|
|
while retaining the basic decoded observation and original bytes. No caller GDB
|
|
command language is exposed. The exact observed GDB/plugin version strings are
|
|
retained.
|
|
|
|
Mapping names are producer display metadata, with unknown current file identity.
|
|
Map permissions are derived from reported flags; zero/unfamiliar flags leave
|
|
permissions unknown. These maps do not establish page contents or an executable
|
|
match. Core source bytes remain available independently of this enrichment.
|
|
An Evidence envelope containing these maps is `derived`; inspection without
|
|
debugger context is `observed`.
|
|
|
|
## Bounds and verification
|
|
|
|
Initial Linux x64 limits: 32 MiB input, 64 MiB decoder reply, 1 MiB diagnostics per
|
|
stage, 30 seconds owned wall deadline per stage, 3 GiB address-space soft ceiling
|
|
and 30 seconds CPU soft ceiling. `REA_PWNTOOLS_MAX_INPUT_BYTES` raises the input
|
|
bound alone, up to 1 GiB, and returns `provider_unavailable` when it is not a
|
|
decimal integer in range; the reply, diagnostic and deadline bounds stay fixed, so a
|
|
large core that outruns them still fails explicitly instead of partially. Tighter
|
|
inherited soft/hard limits are retained; hard limits are not raised. Complete
|
|
oversized results fail explicitly. These process limits do not constitute a sandbox
|
|
for caller-supplied engine code.
|
|
|
|
Resource exit statuses need matching private failure-branch markers. Unmarked
|
|
launcher failures retain their actual status/output and unknown resource cause.
|
|
Cancellation, output truncation and independent owned cleanup remain explicit.
|
|
|
|
`npm run verify:recorded:crash` uses source-owned fixtures and caller-supplied
|
|
GDB/Python/pwndbg/strace. Fixture generation explicitly launches its owned test
|
|
program; subsequent inspection only reads the resulting core. Real acceptance
|
|
checks recorded threads, high registers, missing/malformed notes, opaque owners,
|
|
CLI/MCP parity, optional debugger context and historical PID collision with an
|
|
owned live sentinel. Authored AArch64 auxiliary-header and numeric-unknown
|
|
carriers also pass through the configured decoder and both public adapters;
|
|
they are metadata fixtures, rather than captured AArch64 crashes. Their expected
|
|
names follow [pyelftools 0.33's enums](https://github.com/eliben/pyelftools/blob/v0.33/elftools/elf/enums.py#L431-L435)
|
|
and [machine-specific selection](https://github.com/eliben/pyelftools/blob/v0.33/elftools/elf/structs.py#L179-L184).
|
|
The [AArch64 ELF ABI](https://github.com/ARM-software/abi-aa/blob/2025Q1/aaelf64/aaelf64.rst#program-header)
|
|
defines their raw codes. An observed Node thread group must launch the exact
|
|
ownership `ps` inventory before it can read that live process's `stat` or `status` for native
|
|
identity/UID facts. Only traced `CLONE_THREAD` members share this allowance;
|
|
exec-replaced threads, ordinary children, debugger and decoder processes cannot
|
|
use it. The purpose of stat/status reads within the same Node thread group
|
|
cannot be distinguished by strace. A second recording uses a valid
|
|
historical PID above the host's assignable PID range and rejects resolved lookups,
|
|
including Node `stat`/`status` reads, to detect historical-PID-driven access separately
|
|
from live inventory. Descriptor paths come from strace's `-yy` decoding; exact
|
|
PID-directory opens and relative accesses through those handles are rejected.
|
|
Failed FD-relative pathname attempts are checked across syscall variants.
|
|
Legacy relative pathname calls without dirfd/cwd evidence and symlink aliases
|
|
remain unverified; the verification report declares these gaps rather than
|
|
establishing their absence.
|
|
One syscall/selector contract supplies trace selection, target interpretation
|
|
and the report's explicit coverage catalog. Unlisted PID-directed syscalls remain
|
|
unverified. The catalog includes PID-directed resource
|
|
limits, scheduling, priority, process metadata, signals and pidfd controls.
|
|
Self, group and UID selectors retain their syscall-defined meanings; unresolved
|
|
targets cannot qualify. Coverage is reported once for all CLI/MCP traces and
|
|
does not establish containment of every possible kernel interaction.
|
|
The syscall trace also rejects access to the still-present
|
|
source executable. The CI workflow defines Ubuntu 24.04 and Debian 13 (GDB 16)
|
|
container lanes. Original inputs and host configuration remain unchanged.
|