Skip to content

feat(recorded-crash): decode AArch64 core register notes - #2505

Merged
morluto merged 6 commits into
morluto:mainfrom
NIU-123370:feat/recorded-crash-aarch64
Oct 13, 2026
Merged

morluto merged 6 commits into
morluto:mainfrom
NIU-123370:feat/recorded-crash-aarch64

Conversation

@NIU-123370

@NIU-123370 NIU-123370 commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

inspect_recorded_crash only ever admitted ELF64 x86-64 cores: the bridge refused every other e_machine and the domain schema pinned architecture to a single literal, so a legitimately recorded Linux AArch64 crash could not be inspected at all.

This adds the AArch64 profile from unchanged pwntools 4.15.0 structures — no locally re-declared ABI — and turns the previously amd64-only constants into one owned profile table.

Fixes #2353

ABI facts, measured not assumed

Read directly out of pwnlib/elf/datatypes.py from the official pwntools-4.15.0 wheel via ctypes:

Profile e_machine elf_prstatus size pr_reg offset pr_cursig / pr_pid registers
x86-64 (existing) 62 336 (0x150) 112 12 / 32 27 × c_uint64
AArch64 (new) 183 392 (0x188) 112 12 / 32 34 × c_uint64 (x0…x30, sp, pc, pstate)

The AArch64 register order is user_regs_struct_aarch64._fields_ order, which is the order the bridge already uses to emit registers, so the domain list and the bridge cannot drift silently. The amd64 list in the domain file was verified the same way (it matches _fields_ exactly), which is also what proves the existing profile was not accidentally reinterpreted here.

What changed

  • src/domain/native/recordedCrash.ts — one owned profile table RECORDED_LINUX_CORE_PROFILES (machine id, register order, register width, register offset, PRSTATUS size) plus RECORDED_LINUX_CORE_ARCHITECTURES. architecture becomes z.enum over that list, and thread validation now checks each register name, count and width against the reported architecture's profile instead of a hardcoded amd64 list.
  • bridge/pwntools/recorded_crash_impl.py — CORE_MACHINES = (62, 183); the profile selects elf_prstatus_aarch64 / user_regs_struct_aarch64 and the architecture label. Truncation messages name the selected profile. The unsupported-target refusal now reports the observed e_machine instead of only saying "requires x86-64".
  • src/native/pwntools/RecordedCrashSourceBindings.ts — register source offsets and the minimum descriptor length now come from the same profile table, so a 34-register/392-byte AArch64 thread is bound slot by slot exactly like amd64's 27/336.
  • tests/fixtures/binaryDiagnostics/recordedCrash.ts — the source-owned fixtures derive note, owner and descriptor ranges from the profile (identical bytes to today for x86-64: 0x80/0x8c/0x94, 0x164, 0x150) and now stamp the matching e_machine.
  • docs/recorded-crashes.md — states both profiles and that any other machine is refused before note interpretation.

Verification

Real decode, run locally. I assembled the decoder's actual dependencies and ran the repo's recorded_crash_impl.py unchanged against crafted cores:

  • AArch64 core: architecture = aarch64-little-endian, 34 registers named x0…x30, sp, pc, pstate, every reported register offset equal to descriptor + 112 + index*8, all values round-tripped, PID and cursor signal recovered from pr_pid@32 / pr_cursig@12, and the SIGSEGV fault address decoded from NT_SIGINFO.
  • x86-64 core: unchanged behaviour — 27 registers, x86_64-little-endian, same offsets.
  • 391-byte AArch64 descriptor → format: Linux AArch64 NT_PRSTATUS descriptor is truncated.
  • e_machine = 243 (RISC-V) → unsupported-target naming the observed machine.

Honest limits of that harness: pyelftools 0.33 is the real package and pwnlib/elf/datatypes.py is the verbatim file from the official 4.15.0 wheel, but unicorn 2.1.2 is satisfied by a metadata stub because no macOS arm64 wheel builds here — the recorded-crash path never imports unicorn, only the version preflight reads it. The harness lives in /tmp and is not part of the commit. If you want it in-repo I will add it as a unittest that skips when pwntools 4.15.0 is not importable, so test:python stays green without the dependency.

TypeScript. New src/native/pwntools/RecordedCrashSourceBindings.test.ts (7 cases) binds every register for both profiles, pins each profile's numbers against the ABI table above rather than only using them consistently, asserts the crafted core's e_machine equals its profile's machine, and rejects: a register bound one slot off, a descriptor shorter than the profile size, an amd64 name inside an AArch64 window, and a reported PID that differs from the source bytes. src/domain/native/recordedCrash.test.ts gains 6 cases: the full AArch64 window accepted, its note ranges inside the segment, and rejection of an amd64 name, the amd64 count, a 4-byte register source, and an architecture outside the profiles.

Gate Result
vitest --project domain --project services --project adapters 388 files / 5044 tests passed, 7 skipped
my four touched suites (domain, adapters pwntools, services binaryDiagnostics, boundary binaryDiagnostics) 67 passed, 71 skipped (Linux/x64-only lanes)
tsc --noEmit -p tsconfig.json clean
oxfmt --check clean
npx knip clean
oxlint 0 errors; the 2 warnings are the same on untouched origin/main for the same files

The provider suite for this lane (tests/boundary/binaryDiagnostics/recordedCrashProvider.test.ts, 34 cases) is runIf(linux && x64) and the adapter itself refuses non-Linux hosts, so to check my fixture rewrite I temporarily bypassed both gates, ran all 34 green, then reverted both. The committed diff contains no bypass; git diff for that test file is empty.

npx vitest --project boundary on this machine shows 8 failures in four files (setupSkill, two inspector/javascriptRuntime*, nativeDmgArtifactReader). None of them read recorded-crash code, and on untouched origin/main at the same commit the same four files fail 14 cases — after normalizing names, my failure set is a strict subset with zero cases unique to this diff. So these are macOS host/pre-existing failures, not regressions here.

Mutation arms (each run, each killed)

Arm Killed by
bridge machine not in CORE_MACHINES → machine != 62 harness AArch64 decode refused
bridge truncation check forced to the amd64 structure harness accepted a 391-byte AArch64 descriptor
profile prstatusBytes: 392 → 336 4 binding/domain cases
profile registerOffset: 112 → 120 the pinned ABI numbers case
drop AArch64 from the architecture enum 2 domain cases
validation ignores the reported architecture (always amd64) 2 AArch64 domain cases

Deliberately not in this PR

Collision surface

I indexed the changed files of all 202 open PRs earlier in this session: all seven files this PR touches were free of any in-flight PR. That index is a snapshot, so a rebase before merge is still worth doing; the branch is currently rebased onto c74142e6 with one commit.

Base: c74142e6. Head: 3 commits, 12 files, +529 −88. Trunk has moved 58 commits since that base and git log HEAD..origin/main -- <these twelve paths> returns 0 hits (positive control: the same command finds 3 hits for a file trunk did change), so nothing has been rewritten under this branch. The round-1 files (RecordedCrashStructureBindings.ts, RecordedCrashService.ts and its test) were not in the 202-PR index above, so that snapshot does not cover them; a re-scan or rebase before merge is still worth doing.

Review round 1 (Greptile P1 ×2)

Both findings were correct: the AArch64 profile reached the bridge and the domain, but two downstream consumers still pinned amd64, so nothing actually arrived. Fixed in the second commit.

site was now
src/native/pwntools/RecordedCrashStructureBindings.ts header.readUInt16LE(18) !== 62, so PwntoolsRecordedCrashProvider refused an AArch64 core before the widened register checks ran compares the header against RECORDED_LINUX_CORE_PROFILES[report.architecture].machine
src/application/binaryDiagnostics/RecordedCrashService.ts literal architecture: "x86_64" on every created Evidence RECORDED_LINUX_CORE_PROFILES[value.architecture].evidenceArchitecture
src/domain/native/recordedCrash.ts profile had no Evidence CPU family profile owns evidenceArchitecture: BinaryArchitecture (x86_64 / arm64)

New cases: each profile is admitted by its own e_machine and rejected when the header carries the other profile's machine; created Evidence is pinned per profile; and success-aarch64 runs an AArch64 core through the full provider pipeline as a row of the existing scenario table.

Mutation arms (each run, then reverted from backup and cmp-verified)

arm mutation result
A machine hard-coded back to 62 structure bindings 2 failed / 6 passed
B accept 62 or 183 regardless of the reported profile 2 failed / 6 passed — the guard is bound to the report, not merely widened
C service literal back to "x86_64" service 1 failed / 11 passed
D profile maps AArch64 to arm service 1 failed / 11 passed
E arm A with the Linux lane opened (below) success-aarch64 fails with Reported core structure differs from its original ELF/note headers.

How the host-gated provider case was executed here

tests/boundary/binaryDiagnostics/recordedCrashProvider.test.ts is .runIf(process.platform === "linux" && process.arch === "x64") and PwntoolsDecoder refuses any other host, so all 35 of its cases skip on macOS. To run them I temporarily (1) turned that host check into if (false) and (2) set the test file's host constant to true, ran the file — 35 passed / 0 failed — then restored both files from backup and re-verified with cmp plus grep -c = 0 for each marker. The bridge is stubbed by the test's own launcher, so no pwntools/Python executed in that experiment; the Linux CI lane still covers the real decode.

Local gates for this commit

tsc --noEmit clean. oxfmt --check clean on all six changed files. oxlint on those six: 0 errors, 4 warnings — the same four warnings as at 6055dc26, verified by linting both trees, so no new warning is introduced. Platform-independent selection: structure bindings 8, RecordedCrashService 12, domain 29, source bindings 8 passed; the MCP + CLI-cleanup + stage-retirement selection passed 11 with 35 skipped (only the host-gated provider file).

Static checks round (jscpd)

34dfab14 failed one CI lane: Static checks → step Run npm run check:ci → jscpd, with
ERROR: jscpd found too many duplicates (3.0%) over threshold (3.0%) — 2368 files, 1484 clones, 3.01% duplicated
lines
against a 3.0% budget. The clone was mine: the standalone AArch64 case restated that file's own bridge stub
(recordedCrashProvider.test.ts lines 91:68–101:14 ↔ 153:5–163:14 and 109:20–121:28 ↔ 169:35–181:28).

39c82c17 drops the second copy and makes success-aarch64 a row of the scenario table that already drives a reply
through the structure, source and register bindings, so the assertion set is the same one its sibling scenarios in that table run,
plus expect(result.value.architecture).toBe(architecture).

Measured locally with npm run jscpd on the same .jscpd.json: 6055dc26 = 1429 clones / 2.98%, 34dfab14 = 1431
clones / 2.99%, 39c82c17 = 1429 clones / 2.98% — back on the baseline the previously-green commit sat at, and
jscpd:details no longer lists this file. Local totals differ slightly from CI's (CI counts generated files too), so
the claim is the delta, not the absolute. tsc --noEmit, oxfmt --check and the platform-independent suites are
unchanged by this commit.

The recorded-crash contract admitted only ELF64 x86-64 cores: the bridge
refused every other e_machine and the domain schema pinned one
architecture literal, so legitimate recorded Linux AArch64 crashes could
not be inspected at all.

Interpret a second profile from unchanged pwntools 4.15.0
elf_prstatus_aarch64 and user_regs_struct_aarch64 structures. The ABI
facts now have one owner, the domain profile, which the bridge mirrors:
AArch64 binds 34 uint64 registers at descriptor offset 112 within a
392-byte PRSTATUS, while x86-64 keeps its 27-register 336-byte window.
Any other machine is still refused before note interpretation.
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

@coderabbitai

coderabbitai Bot commented Oct 13, 2026

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

@morluto, what would you like me to do for this PR? I can see your latest comment and the PR objectives, but I do not have the full earlier conversation.

You are interacting with an AI system.

@morluto

morluto commented Oct 13, 2026

Copy link
Copy Markdown
Owner

@greptileai review

@greptile-apps

greptile-apps Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Medium impact] The PR appears safe to merge, with no outstanding findings.

Summary

Adds AArch64 recorded-core decoding with architecture-specific register layouts, source-byte checks, and Evidence CPU names.

  • Recorded crash inspection now reads AArch64 cores.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Selected core snapshot] --> B[Bridge selects ELF machine profile]
  B --> C[Decode recorded notes and registers]
  C --> D[Check report schema]
  D --> E[Bind ELF headers and values to snapshot]
  E --> F[Create Evidence with matching CPU family]
Loading

Reviews (5) · Last reviewed commit: "docs(recorded-crash): distinguish archit..." · Reviewed by Greptile

Comment thread bridge/pwntools/recorded_crash_impl.py Resolved
Comment thread src/domain/native/recordedCrash.ts Resolved
…he profile

Review found two places where the AArch64 profile stopped at the bridge:

- validateRecordedCrashStructure still refused every e_machine but 62, so an
  AArch64 core died inside PwntoolsRecordedCrashProvider before the widened
  register checks ran. It now compares the header against
  RECORDED_LINUX_CORE_PROFILES[report.architecture].machine, so the accepted
  machine stays bound to the architecture the reply actually claims.
- RecordedCrashService stamped "x86_64" on every created Evidence. The profile
  table now owns the CPU family as evidenceArchitecture and the service reads
  it, so an AArch64 report publishes arm64 instead of two conflicting names.

Tests added: both recorded profiles are admitted by their own e_machine, and
each is rejected when the header carries the other profile's machine; created
Evidence is pinned to x86_64 / arm64; and an AArch64 core now runs through the
full provider pipeline.

Refs morluto#2353
…o table

The first version of that case restated the provider's bridge stub, and jscpd
counts clones repo-wide: this branch went to 3.01% duplicated lines against a
3.0% budget, so `Static checks` failed at `npm run check:ci` -> jscpd.

Coverage is unchanged - `success-aarch64` is now a row of the existing scenario
table, which already drives a reply through the structure, source and register
bindings. Locally `npm run jscpd` is back at the `6055dc26` baseline (1429
clones, 2.98%), and with the pwntools host check and this file's `runIf`
temporarily opened the provider file is 35 passed / 0 failed. Reverting the
`e_machine` fix still kills `success-aarch64` with `Reported core structure
differs from its original ELF/note headers.`
@NIU-123370

Copy link
Copy Markdown
Contributor Author

The remaining Static checks failure is the repo-wide duplication budget, and trunk is already over it on its own, so this branch cannot come back under it by further de-duplicating its own code.

Same step (npm run check:ci → jscpd), three readings:

tree jscpd line conclusion
trunk 4276aaf18 (06:58Z) 2361 files, 1474 clones, 3.01% duplicated lines Static checks failure
trunk bf34d0d2f (07:13Z) 2367 files, 1480 clones, 3.01% Static checks failure
this PR 39c82c17 2368 files, 1482 clones, 3.01% Static checks failure

All three print ERROR: jscpd found too many duplicates (3.0%) over threshold (3.0%). This branch adds 2 clones over trunk, so even a clone-neutral version of it would still report 3.01% — the budget was crossed on trunk before this head ran, not here.

On my own share of it: my intermediate commit duplicated recordedCrashProvider.test.ts's bridge stub (clones at 91:68–101:14 ↔ 153:5–163:14 and 109:20–121:28 ↔ 169:35–181:28), and 39c82c1 removes that copy by folding success-aarch64 into the file's existing scenario table. Locally on one tree with the same .jscpd.json, c74142e6 = 1427 clones, that intermediate commit = 1431, current head = 1429. Local absolute totals aren't comparable to CI's (2322 vs 2368 files — CI also scans generated paths), so only the same-tree delta is quoted here; the residual +2 is this feature's own similarity to the sibling BinaryLayoutService boilerplate.

Happy to rebase once the budget is back under 3.0%, and equally happy to trim the +2 here if you would rather this branch contribute nothing to the count — say which and I will do it.

Comment thread src/domain/native/recordedCrash.ts Resolved
@greptile-apps

greptile-apps Bot commented Oct 13, 2026

Copy link
Copy Markdown
Contributor

Want your agent to iterate on Greptile's feedback? Try greploops.

@morluto

morluto commented Oct 13, 2026

Copy link
Copy Markdown
Owner

Review findings addressed at their producing boundaries and consumers. Latest changes were reviewed from source; tests and provider runs were skipped at the maintainer's request. Findings requiring separate decisions or verification remain open.

  1. thread 1

The canonical inspect_recorded_crash description still named only amd64 targets. It now names amd64 and AArch64 little-endian ELF64 cores while separately retaining the Linux x64 host profile and the existing BYO dependencies/authority. The guide's register-set wording also now distinguishes the schema's 27-register amd64 and 34-register AArch64 layouts. Generated catalogs and provider checks were not run at the user's request.

Source fix: 7fea123. Tests and checks were skipped at the user's explicit request; this assessment is based on source inspection.

@morluto morluto added enhancement New feature or request area: native Native analysis and decompilation, including Ghidra, IDA, and Hopper analysis behavior area: bridge Hopper bridge (Python) related changes area: server Server layer and tool wiring P2: medium Medium priority issue labels Oct 13, 2026
@morluto
morluto merged commit 522b992 into morluto:main Oct 13, 2026
36 checks passed
@morluto morluto mentioned this pull request Oct 14, 2026
3 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: bridge Hopper bridge (Python) related changes area: native Native analysis and decompilation, including Ghidra, IDA, and Hopper analysis behavior area: server Server layer and tool wiring enhancement New feature or request P2: medium Medium priority issue

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Decode recorded Linux AArch64 ELF core evidence

2 participants