Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(native): inspect offline ELF layout through pwntools (#1037)
Ysopwnable4fc6565b0ffb
diff --git a/.github/workflows/real-binary-layout.yml b/.github/workflows/real-binary-layout.ymlnew file mode 100644index 000000000..95a03e165--- /dev/null+++ b/.github/workflows/real-binary-layout.yml@@ -0,0 +1,78 @@+name: Real offline binary layout++on:+ workflow_dispatch:+ inputs:+ large_mcp:+ description: "Also verify the complete 65,281-section result over MCP (slow)"+ type: boolean+ default: false+ pull_request:+ paths:+ - ".github/workflows/real-binary-layout.yml"+ - "bridge/pwntools/**"+ - "src/native/pwntools/**"+ - "src/domain/native/binaryLayout*"+ - "src/application/binaryDiagnostics/**"+ - "src/contracts/native/binaryDiagnosticsToolContracts.ts"+ - "src/composition/binaryDiagnostics.ts"+ - "src/server/registerBinaryDiagnosticsTools.ts"+ - "src/server/createServer.ts"+ - "src/cli/binaryDiagnosticsCommands.ts"+ - "src/cli.ts"+ - "src/cliCommandNames.ts"+ - "src/contracts/toolContracts.ts"+ - "src/contracts/toolEffects.ts"+ - "src/process/OwnedCommand.ts"+ - "src/process/ProviderProcess.ts"+ - "src/process/ProviderDeadline.ts"+ - "src/process/ProcessOwnership*.ts"+ - "src/process/PrivateRuntimeRoot.ts"+ - "src/artifacts/readStableArtifact*.ts"+ - "src/artifacts/ArtifactReader.ts"+ - "src/domain/analysisError*.ts"+ - "scripts/verify-binary-layout.mjs"+ - "scripts/lib/elf-section-name-fixtures.mjs"+ - "scripts/lib/large-result-mcp.mjs"+ - "scripts/fixtures/binary-layout*"+ - "package.json"+ - "package-lock.json"++permissions:+ contents: read++concurrency:+ group: real-binary-layout-${{ github.event.pull_request.number || github.ref }}+ cancel-in-progress: true++env:+ NODE_OPTIONS: --max-old-space-size=768+ HUSKY: "0"+ REA_VERIFY_LARGE_ELF_MCP: ${{ inputs.large_mcp && '1' || '0' }}++jobs:+ real-binary-layout:+ runs-on: ubuntu-24.04+ timeout-minutes: 15+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version-file: .nvmrc+ cache: npm+ - run: npm ci+ - name: Acquire exact upstream libraries in an isolated runner environment+ shell: bash+ run: |+ layout_python_root="${RUNNER_TEMP}/rea-pwntools-layout"+ python3 -m venv "${layout_python_root}"+ "${layout_python_root}/bin/python" -m pip install --disable-pip-version-check \+ 'pwntools==4.15.0' 'pyelftools==0.33' 'unicorn==2.1.2'+ command -v gcc+ command -v ld+ command -v strip+ command -v strace+ echo "REA_PWNTOOLS_PYTHON=${layout_python_root}/bin/python" >> "${GITHUB_ENV}"+ echo "REA_VERIFY_STRACE_COMMAND=$(command -v strace)" >> "${GITHUB_ENV}"+ - name: Verify source-owned fixtures through public CLI and MCP+ run: npm run verify:binary:layoutdiff --git a/README.md b/README.mdindex d2ec86629..e0a1090a3 100644--- a/README.md+++ b/README.md@@ -150,6 +150,7 @@ Additional tools and host support depend on the target:| Target | What REA returns | Requirements and guide || ---------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- || Native binaries | Pseudocode, assembly, strings, symbols, calls and references | Hopper, Ghidra or IDA; [native analysis](https://morluto.github.io/rea/guides/native/) |+| Offline ELF layout | Sections, segments, original symbols/relocations and static mitigation candidates | Caller-supplied pwntools on Linux x64; [binary diagnostics](docs/binary-diagnostics.md) || JavaScript / Electron | Modules, imports, source maps, routes, IPC and native add-on relationships | Node.js and npm; [application analysis](https://morluto.github.io/rea/guides/javascript/) || Websites | Page structure, scripts, network observations and requested screenshots | A Chrome-family browser; [browser analysis](https://morluto.github.io/rea/guides/browser/) || Saved network captures | Requests, responses, exposed payloads and source locations | HAR; mitmdump on Linux for native mitmproxy captures; [capture guide](docs/web-network-captures.md) |diff --git a/README_ar.md b/README_ar.mdindex 45fa442d8..328c3b716 100644--- a/README_ar.md+++ b/README_ar.md@@ -213,20 +213,20 @@ rea setup## منصة أدوات التحقيق-| عائلة الأدوات | العدد | الاستخدام |-| -------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------- |-| الفحص الأصلي | 41 | الدوال والشيفرة شبه المصدرية والتعليمات والسلاسل والرموز والاستدعاءات والمراجع والتعليقات وقراءة البايتات ومواضع الملفات |-| سير عمل التحقيق | 14 | نظرات عامة على التطبيقات وملفات الدوال وواجهات API الأصلية والتوزيع وفك الترجمة الدفعي وتتبع الميزات ومسارات الاستدعاء ومخططاته واكتشاف Swift وObjective-C |-| أدوات macOS الأصلية | 8 | بيانات Mach-O والتوقيعات وplist والمعماريات واستعادة أسماء Swift ومراقبة الاستدعاءات عبر LLDB دون تشغيل Hopper |-| مخطط المخرجات | 5 | جرد الدلائل والحزم وملفات Interface Builder المترجمة وكتالوجات موارد Apple والاستخراج |-| PE/CLI المُدار | 7 | هوية تجميعات .NET وبياناتها الوصفية وتعليمات CIL والاعتماديات الأصلية واستيراد إعادة البناء ومقارنة الإصدارات |-| البرامج الثابتة | 2 | فحص مناطق البرامج الثابتة على Linux واستخراجها الصريح |-| Android APK | 5 | بيانات الحزمة وmanifest والبحث عن الأصناف وقوائم الأعضاء وفك ترجمة الأساليب والمراجع الثابتة |-| مراقبة المتصفح | 12 | بنية الصفحات وبيانات الشبكة والبرامج النصية وخرائط المصدر واكتشاف WebMCP والصور ومقارنة الالتقاط |-| تحليل Electron | 5 | مراقبة العارضين وخريطة التطبيق الثابتة والمواءمة بين نتائج الثبات والتشغيل |-| وقت تشغيل JavaScript | 2 | اكتشاف أهداف Node/Electron Inspector ومواضع البرامج وأحداث سياقات التنفيذ |-| سير عمل التطبيقات | 13 | تصدير النصوص البرمجية الملتقطة، تتبع الميزات عبر الطبقات ومقارنة الإصدارات ومواءمة المصدر التاريخي ومقارنة أشكال القيم المعادة والتحقق من إعادة الإنشاء |-| مساحة العمل والملاحظة | 21 | الجلسات وحزم الأدلة وسياق التنقل ومقارنة العمليات والمخرجات والدوال وتسجيل الأسئلة غير المحسومة |+| عائلة الأدوات | العدد | الاستخدام |+| ---------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------- |+| الفحص الأصلي | 41 | الدوال والشيفرة شبه المصدرية والتعليمات والسلاسل والرموز والاستدعاءات والمراجع والتعليقات وقراءة البايتات ومواضع الملفات |+| سير عمل التحقيق | 14 | نظرات عامة على التطبيقات وملفات الدوال وواجهات API الأصلية والتوزيع وفك الترجمة الدفعي وتتبع الميزات ومسارات الاستدعاء ومخططاته واكتشاف Swift وObjective-C |+| أدوات الملفات الثنائية | 9 | بيانات Mach-O والتوقيعات وplist والمعماريات وأسماء Swift ومراقبة الاستدعاءات عبر LLDB على macOS؛ تخطيط ELF وأدلة الحماية الثابتة على Linux |+| مخطط المخرجات | 5 | جرد الدلائل والحزم وملفات Interface Builder المترجمة وكتالوجات موارد Apple والاستخراج |+| PE/CLI المُدار | 7 | هوية تجميعات .NET وبياناتها الوصفية وتعليمات CIL والاعتماديات الأصلية واستيراد إعادة البناء ومقارنة الإصدارات |+| البرامج الثابتة | 2 | فحص مناطق البرامج الثابتة على Linux واستخراجها الصريح |+| Android APK | 5 | بيانات الحزمة وmanifest والبحث عن الأصناف وقوائم الأعضاء وفك ترجمة الأساليب والمراجع الثابتة |+| مراقبة المتصفح | 12 | بنية الصفحات وبيانات الشبكة والبرامج النصية وخرائط المصدر واكتشاف WebMCP والصور ومقارنة الالتقاط |+| تحليل Electron | 5 | مراقبة العارضين وخريطة التطبيق الثابتة والمواءمة بين نتائج الثبات والتشغيل |+| وقت تشغيل JavaScript | 2 | اكتشاف أهداف Node/Electron Inspector ومواضع البرامج وأحداث سياقات التنفيذ |+| سير عمل التطبيقات | 13 | تصدير النصوص البرمجية الملتقطة، تتبع الميزات عبر الطبقات ومقارنة الإصدارات ومواءمة المصدر التاريخي ومقارنة أشكال القيم المعادة والتحقق من إعادة الإنشاء |+| مساحة العمل والملاحظة | 21 | الجلسات وحزم الأدلة وسياق التنقل ومقارنة العمليات والمخرجات والدوال وتسجيل الأسئلة غير المحسومة |## خطة العملdiff --git a/README_ja.md b/README_ja.mdindex e64c367ae..813e870b2 100644--- a/README_ja.md+++ b/README_ja.md@@ -240,7 +240,7 @@ TypeScript と SQLite を使って私のプロジェクト向けに実装して| -------------------- | --: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- || ネイティブ検査 | 41 | 関数、疑似コード、アセンブリ、文字列、シンボル、呼び出し、参照、注釈、バイト読み取り、ファイルオフセット || 調査ワークフロー | 14 | アプリ概要、関数ドシエ、ネイティブ API とディスパッチ、一括逆コンパイル、機能トレース、コールパス、コールグラフ、Swift と Objective-C の検出 |-| macOS ネイティブ | 8 | Hopper を起動せずに扱える Mach-O メタデータ、コード署名、plist、アーキテクチャ、Swift シンボルのデマングル、LLDB による呼び出し観測 |+| ネイティブバイナリ | 9 | macOS の Mach-O メタデータ、署名、plist、アーキテクチャ、Swift シンボル、LLDB による呼び出し観測;Linux の ELF レイアウトと静的な保護機構の証拠 || 成果物グラフ | 5 | ディレクトリとパッケージの目録、コンパイル済み Interface Builder ファイル、Apple アセットカタログ、抽出 || マネージド PE/CLI | 7 | .NET の識別情報、メタデータ、CIL 命令、ネイティブ依存関係、再構築結果のインポート、ビルド比較 || ファームウェア | 2 | Linux ファームウェア領域の検査と明示的な展開 |diff --git a/README_ko.md b/README_ko.mdindex 66656e555..ee9a5fa0c 100644--- a/README_ko.md+++ b/README_ko.md@@ -207,7 +207,7 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이| ----------------- | --: | ------------------------------------------------------------------------------------------------------------------------- || 네이티브 검사 | 41 | 함수, 의사 코드, 어셈블리, 문자열, 심볼, 호출, 참조, 주석, 바이트 읽기, 파일 오프셋 || 조사 워크플로 | 14 | 앱 개요, 함수 기록서, 네이티브 API와 디스패치, 일괄 디컴파일, 기능 추적, 호출 경로, 호출 그래프, Swift와 Objective-C 탐색 |-| macOS 네이티브 | 8 | Hopper 실행 없이 처리하는 Mach-O 메타데이터, 서명, plist, 아키텍처, Swift 이름 복원, LLDB 호출 관찰 |+| 네이티브 바이너리 | 9 | macOS의 Mach-O 메타데이터, 서명, plist, 아키텍처, Swift 심볼과 LLDB 호출 관찰; Linux의 ELF 레이아웃과 정적 보호 증거 || 아티팩트 그래프 | 5 | 디렉터리와 패키지 목록, 컴파일된 Interface Builder 파일, Apple 애셋 카탈로그, 추출 || 관리 PE/CLI | 7 | .NET 식별, 메타데이터, CIL 명령어, 네이티브 종속성, 재구성 가져오기, 빌드 비교 || 펌웨어 | 2 | Linux 펌웨어 영역 검사 및 명시적 추출 |diff --git a/README_zh.md b/README_zh.mdindex 29b6052a1..3c0f1d9e8 100644--- a/README_zh.md+++ b/README_zh.md@@ -206,7 +206,7 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常| ----------------- | ---: | ------------------------------------------------------------------------------------------------------ || 原生检查 | 41 | 函数、伪代码、汇编、字符串、符号、调用、引用、注释、字节读取与文件偏移 || 调查工作流 | 14 | 应用概览、函数档案、原生 API 与分发、批量反编译、功能追踪、调用路径与调用图、Swift 与 Objective-C 发现 |-| macOS 原生工具 | 8 | Mach-O 元数据、代码签名、plist、架构、Swift 符号还原与 LLDB 调用观察,无需启动 Hopper |+| 原生二进制工具 | 9 | macOS 的 Mach-O 元数据、签名、plist、架构、Swift 符号与 LLDB 调用观察;Linux 的 ELF 布局和静态保护证据 || 产物图 | 5 | 目录与软件包清单、编译后的 Interface Builder 文件、Apple 资源目录与提取 || 托管 PE/CLI | 7 | .NET 程序集身份、元数据、CIL 指令、原生依赖声明、重建导入与构建比较 || 固件 | 2 | Linux 固件区域检查与显式提取 |diff --git a/bridge/pwntools/layout.py b/bridge/pwntools/layout.pynew file mode 100644index 000000000..0d39344ea--- /dev/null+++ b/bridge/pwntools/layout.py@@ -0,0 +1,39 @@+"""Catch typed resource failures while loading or running the owned ELF adapter.++Only this package's fixed sibling is executed; caller input stays in request.json.+Interpreter startup failures before this boundary remain unclassified.+"""+import os+import sys+++def resource_exit(status, marker):+ try:+ if len(sys.argv) > 2:+ descriptor = os.open(sys.argv[1], os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)+ os.write(descriptor, marker)+ os.close(descriptor)+ except (OSError, MemoryError):+ # Without a complete marker the parent keeps this failure unclassified.+ pass+ os._exit(status)++try:+ implementation = os.path.join(os.path.dirname(__file__), "layout_impl.py")+ with open(implementation, "rb") as handle:+ source = handle.read()+ exec(compile(source, implementation, "exec"), {+ "__file__": implementation,+ "__name__": "__main__",+ })+except MemoryError:+ # Reserved status: an observed allocation failure, including imports/compile.+ resource_exit(75, b"M")+except OSError as error:+ # Linux ENOMEM is an observed allocation failure, independent of error text.+ if error.errno == 12:+ resource_exit(75, b"M")+ # Linux EFBIG is observed directly, including a partial limits/reply write.+ if error.errno == 27:+ resource_exit(76, b"F")+ raisediff --git a/bridge/pwntools/layout_impl.py b/bridge/pwntools/layout_impl.pynew file mode 100644index 000000000..92b3ea9e8--- /dev/null+++ b/bridge/pwntools/layout_impl.py@@ -0,0 +1,356 @@+"""Offline adapter to unchanged pwntools 4.15.0; never use libs/maps/libc.++Owned request/snapshot/reply paths are supplied by REA. No host target-process launch,+user configuration initialization, debugger startup, or dependency installation.+"""+import base64+import importlib.metadata+import io+import json+import os+from pathlib import Path+import resource+import sys++PACKAGES = {"pwntools": "4.15.0", "pyelftools": "0.33", "unicorn": "2.1.2"}+OUTPUT_BYTES = 64 * 1024 * 1024+++class LayoutFailure(Exception):+ def __init__(self, reason, message):+ super().__init__(message)+ self.reason = reason+++def address(value):+ return hex(int(value))+++def file_range(offset, size, length):+ return 0 <= offset <= length and 0 <= size <= length - offset+++def location(offset, size, length):+ if not file_range(offset, size, length):+ raise LayoutFailure("format", "ELF contains a file-backed range outside the selected snapshot.")+ return {"offset": address(offset), "bytes": address(size)}+++def name_reference(display, section, offset, content):+ header = getattr(section, "header", None)+ if header is None or header.sh_type != "SHT_STRTAB":+ return {"display": display, "bytes_base64": None, "location": None,+ "unknown_reason": "Referenced string table could not be resolved."}+ return name_in_table(display, header.sh_offset, header.sh_size, offset, content)+++def name_in_table(display, table_start, table_size, offset, content):+ location(table_start, table_size, len(content))+ if not 0 <= offset < table_size:+ raise LayoutFailure("format", f"ELF name offset {offset} lies outside its declared string table of {table_size} bytes at file offset {table_start}.")+ start = table_start + offset+ limit = table_start + table_size+ end = content.find(b"\0", start, limit)+ if end < 0:+ raise LayoutFailure("format", "ELF name lacks a terminator within its reported string table.")+ raw = content[start:end]+ return {"display": raw.decode("utf-8", "replace") if display is None else display, "bytes_base64": base64.b64encode(raw).decode("ascii"),+ "location": location(start, len(raw) + 1, len(content)), "unknown_reason": None}+++def dynamic_name_reference(tags, offset, image, content):+ starts = [tag.d_val for tag in tags if tag.d_tag == "DT_STRTAB"]+ sizes = [tag.d_val for tag in tags if tag.d_tag == "DT_STRSZ"]+ if not starts or not sizes:+ raise LayoutFailure("format", "ELF dependency requires DT_STRTAB and DT_STRSZ.")+ if len(starts) != 1 or len(sizes) != 1:+ raise LayoutFailure("unsupported", "ELF dependency string-table tags are ambiguous: " + repr({"DT_STRTAB": starts, "DT_STRSZ": sizes}))+ if not 0 <= offset < sizes[0]:+ raise LayoutFailure("format", f"ELF dependency name offset {offset} lies outside declared DT_STRSZ {sizes[0]}.")+ offsets = set()+ if len(starts) == 1 and len(sizes) == 1:+ for segment in image.iter_segments_by_type("PT_LOAD"):+ h = segment.header+ if starts[0] >= h.p_vaddr and starts[0] + sizes[0] <= h.p_vaddr + h.p_filesz:+ offsets.add(h.p_offset + starts[0] - h.p_vaddr)+ if len(offsets) != 1:+ raise LayoutFailure("unsupported", "Dynamic string table lacks a unique file-backed mapping: " + repr({"DT_STRTAB": starts, "DT_STRSZ": sizes, "candidate_file_offsets": sorted(offsets)}))+ return name_in_table(None, offsets.pop(), sizes[0], offset, content)+++def symbol_value_meaning(raw, image_type, sections):+ index = raw.st_shndx+ if raw.st_info.type == "STT_FILE": return "no-address"+ if index == "SHN_UNDEF": return "undefined"+ if index == "SHN_COMMON": return "alignment"+ if index == "SHN_ABS": return "absolute-value"+ if not isinstance(index, int) or not 0 < index < len(sections) or index >= 0xff00:+ return "unknown-section-index"+ if sections[index].header.sh_type == "SHT_NULL":+ return "unknown-section-index"+ if image_type == "ET_REL": return "section-offset"+ if raw.st_info.type == "STT_TLS": return "tls-offset"+ return "linked-virtual-address"+++def relocation_target(image_type, section_index, offset, sections):+ if image_type != "ET_REL":+ return {"kind": "linked-virtual-address", "address": address(offset)}+ if section_index == 0 or sections[section_index].header.sh_type == "SHT_NULL":+ return {"kind": "unknown-section", "reported_section_index": section_index,+ "offset": address(offset), "unknown_reason": "undefined-section-reference" if section_index == 0 else "inactive-section-header"}+ return {"kind": "section-offset", "section_index": section_index, "offset": address(offset)}+++def inspect_elf(path, cache):+ for package, expected in PACKAGES.items():+ try:+ version = importlib.metadata.version(package)+ except importlib.metadata.PackageNotFoundError as error:+ raise LayoutFailure("unavailable", "Selected Python lacks " + package + " " + expected + ".") from error+ if version != expected:+ raise LayoutFailure("unsupported", "Expected " + package + " " + expected + "; selected Python reports " + version + ".")+ content = path.read_bytes()+ if len(content) < 4 or content[:4] != b"\x7fELF":+ raise LayoutFailure("format", "Selected object does not contain an ELF header.")+ if len(content) < 16:+ raise LayoutFailure("format", "Selected ELF identification is truncated.")+ if content[4] != 2 or content[5] != 1:+ raise LayoutFailure("unsupported", "Initial layout profile requires ELF64 little-endian objects.")+ if len(content) < 64:+ raise LayoutFailure("format", "Selected ELF64 header is truncated.")+ if int.from_bytes(content[18:20], "little") != 62:+ raise LayoutFailure("unsupported", "Initial layout profile requires x86-64 ELF objects.")+ if int.from_bytes(content[16:18], "little") not in (1, 2, 3):+ raise LayoutFailure("unsupported", "Selected ELF type is outside the EXEC/DYN/REL layout profile; recorded core analysis is separate.")+ from pwnlib.context import context+ with context.local(cache_dir=str(cache), log_level="warning"):+ from elftools.common.exceptions import ELFError+ from elftools.elf.elffile import ELFFile+ from pwnlib.elf import ELF+ try:+ headers = ELFFile(io.BytesIO(content))+ section_count = headers.num_sections()+ if headers.header.e_shstrndx == 0xffff and section_count == 0:+ raise LayoutFailure("format", "ELF extended section-name index requires a declared section-zero header.")+ raw_name_index = headers.header.e_shstrndx+ if 0xff00 <= raw_name_index < 0xffff:+ raise LayoutFailure("format", f"ELF section-name index {raw_name_index} is reserved and cannot directly reference a section.")+ section_name_index = headers.get_shstrndx()+ if raw_name_index == 0xffff and section_name_index < 0xff00:+ raise LayoutFailure("format", f"ELF SHN_XINDEX resolves to ordinary index {section_name_index}; the escape requires an index at least SHN_LORESERVE (0xff00).")+ if section_name_index != 0:+ if section_name_index >= section_count:+ raise LayoutFailure("format", f"ELF section-name table index {section_name_index} lies outside the declared section count {section_count}.")+ names_header = headers._get_section_header(section_name_index)+ if names_header.sh_type != "SHT_STRTAB":+ raise LayoutFailure("format", f"ELF section-name table {section_name_index} is not SHT_STRTAB.")+ location(names_header.sh_offset, names_header.sh_size, len(content))+ except ELFError as error:+ raise LayoutFailure("format", str(error)) from error+ class LayoutELF(ELF):+ def _get_section_name(self, header):+ # SHN_UNDEF declares no names; upstream would otherwise read+ # strings at the inactive section-zero offset.+ return "" if section_name_index == 0 else super()._get_section_name(header)++ # pyelftools 0.33 calls these documented filters internally;+ # pwntools 4.15.0's cached overrides do not accept the argument.+ # Forward the filter on this adapter instance, without modifying+ # either upstream package or process-global methods.+ def iter_segments(self, type=None):+ return (segment for segment in super().iter_segments()+ if type is None or segment.header.p_type == type)++ def iter_sections(self, type=None):+ return (section for section in super().iter_sections()+ if type is None or section.header.sh_type == type)+ try:+ image = LayoutELF(str(path), checksec=False)+ if image.arch != "amd64" or image.bits != 64 or image.endian != "little":+ raise LayoutFailure("unsupported", "Initial layout profile requires x86-64 ELF64 little-endian objects.")+ if image.header.e_type not in ("ET_EXEC", "ET_DYN", "ET_REL"):+ raise LayoutFailure("unsupported", "Selected ELF type is outside the EXEC/DYN/REL layout profile; recorded core analysis is separate.")+ length = len(content)+ all_sections = list(image.iter_sections())+ shstrings = image.get_section(section_name_index) if all_sections and section_name_index != 0 else None+ sections, segments, symbols, relocations, packed_relatives = [], [], [], [], []+ needed, interpreters = [], []+ for index, section in enumerate(all_sections):+ h = section.header+ backing = h.sh_type not in ("SHT_NOBITS", "SHT_NULL")+ if backing: location(h.sh_offset, h.sh_size, length)+ sections.append({+ "index": index, "name": name_reference(section.name, shstrings, h.sh_name, content) if shstrings is not None else {"display": "", "bytes_base64": None, "location": None, "unknown_reason": "ELF declares no section-name table (SHN_UNDEF index 0)."}, "name_offset": address(h.sh_name), "type": h.sh_type,+ "header_location": location(image.header.e_shoff + index * image.header.e_shentsize, image.header.e_shentsize, length),+ "address": address(h.sh_addr), "offset": address(h.sh_offset),+ "size": address(h.sh_size), "alignment": address(h.sh_addralign),+ "flags": address(h.sh_flags), "link": h.sh_link, "info": h.sh_info,+ "entry_size": address(h.sh_entsize), "file_backing": "file" if backing else "none",+ })+ if h.sh_type in ("SHT_SYMTAB", "SHT_DYNSYM"):+ if h.sh_entsize < image.structs.Elf_Sym.sizeof():+ raise LayoutFailure("format", "ELF symbol entry is smaller than the decoded Elf64_Sym structure.")+ if h.sh_link >= len(all_sections) or all_sections[h.sh_link].header.sh_type != "SHT_STRTAB":+ raise LayoutFailure("format", f"ELF symbol table {index} links to invalid string table {h.sh_link}.")+ strings = all_sections[h.sh_link]+ for entry, symbol in enumerate(section.iter_symbols()):+ raw = symbol.entry+ symbols.append({+ "table_index": index, "entry_index": entry,+ "name": name_reference(symbol.name, strings, raw.st_name, content), "name_offset": address(raw.st_name),+ "location": location(h.sh_offset + entry * h.sh_entsize, h.sh_entsize, length),+ "value": address(raw.st_value), "value_meaning": symbol_value_meaning(raw, image.header.e_type, all_sections),+ "size": address(raw.st_size), "binding": raw.st_info.bind, "type": raw.st_info.type,+ "visibility": raw.st_other.visibility, "section_index": raw.st_shndx,+ })+ if h.sh_type in ("SHT_REL", "SHT_RELA"):+ if image.header.e_type == "ET_REL" and h.sh_info >= len(all_sections):+ raise LayoutFailure("format", f"ELF relocation section {index} references missing target section {h.sh_info}.")+ symbol_table = None+ if h.sh_link != 0:+ if h.sh_link >= len(all_sections) or all_sections[h.sh_link].header.sh_type not in ("SHT_SYMTAB", "SHT_DYNSYM"):+ raise LayoutFailure("format", f"ELF relocation section {index} links to invalid symbol table {h.sh_link}.")+ symbol_table = all_sections[h.sh_link]+ for entry, relocation in enumerate(section.iter_relocations()):+ raw = relocation.entry+ if raw.r_info_sym != 0 and (symbol_table is None or raw.r_info_sym >= symbol_table.num_symbols()):+ raise LayoutFailure("format", f"ELF relocation section {index} entry {entry} references missing symbol {raw.r_info_sym} in table {h.sh_link}.")+ relocations.append({+ "section_index": index, "entry_index": entry, "reported_offset": address(raw.r_offset),+ "target": relocation_target(image.header.e_type, h.sh_info, raw.r_offset, all_sections),+ "location": location(h.sh_offset + entry * h.sh_entsize, h.sh_entsize, length),+ "type": raw.r_info_type, "symbol_table_index": h.sh_link, "symbol_index": raw.r_info_sym,+ "symbol_reference_meaning": "zero-symbol-value" if raw.r_info_sym == 0 else "symbol-table-entry",+ "addend": None if "r_addend" not in raw else str(raw.r_addend),+ })+ if h.sh_type == "SHT_RELR":+ packed_relatives.append({+ "section_index": index,+ "location": location(h.sh_offset, h.sh_size, length),+ "encoded_bytes_base64": base64.b64encode(content[h.sh_offset:h.sh_offset + h.sh_size]).decode("ascii"),+ "entries": [{"decoded_index": decoded, "reported_offset": address(relocation.entry.r_offset)} for decoded, relocation in enumerate(section.iter_relocations())],+ "offset_meaning": "unknown" if image.header.e_type == "ET_REL" else "linked-virtual-address",+ "evidence_kind": "derived", "entry_source_locations": None, "addends": None,+ })+ for index, segment in enumerate(image.iter_segments()):+ h = segment.header+ backing = h.p_type != "PT_NULL" and h.p_filesz != 0+ if backing: location(h.p_offset, h.p_filesz, length)+ if h.p_type == "PT_LOAD" and h.p_memsz < h.p_filesz:+ raise LayoutFailure("format", "ELF load segment memory size is smaller than its file size.")+ segments.append({+ "index": index, "type": h.p_type, "offset": address(h.p_offset),+ "header_location": location(image.header.e_phoff + index * image.header.e_phentsize, image.header.e_phentsize, length),+ "file_size": address(h.p_filesz), "memory_size": address(h.p_memsz),+ "virtual_address": address(h.p_vaddr), "physical_address": address(h.p_paddr),+ "alignment": address(h.p_align), "flags": address(h.p_flags),+ "file_backing": "file" if backing else "none",+ "permissions": None if h.p_type == "PT_NULL" else {"read": bool(h.p_flags & 4), "write": bool(h.p_flags & 2), "execute": bool(h.p_flags & 1)},+ })+ if h.p_type == "PT_DYNAMIC":+ tag_size = image.structs.Elf_Dyn.sizeof()+ tags = []+ for tag_index in range(h.p_filesz // tag_size):+ tag = segment._get_tag(tag_index)+ tags.append(tag)+ if tag.d_tag == "DT_NULL":+ break+ else:+ raise LayoutFailure("format", f"ELF dynamic segment {index} has no complete DT_NULL terminator within its reported file range.")+ for tag in tags:+ if tag.d_tag == "DT_NEEDED":+ needed.append(dynamic_name_reference(tags, tag.d_val, image, content))+ if h.p_type == "PT_INTERP":+ raw = content[h.p_offset:h.p_offset + h.p_filesz]+ end = raw.find(b"\0")+ if end < 0:+ raise LayoutFailure("format", "ELF interpreter lacks a reported terminator.")+ interpreters.append({"display": raw[:end].decode("utf-8", "replace"), "bytes_base64": base64.b64encode(raw[:end]).decode("ascii"), "location": location(h.p_offset, end + 1, length), "unknown_reason": None})+ return {+ "format": "elf", "architecture": {"machine": image.header.e_machine, "bits": image.bits, "byte_order": image.endian},+ "image_type": image.header.e_type,+ "entry_point": {"reported_value": address(image.header.e_entry), "meaning": "not-applicable" if image.header.e_type == "ET_REL" else "absent" if image.header.e_entry == 0 else "linked-virtual-address", "execution_status": "unknown"},+ "runtime_load_base": None, "sections": sections, "segments": segments, "symbols": symbols, "relocations": relocations,+ "packed_relative_relocations": packed_relatives, "relocation_inventory_completeness": "unknown",+ "linkage": {"needed_libraries": needed, "interpreters": interpreters,+ "got": [{"display_name": name, "address": address(value)} for name, value in image.got.items()],+ "plt": [{"display_name": name, "address": address(value)} for name, value in image.plt.items()],+ "convenience_maps_completeness": "unknown", "runtime_library_paths": None},+ "mitigations": {"evidence_kind": "inferred", "position_independent": image.pie, "nx_indicator": image.nx, "executable_stack_indicator": image.execstack, "stack_canary_indicator": image.canary, "relro": image.relro},+ "limitations": [+ "PT_NULL payload fields are unused and retain their reported numbers without file-byte or permission claims. Zero-file-size segments provide no file bytes.",+ "SHN_XINDEX symbol values remain unresolved in this upstream representation; an external index table does not establish a resolved index in this report.",+ "Reported values preserve linked addresses, section offsets, TLS offsets, alignment and absolute values separately. Runtime load base and library paths are unknown.",+ "Names are display strings plus raw bytes and file ranges where resolvable; section/table/entry indices preserve identity and duplicates. Name ranges include their terminating NUL; raw name bytes exclude it.",+ "Ordinary relocation rows cover REL/RELA. RELR tables retain complete encoded bytes and upstream-decoded offsets as derived evidence; per-offset packed-word locations and implicit addends remain unknown. Relocation inventory completeness is unknown, including other encodings and missing section tables.",+ "Relocation symbol index zero uses a zero symbol value without a table lookup. Positive indices reference validated original symbol-table entries; raw table and symbol indices remain reported.",+ "Relocatable relocation targets with SHN_UNDEF or inactive SHT_NULL headers retain their reported section index/offset as unknown; they do not establish an associated target section.",+ "GOT/PLT are derived upstream convenience maps; PLT inference can emulate selected instructions in Unicorn. They do not establish target runtime behavior; aliases may collapse and warnings may indicate incomplete coverage. Their completeness is unknown.",+ "Mitigations are upstream static heuristics, not runtime protection. ET_DYN does not prove an executable; absent canary symbols do not prove every function unprotected.",+ "This profile inspects ELF EXEC/DYN/REL layout only. It does not analyze recorded cores, resolve loaded libraries, launch the target as a host process or start a debugger.",+ "Symbol/relocation inventories reflect original section tables. A sectionless image can still report dynamic dependency names; missing tables do not prove absence of dynamic symbols or relocations.",+ *(["Absent section-name table: section-dependent RELRO/canary heuristics may be incomplete; protection coverage is unknown."] if all_sections and section_name_index == 0 else []),+ *(["Sectionless images lack the .dynamic section and symbol tables used by upstream heuristics. RELRO/canary indicators may be incomplete; their values remain reported static candidates, with protection coverage unknown."] if not all_sections else []),+ ],+ }+ except LayoutFailure:+ raise+ except (ELFError, ValueError, AssertionError, IndexError) as error:+ raise LayoutFailure("format", "Selected ELF failed unchanged upstream structural parsing: " + str(error)) from error+++def lower_resource_limits():+ limits = {}+ for name, kind, maximum in (+ ("address_space_bytes", resource.RLIMIT_AS, 3 * 1024**3),+ ("cpu_seconds", resource.RLIMIT_CPU, 30),+ ("file_size_bytes", resource.RLIMIT_FSIZE, OUTPUT_BYTES),+ ):+ soft, hard = resource.getrlimit(kind)+ finite = [maximum] + [value for value in (soft, hard) if value != resource.RLIM_INFINITY]+ effective = min(finite)+ # Preserve the inherited hard boundary and never raise a caller's soft limit.+ resource.setrlimit(kind, (effective, hard))+ limits[name] = effective+ return limits+++def main(request_path):+ request = json.loads(Path(request_path).read_text(encoding="utf-8"))+ os.environ["PWNLIB_NOTERM"] = "1"+ os.environ["PWNLIB_CACHE_DIR"] = str(Path(request_path).parent / "cache")+ limits = None+ # Release bounded emergency headroom before constructing a MemoryError reply.+ # The outer exit-status contract also covers allocation failure during serialization.+ memory_reserve = bytearray(1024 * 1024)+ try:+ limits = lower_resource_limits()+ descriptor = os.open(Path(request_path).parent / "limits.json", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)+ with os.fdopen(descriptor, "w", encoding="utf-8") as handle:+ json.dump(limits, handle)+ value = inspect_elf(Path(request["snapshot_path"]), Path(request_path).parent / "cache")+ value["limitations"].append("Effective owned Python resource soft limits: " + json.dumps(limits, sort_keys=True) + ". Inherited tighter limits are retained.")+ reply = {"ok": True, "profile": PROFILE, "value": value}+ except LayoutFailure as error:+ reply = {"ok": False, "reason": error.reason, "message": str(error)}+ except MemoryError:+ memory_reserve = None+ reply = {"ok": False, "reason": "resource-limit", "message": "pwntools memory allocation failed under the effective resource limits; the exact allocation cause is unknown.", "reported_limits": limits}+ except Exception as error:+ if isinstance(error, OSError) and error.errno == 12:+ memory_reserve = None+ reply = {"ok": False, "reason": "resource-limit", "message": "pwntools reported OSError(ENOMEM); the exact allocation cause is unknown.", "reported_limits": limits}+ else:+ reply = {"ok": False, "reason": "decoder", "message": type(error).__name__ + ": " + str(error)}+ encoded = json.dumps(reply, ensure_ascii=True, allow_nan=False).encode("utf-8")+ if len(encoded) > OUTPUT_BYTES:+ encoded = json.dumps({"ok": False, "reason": "output-limit", "message": "Complete ELF layout exceeds the 64 MiB reply budget."}).encode("utf-8")+ descriptor = os.open(request["reply_path"], os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)+ with os.fdopen(descriptor, "wb") as handle:+ handle.write(encoded)+++if __name__ == "__main__":+ main(sys.argv[-1])diff --git a/docs/architecture.mermaid b/docs/architecture.mermaidindex b4fc6c5b0..2bad907aa 100644--- a/docs/architecture.mermaid+++ b/docs/architecture.mermaid@@ -26,6 +26,7 @@ graph TDendsubgraph "Provider Layers"+ PWNTOOLS["src/native/pwntools/<br/>BYO offline ELF adapter<br/>owned Python process, unchanged upstream tables/heuristics"]HOPPER["src/hopper/<br/>Hopper launch & Unix-socket protocol<br/>BridgeLauncher, HopperClient, protocol"]GHIDRA["src/ghidra/<br/>Ghidra discovery, profile & function analysis<br/>snapshot, Unix/Windows transport, bounded lifecycle"]IDA["src/ida/<br/>Upstream MCP contract adaptation<br/>live GUI binding or owned headless database"]@@ -92,6 +93,9 @@ graph TDAPP -->|record callbacks| RECORDSSERVER -->|narrow record ports| RECORDSRECORDS --> DOMAIN+ COMPOSITION --> PWNTOOLS+ PWNTOOLS --> PROCESS+ PWNTOOLS --> DOMAINCOMPOSITION --> HOPPERCOMPOSITION --> GHIDRACOMPOSITION --> IDAdiff --git a/docs/binary-diagnostics.md b/docs/binary-diagnostics.mdnew file mode 100644index 000000000..a833edc36--- /dev/null+++ b/docs/binary-diagnostics.md@@ -0,0 +1,131 @@+# Offline binary diagnostics++`inspect_binary_layout` / `inspect-binary-layout` answers what an explicit+file contains: section/segment layout, original symbols/relocations, static+linkage names and mitigation indicators. It works without an active Hopper,+Ghidra or IDA target. CTF is one possible use; crash triage, compatibility and+ordinary binary inspection use the same modular capability.++## Bring your own engine++Initial real verification covers **Linux x64, ELF64 x86-64 little-endian+EXEC/DYN/REL**. Provide an absolute Python executable whose environment already+contains unchanged pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2:++```sh+REA_PWNTOOLS_PYTHON=/absolute/isolated-env/bin/python \+ rea inspect-binary-layout ./selected.elf --json+```++```json+{+ "name": "inspect_binary_layout",+ "arguments": { "path": "/artifacts/selected.elf" }+}+```++REA never installs Python, packages or GDB, changes a user init file, launches+the selected object as a host process, or requests runtime library resolution. The Python process+uses isolated mode and an owned cache. Exact upstream profiles are recorded in+[upstream provenance](../third_party/pwntools/README.md).++## Interpreting results++- Artifact path, SHA-256 and size identify original selected bytes. All parsing+ reads an owned stable snapshot; the original is unchanged.+- Addresses, offsets, lengths and flags are hexadecimal strings. A linked+ address is not a runtime address. Runtime load base remains null. A zero+ EXEC/DYN entry means absent; a relocatable entry is not applicable.+- Each symbol retains its table and entry index. Its reported value can mean+ undefined, alignment, absolute value, no address, unknown section index,+ section offset, TLS offset or linked virtual address. Duplicate names remain+ separate entries. SHN_XINDEX remains unresolved in the selected upstream+ representation; its external index table is not silently treated as resolved.+- Relocatable objects have section-relative relocations and no executable entry+ claim. Signed REL/RELA relocation addends are decimal strings. Packed RELR+ tables retain full original bytes and upstream-decoded offsets as derived+ evidence, with per-offset packed-word locations and implicit addends unknown.+ Overall relocation inventory completeness remains unknown.+ A relocatable SHN_UNDEF target or inactive SHT_NULL header remains an explicit+ unknown with the original reported section index and offset.+- REL/RELA symbol references retain their original table and entry indices.+ Positive indices resolve through a validated symbol table; symbol index zero+ means a zero symbol value without a table lookup, including when no table is+ linked. Malformed references fail with the affected section and symbol index.+- Section-name and symbol tables require declared SHT_STRTAB links.+ SHN_UNDEF explicitly means no section names: display is empty, raw name and+ location unknown, with the original name offsets retained. Extended section-name+ indices resolve through section zero and undergo the same validation.+- Symbol tables require a declared SHT_STRTAB link. Name offsets and terminators+ must stay inside the declared string table; malformed references fail before+ unrelated bytes can become names. Dynamic dependencies use DT_STRTAB/DT_STRSZ+ with a unique file-backed mapping; ambiguous or unbacked mappings are+ explicitly unsupported.+- Name display strings use UTF-8 replacement for opaque bytes, including+ sectionless dependency names and interpreter paths. Raw name+ bytes and string-table ranges retain observed identity where resolvable;+ ranges include the terminating NUL and base64 bytes exclude it.+- NOBITS and NULL sections provide no file bytes. Reported file-backed ranges+ are checked against snapshot size again at the public boundary. PT_NULL payload+ fields are unused: reported numbers remain, file backing is none and interpreted+ permissions are null. Segments with zero file size also have no file bytes.+- Sectionless dynamic images still report dependency names with raw bytes and+ file locations where uniquely mapped. Missing symbol/relocation section tables+ do not establish that those runtime tables are absent.+ Upstream RELRO/canary heuristics rely on sections and can be incomplete in+ this case; their reported candidates retain an explicit coverage limitation.+- DT_NEEDED/PT_INTERP are reported names, not resolved runtime paths. GOT/PLT+ maps are derived convenience views and may collapse aliases. PLT inference+ can emulate selected instructions in Unicorn; its outputs are static candidates.+ Exec syscall tracing observes host process launches. Map completeness+ remains unknown and original upstream warnings are returned inline.+- Canary, PIE, NX, executable-stack and RELRO are static inferences. NX and+ executable-stack are separate upstream indicators: on x86-64 an executable+ stack can accompany an unknown (`null`) NX indicator. ET_DYN can be a shared+ library, and an absent canary symbol does not prove every function unprotected.++Complete results have a 32 MiB input, 64 MiB reply, 1 MiB combined diagnostics+and 30-second owned command deadline. The reply budget applies to the decoder+record; the CLI/MCP Evidence envelope adds copies and encoding overhead. The+pinned MCP SDK defaults to a 10 MiB receive buffer. Large complete results need+a caller-configured `StdioClientTransport({ maxBufferSize: ... })`; the large+extended-index verification uses 256 MiB and an explicit five-minute request+timeout in its separate opt-in MCP lane. REA does not silently truncate the result. Python lowers resource soft limits to at most 3 GiB virtual address space,+30 CPU seconds and 64 MiB file output. Inherited tighter soft/hard limits are+retained, and the effective values are returned in the result limitations. Virtual address space is not RSS;+Unicorn needs a large virtual map. Limits fail with no partial success, and+owned process/root cleanup completes independently of cancellation.++Core files, GDB session/state/control, optional pwndbg enrichment and instruction+inspection are separate increments tracked by #969. This increment makes no+real support claim for those features or other operating systems/architectures.++Typed decoder failures retain bounded `captured_output` (stdout, stderr and an+explicit truncation flag) alongside the original failure category and reason.+Successful `diagnostics` also exposes the supervisor's `truncated` flag. Output+beyond the complete diagnostic budget is rejected, including when the decoder+writes a valid reply; cleanup and late cancellation reuse the observed flag.+Memory allocation failures use `resource_constraint`, with effective resource+limits (or an explicit unknown) and memory-specific recovery guidance. A+MemoryError alone does not establish the exact failed allocation or that a+particular budget was exhausted. Invalid undersized symbol entries are rejected+before REA reports source ranges for them.+The bridge reserves 1 MiB to report allocation failures. If even error reporting+or serialization fails with MemoryError, its reserved exit status preserves the+resource classification with unknown effective limits.+Reserved exits require a matching private marker written by the bridge's actual+failure branch. Bare launcher exits or missing/unwritable markers retain process+diagnostics with the resource cause unverified.+Signal termination alone is never classified as observed memory exhaustion.+The small bootstrap also covers catchable MemoryError during adapter imports,+compilation and initialization. Python interpreter startup failures before the+bootstrap runs retain their observed process diagnostics without guessed causes.+SIGXCPU retains a CPU resource diagnostic and CPU-specific recovery advice.+Observed EFBIG writes or SIGXFSZ termination retain a file-size resource+diagnostic and file-size-specific recovery advice. If a tight file limit also+prevents writing the limit record, effective values remain unknown.+The bridge records actual limits in owned storage before analysis; missing or+malformed limit reports remain unknown with their read failure preserved. A+received signal alone does not establish its exact cause. Dynamic tags require+a complete DT_NULL inside PT_DYNAMIC; interpreter names and ranges end at the+first NUL, with any padding still represented by the original segment range.diff --git a/docs/error-contract.schema.json b/docs/error-contract.schema.jsonindex 1d5f875cb..11f0fc659 100644--- a/docs/error-contract.schema.json+++ b/docs/error-contract.schema.json@@ -14,6 +14,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -48,6 +49,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -82,6 +84,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -116,6 +119,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -150,6 +154,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -184,6 +189,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -218,6 +224,42 @@"truncated","cancelled","timeout",+ "resource_constraint",+ "unavailable",+ "execution_failure"+ ]+ },+ "message": { "type": "string", "minLength": 1 },+ "retryable": { "type": "boolean" },+ "remediation": {+ "type": "object",+ "properties": { "action": { "type": "string", "minLength": 1 } },+ "required": ["action"],+ "additionalProperties": false+ },+ "details": {+ "type": "object",+ "propertyNames": { "type": "string" },+ "additionalProperties": {}+ }+ },+ "required": ["code", "category", "message", "retryable", "remediation"],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "code": { "type": "string", "const": "resource_constraint" },+ "category": {+ "type": "string",+ "enum": [+ "invalid_input",+ "unsupported_provider",+ "integrity_mismatch",+ "truncated",+ "cancelled",+ "timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -252,6 +294,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -286,6 +329,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -342,6 +386,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -376,6 +421,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -410,6 +456,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -444,6 +491,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -478,6 +526,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -512,6 +561,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -546,6 +596,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -580,6 +631,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]@@ -614,6 +666,7 @@"truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure"]diff --git a/docs/product-catalog.json b/docs/product-catalog.jsonindex 75735d07f..327a8e352 100644--- a/docs/product-catalog.json+++ b/docs/product-catalog.json@@ -7,10 +7,10 @@"client": "2.3.1","core": "2.3.1"},- "skill_version": "29"+ "skill_version": "30"},"tools": {- "total": 135,+ "total": 136,"families": [{"id": "direct",@@ -84,10 +84,11 @@{"id": "native","surface": "native-provider",- "count": 8,+ "count": 9,"tools": ["capture_native_ui_scenario","demangle_swift",+ "inspect_binary_layout","inspect_macho","inspect_plist","inspect_signature",@@ -372,6 +373,12 @@"observe_native_ui"]},+ {+ "id": "pwntools-elf",+ "name": "REA pwntools ELF adapter",+ "capabilities": ["inspect_binary_layout"]+ },{"id": "rea-android-application","name": "REA Android application workflows",@@ -585,7 +592,7 @@}],"cli": {- "primary_count": 90,+ "primary_count": 91,"commands": ["address-to-file-offset","analyze",@@ -627,6 +634,7 @@"inspect-android-package","inspect-artifact","inspect-asset-catalog",+ "inspect-binary-layout","inspect-electron-page","inspect-firmware-regions","inspect-keyed-archive",@@ -687,15 +695,15 @@},"runtime_catalog": {"counts": {- "cli_commands": 90,- "mcp_tools": 135,+ "cli_commands": 91,+ "mcp_tools": 136,"mcp_prompts": 6},"digests": {- "tools_sha256": "4266c0019ab7ddda340ceba2da9a62525368af1e6052d08cc0ef4a790be07882",+ "tools_sha256": "51992818bb03b1f6136a2674517e3d983037dc474cd0ac31a37fe4096211e5e2","prompts_sha256": "ef2de8814390b340623c32001610aa2709d90bed51537b6e562ab3abf144ab4d",- "combined_sha256": "bfa2ed377826f8e561d1b8a9024d4ab0cf11f09d8b1af86c80d2884c1d72dbf3",- "providers_sha256": "de4729a56a0e22b42f24803efefd625fa607b6af7de02d594b6dfaccf5a91fa0"+ "combined_sha256": "fc75e5d817f64311dacc23ef2bde4223fd12d2d5a9c49e93051ac9f7857b2d8c",+ "providers_sha256": "6e0080dea56ee7f3ebdf5ce0d74ea18e5d44ebce80b89c7f4de94e9c69f4d2e5"}}}diff --git a/docs/testing.md b/docs/testing.mdindex c82aeebab..ad3312253 100644--- a/docs/testing.md+++ b/docs/testing.md@@ -617,6 +617,23 @@ compiler. Ordinary unit/static gates acquire no browser. See[website runtime attribution](web-runtime.md) for effects, resource bounds andcoverage limits.+### Offline binary layout++`npm run verify:binary:layout` requires Linux x64, GCC/binutils, absolute+`REA_PWNTOOLS_PYTHON` with pwntools 4.15.0/pyelftools 0.33/Unicorn 2.1.2 and+absolute `REA_VERIFY_STRACE_COMMAND`. It compiles ephemeral source-owned ELF+fixtures and checks public CLI/MCP, lossless addresses/names, file ranges,+mitigation inferences, malformed/unsupported input, original file hashes and+released process ownership. Exec syscall tracing must identify only the declared+Node/Python launchers; no target binary is executed. Core/debugger claims need+separate verification lanes. Pass an installed package entrypoint as the script's+first argument to verify packaging independently of the checkout.+The valid SHN_XINDEX fixture has 65,281 full section rows; CLI is checked in+the ordinary lane. Its large MCP transfer is opt-in with+`REA_VERIFY_LARGE_ELF_MCP=1` (or the workflow dispatch `large_mcp` input), an+explicit 256 MiB SDK receive buffer and five-minute request timeout. Ordinary+MCP fixtures retain the pinned SDK defaults.+## Agent evaluation and conformance recordsEvaluate native, JavaScript, managed and browser investigation tasks through adiff --git a/docs/verification/managed-conformance-manifest.json b/docs/verification/managed-conformance-manifest.jsonindex 3092caf24..2d1fa5481 100644--- a/docs/verification/managed-conformance-manifest.json+++ b/docs/verification/managed-conformance-manifest.json@@ -1,5 +1,5 @@{- "manifest_id": "ecm_d5fdca7e469b71989b98eaec30d26af3ccb3a08b42d558b4d4fe3b1d220c3898",+ "manifest_id": "ecm_4308b9eca45ac983c4af2da0e6aafe6180b27569f55b3454b508f7c61a1f3fde","verifier": {"id": "rea-managed-conformance","version": "1"@@ -13,7 +13,7 @@"skill_digests": [{"skill_id": "reverse-engineer-anything",- "sha256": "3f8e02d3dc409f4fe0ac3a4315cfa4c34de53e504f627b6dc9cf6cb7b0adbedc"+ "sha256": "3c5b36ca0beb632f003b66e52afc4cd689ee5fe71c965dfa72374467cac9144e"}],"claims": [diff --git a/package.json b/package.jsonindex c1788c9ad..3c70e52a0 100644--- a/package.json+++ b/package.json@@ -63,7 +63,10 @@"LICENSE","native/windows/build/manifest.json","native/windows/build/rea-windows-x64.node",- "scripts/verify-windows-native-artifact.mjs"+ "scripts/verify-windows-native-artifact.mjs",+ "bridge/pwntools/layout.py",+ "bridge/pwntools/layout_impl.py",+ "third_party/pwntools/README.md"],"scripts": {"deps:check": "node scripts/check-dependency-install.mjs",@@ -195,7 +198,8 @@"verify:module-boundaries": "node scripts/verify-module-boundaries.mjs","verify:browser:source-maps": "npm run build:cached && node scripts/verify-browser-source-maps.mjs","verify:browser:runtime": "npm run build:cached && node scripts/verify-browser-runtime.mjs",- "verify:web:network-captures": "npm run build:cached && node scripts/verify-web-network-captures.mjs"+ "verify:web:network-captures": "npm run build:cached && node scripts/verify-web-network-captures.mjs",+ "verify:binary:layout": "npm run build:cached && node scripts/verify-binary-layout.mjs"},"lint-staged": {"*.{cjs,cts,js,jsx,mjs,mts,ts,tsx}": [diff --git a/scripts/fixtures/binary-layout-high.S b/scripts/fixtures/binary-layout-high.Snew file mode 100644index 000000000..5faf3fcb7--- /dev/null+++ b/scripts/fixtures/binary-layout-high.S@@ -0,0 +1,10 @@+.globl _start+.globl absolute_value+.set absolute_value, 0x20000000000007+.bss+.lcomm zero_backing, 8192+.text+_start:+ mov $60, %eax+ xor %edi, %edi+ syscalldiff --git a/scripts/fixtures/binary-layout.c b/scripts/fixtures/binary-layout.cnew file mode 100644index 000000000..0ff882b8e--- /dev/null+++ b/scripts/fixtures/binary-layout.c@@ -0,0 +1,17 @@+#include <stdio.h>+#include <stdlib.h>++int stored_value = 7;+char zero_backing[8192];+__thread int tls_value;+int common_value;++__attribute__((noinline)) int read_values(const char *text) {+ char buffer[32];+ snprintf(buffer, sizeof(buffer), "%s", text);+ return buffer[0] + stored_value + tls_value + common_value;+}++int main(int argc, char **argv) {+ return read_values(argc > 1 ? argv[1] : "source-owned");+}diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjsindex 3664e28aa..efe58e26c 100644--- a/scripts/lib/catalog-builders.mjs+++ b/scripts/lib/catalog-builders.mjs@@ -16,7 +16,10 @@ export const toolFamilyCatalog = (sources) => {{id: "native",surface: "native-provider",- contracts: sources.nativeContracts.NATIVE_TOOL_CONTRACTS,+ contracts: [+ ...sources.nativeContracts.NATIVE_TOOL_CONTRACTS,+ ...sources.binaryDiagnosticsContracts.BINARY_DIAGNOSTICS_TOOL_CONTRACTS,+ ],},{id: "artifact",@@ -143,6 +146,11 @@ export const providerCatalog = (sources) => {identity: sources.nativeProvider.NATIVE_MACOS_PROVIDER_IDENTITY,contracts: sources.nativeContracts.NATIVE_TOOL_CONTRACTS,},+ {+ identity: sources.pwntoolsProvider.PWNTOOLS_PROVIDER_IDENTITY,+ contracts:+ sources.binaryDiagnosticsContracts.BINARY_DIAGNOSTICS_TOOL_CONTRACTS,+ },{identity: sources.artifactProviders.ARTIFACT_GRAPH_PROVIDER,contracts: sources.artifactContracts.ARTIFACT_TOOL_CONTRACTS,diff --git a/scripts/lib/catalog-core.mjs b/scripts/lib/catalog-core.mjsindex c2b2018f8..178702f1c 100644--- a/scripts/lib/catalog-core.mjs+++ b/scripts/lib/catalog-core.mjs@@ -40,6 +40,9 @@ const SOURCE_PATHS = {officialContracts: "dist/contracts/officialToolContracts.js",enhancedContracts: "dist/contracts/enhancedToolContracts.js",sessionContracts: "dist/contracts/sessionToolContracts.js",+ binaryDiagnosticsContracts:+ "dist/contracts/native/binaryDiagnosticsToolContracts.js",+ pwntoolsProvider: "dist/native/pwntools/PwntoolsRelease.js",nativeContracts: "dist/contracts/native/nativeToolContracts.js",artifactContracts: "dist/contracts/artifactToolContracts.js",managedContracts: "dist/contracts/managed/managedToolContracts.js",diff --git a/scripts/lib/elf-section-name-fixtures.mjs b/scripts/lib/elf-section-name-fixtures.mjsnew file mode 100644index 000000000..ad3684c84--- /dev/null+++ b/scripts/lib/elf-section-name-fixtures.mjs@@ -0,0 +1,88 @@+import assert from "node:assert/strict";++/** Source-owned ELF64 mutations for declared, absent and escaped name-table references. */+export const sectionNameFixtures = (original, report) => {+ // ELF gABI: https://gabi.xinuos.com/elf/02-eheader.html#e-shstrndx+ // SHN_XINDEX must carry an actual index >= SHN_LORESERVE, not a small index.+ const sourceTable = report.sections[original.readUInt16LE(62)];+ assert.equal(sourceTable.type, "SHT_STRTAB");+ const sourceHeader = Number(BigInt(sourceTable.header_location.offset));+ const fixtures = [];+ for (const problem of [+ "out-of-range",+ "wrong-type",+ "undeclared-header",+ "extended-undeclared-header",+ "extended-without-sections",+ "extended-absent",+ "extended-small",+ ]) {+ let bytes = Buffer.from(original);+ let selected = report.sections.length + 100;+ if (problem === "wrong-type")+ selected = report.sections.find(+ (section) => section.type === "SHT_PROGBITS",+ ).index;+ else if (problem.includes("undeclared-header")) {+ const end =+ Number(bytes.readBigUInt64LE(40)) ++ report.sections.length * bytes.readUInt16LE(58);+ const extended = Buffer.alloc(Math.max(bytes.length, end + 64));+ bytes.copy(extended);+ bytes.copy(extended, end, sourceHeader, sourceHeader + 64);+ bytes = extended;+ selected = report.sections.length;+ }+ if (problem === "extended-without-sections") {+ bytes.writeBigUInt64LE(0n, 40);+ bytes.writeUInt16LE(0, 60);+ bytes.writeUInt16LE(0xffff, 62);+ } else if (problem.startsWith("extended-")) {+ bytes.writeUInt16LE(0xffff, 62);+ if (problem === "extended-absent") selected = 0;+ if (problem === "extended-small") selected = sourceTable.index;+ bytes.writeUInt32LE(selected, Number(bytes.readBigUInt64LE(40)) + 40);+ } else bytes.writeUInt16LE(selected, 62);+ fixtures.push({ name: problem, bytes, expectation: "invalid_input" });+ }+ const absent = Buffer.from(original);+ absent.writeUInt16LE(0, 62);+ fixtures.push({ name: "absent", bytes: absent, expectation: "absent" });++ // A genuine escape requires a large table. Relocate the original table, keep+ // its referenced indices and move only the name table to index SHN_LORESERVE.+ const selected = 0xff00,+ count = selected + 1;+ const start = Math.ceil(original.length / 8) * 8;+ const large = Buffer.alloc(start + count * 64);+ original.copy(large);+ const oldStart = Number(original.readBigUInt64LE(40));+ original.copy(large, start, oldStart, oldStart + report.sections.length * 64);+ large.fill(+ 0,+ start + sourceTable.index * 64,+ start + (sourceTable.index + 1) * 64,+ );+ original.copy(large, start + selected * 64, sourceHeader, sourceHeader + 64);+ large.writeBigUInt64LE(BigInt(start), 40);+ large.writeUInt16LE(0, 60);+ large.writeUInt16LE(0xffff, 62);+ large.writeBigUInt64LE(BigInt(count), start + 32);+ large.writeUInt32LE(selected, start + 40);+ fixtures.push({+ name: "extended-large",+ bytes: large,+ expectation: "resolved",+ tableIndex: selected,+ sectionCount: count,+ });+ const reserved = Buffer.from(large);+ reserved.writeUInt16LE(selected, 62);+ reserved.writeUInt32LE(0, start + 40);+ fixtures.push({+ name: "direct-reserved",+ bytes: reserved,+ expectation: "invalid_input",+ });+ return fixtures;+};diff --git a/scripts/lib/large-result-mcp.mjs b/scripts/lib/large-result-mcp.mjsnew file mode 100644index 000000000..d7a4ab30f--- /dev/null+++ b/scripts/lib/large-result-mcp.mjs@@ -0,0 +1,27 @@+import { Client } from "@modelcontextprotocol/client";+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";++/** Own one SDK client with an explicit receive budget for a large complete result. */+export const withLargeResultMcp = async (+ { entrypoint, environment, maxBufferSize },+ useClient,+) => {+ const client = new Client({ name: "large-result-verifier", version: "1" });+ const transport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "mcp"],+ env: environment,+ stderr: "inherit",+ maxBufferSize,+ });+ try {+ await client.connect(transport);+ return await useClient(client);+ } finally {+ try {+ await client.close();+ } finally {+ await transport.close();+ }+ }+};diff --git a/scripts/verify-binary-layout.mjs b/scripts/verify-binary-layout.mjsnew file mode 100644index 000000000..feb11b285--- /dev/null+++ b/scripts/verify-binary-layout.mjs@@ -0,0 +1,1290 @@+#!/usr/bin/env node+import assert from "node:assert/strict";+import { execFile } from "node:child_process";+import { createHash } from "node:crypto";+import {+ copyFile,+ mkdir,+ readFile,+ readdir,+ writeFile,+} from "node:fs/promises";+import { dirname, isAbsolute, join } from "node:path";+import { fileURLToPath } from "node:url";+import { promisify } from "node:util";+import { Client } from "@modelcontextprotocol/client";+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";+import { PrivateRuntimeRoot } from "../dist/process/PrivateRuntimeRoot.js";+import { parseEvidence } from "../dist/domain/evidence.js";+import { mcpTextValue } from "./lib/mcp-verifier-results.mjs";+import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";+import { sectionNameFixtures } from "./lib/elf-section-name-fixtures.mjs";+import { withLargeResultMcp } from "./lib/large-result-mcp.mjs";++const verifyLargeMcp = process.env.REA_VERIFY_LARGE_ELF_MCP === "1";+const python = process.env.REA_PWNTOOLS_PYTHON;+const strace = process.env.REA_VERIFY_STRACE_COMMAND;+if (+ process.platform !== "linux" ||+ process.arch !== "x64" ||+ !isAbsolute(python ?? "") ||+ !isAbsolute(strace ?? "")+)+ throw new Error(+ "verify:binary:layout requires Linux x64, absolute REA_PWNTOOLS_PYTHON (pwntools 4.15.0/pyelftools 0.33/Unicorn 2.1.2) and REA_VERIFY_STRACE_COMMAND. gcc, ld and strip must be available. No target is executed.",+ );+const run = createVerifierRun();+const execute = promisify(execFile);+for (const command of ["gcc", "ld", "strip", "/usr/bin/prlimit", strace]) {+ try {+ await execute(command, [command === strace ? "-V" : "--version"], {+ timeout: 10_000,+ maxBuffer: 1024 * 1024,+ });+ } catch (cause) {+ throw new Error(+ `verify:binary:layout prerequisite unavailable: ${command}`,+ { cause },+ );+ }+}+const entrypoint =+ process.argv[2] ?? fileURLToPath(new URL("./rea.mjs", import.meta.url));+const root = await PrivateRuntimeRoot.create({+ prefix: "rea-layout-verifier-",+});+const environment = Object.fromEntries(+ Object.entries(process.env).filter(([, value]) => typeof value === "string"),+);+const client = new Client({ name: "binary-layout-verifier", version: "1" });+const transport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "mcp"],+ env: environment,+ stderr: "pipe",+});+const source = fileURLToPath(+ new URL("./fixtures/binary-layout.c", import.meta.url),+);+const highSource = fileURLToPath(+ new URL("./fixtures/binary-layout-high.S", import.meta.url),+);+let cases = 0;+let bootstrapCases = 0;+const failures = [];+try {+ const bootstrapRoot = join(root.path, "bootstrap-boundary");+ await mkdir(bootstrapRoot);+ const bootstrapPath = join(bootstrapRoot, "layout.py");+ await copyFile(+ join(dirname(dirname(entrypoint)), "bridge/pwntools/layout.py"),+ bootstrapPath,+ );+ for (const [source, status] of [+ ["raise MemoryError('source-owned initialization failure')", 75],+ ["raise OSError(12, 'source-owned allocation failure')", 75],+ ["raise OSError(27, 'source-owned file write failure')", 76],+ [+ "raise OSError(2, 'MemoryError-like text is not an allocation failure')",+ 1,+ ],+ ]) {+ await writeFile(join(bootstrapRoot, "layout_impl.py"), source);+ const markerPath = join(bootstrapRoot, `failure-${bootstrapCases}`);+ let exitCode = 0;+ try {+ await execute(+ python,+ ["-I", bootstrapPath, markerPath, "unused-request"],+ {+ timeout: 10000,+ maxBuffer: 1024 * 1024,+ },+ );+ } catch (cause) {+ assert.equal(typeof cause.code, "number");+ exitCode = cause.code;+ }+ assert.equal(exitCode, status);+ if (status === 75 || status === 76)+ assert.equal(+ await readFile(markerPath, "ascii"),+ status === 75 ? "M" : "F",+ );+ else await assert.rejects(readFile(markerPath), { code: "ENOENT" });+ bootstrapCases++;+ }+ for (const [name, flags] of [+ [+ "protected",+ [+ "-fPIE",+ "-pie",+ "-fstack-protector-all",+ "-Wl,-z,relro,-z,now",+ "-Wl,-z,noexecstack",+ ],+ ],+ [+ "plain",+ [+ "-fno-pie",+ "-no-pie",+ "-fno-stack-protector",+ "-Wl,-z,norelro",+ "-Wl,-z,execstack",+ ],+ ],+ ["relocatable", ["-c", "-fcommon", "-fPIC"]],+ ["library", ["-shared", "-fPIC", "-fno-stack-protector"]],+ ["packed-relative", ["-shared", "-fPIC", "-Wl,-z,pack-relative-relocs"]],+ ])+ await execute(+ "gcc",+ ["-O1", "-g", ...flags, source, "-o", join(root.path, name)],+ { timeout: 30_000, maxBuffer: 1024 * 1024 },+ );+ const sectionlessBytes = await readFile(join(root.path, "protected"));+ sectionlessBytes.writeBigUInt64LE(0n, 40);+ sectionlessBytes.writeUInt16LE(0, 60);+ sectionlessBytes.writeUInt16LE(0, 62);+ await writeFile(join(root.path, "sectionless"), sectionlessBytes);+ const nullBytes = Buffer.from(await readFile(join(root.path, "protected")));+ const phOffset = Number(nullBytes.readBigUInt64LE(32));+ const phSize = nullBytes.readUInt16LE(54);+ const phCount = nullBytes.readUInt16LE(56);+ const unusedIndex = Array.from({ length: phCount }, (_, index) => index).find(+ (index) => nullBytes.readUInt32LE(phOffset + index * phSize) === 0x6474e551,+ );+ assert.notEqual(+ unusedIndex,+ undefined,+ "Required stack fixture header absent",+ );+ const unusedHeader = phOffset + unusedIndex * phSize;+ nullBytes.writeUInt32LE(0, unusedHeader);+ for (const field of [8, 32, 40])+ nullBytes.writeBigUInt64LE(0xffffffffffffffffn, unusedHeader + field);+ await writeFile(join(root.path, "unused-segment"), nullBytes);+ const emptyBytes = Buffer.from(nullBytes);+ emptyBytes.writeUInt32LE(1, unusedHeader);+ emptyBytes.writeBigUInt64LE(0n, unusedHeader + 32);+ emptyBytes.writeBigUInt64LE(0n, unusedHeader + 40);+ await writeFile(join(root.path, "empty-segment"), emptyBytes);+ await copyFile(join(root.path, "protected"), join(root.path, "stripped"));+ await execute("strip", ["--strip-all", join(root.path, "stripped")], {+ timeout: 10_000,+ });+ await execute("gcc", ["-c", highSource, "-o", join(root.path, "high.o")], {+ timeout: 10_000,+ });+ await execute(+ "ld",+ [+ "-Ttext=0x20000000000001",+ "-o",+ join(root.path, "high"),+ join(root.path, "high.o"),+ ],+ { timeout: 10_000 },+ );+ await client.connect(transport);+ const reports = new Map();+ for (const name of [+ "protected",+ "plain",+ "relocatable",+ "library",+ "packed-relative",+ "stripped",+ "sectionless",+ "unused-segment",+ "empty-segment",+ "high",+ ]) {+ const path = join(root.path, name);+ const bytes = await readFile(path);+ const sha256 = createHash("sha256").update(bytes).digest("hex");+ for (const mode of ["cli", "mcp"]) {+ const value = await inspect(mode, path);+ assert.equal(value.artifact.sha256, sha256);+ assert.equal(value.artifact.bytes, bytes.length);+ assert.equal(value.runtime_load_base, null);+ assert.equal(value.linkage.runtime_library_paths, null);+ assert.equal(value.mitigations.evidence_kind, "inferred");+ if (name === "sectionless") {+ assert.equal(value.sections.length, 0);+ assert.equal(value.symbols.length, 0);+ assert.deepEqual(+ value.linkage.needed_libraries,+ reports.get("protected").linkage.needed_libraries,+ );+ assert.ok(+ value.linkage.needed_libraries.every(+ (name) => name.location !== null && name.bytes_base64 !== null,+ ),+ );+ // Preserve the unchanged engine's section-dependent heuristic and its+ // explicit coverage limitation, rather than inventing a stronger label.+ assert.equal(value.mitigations.relro, "Partial");+ assert.ok(+ value.limitations.some((item) =>+ item.includes("RELRO/canary indicators may be incomplete"),+ ),+ );+ } else+ assert.ok(+ value.sections.some((section) => section.file_backing === "none"),+ );+ for (const section of value.sections) {+ assert.ok(typeof section.address === "string");+ if (section.file_backing === "file")+ assert.ok(+ BigInt(section.offset) + BigInt(section.size) <=+ BigInt(bytes.length),+ );+ }+ if (name === "unused-segment" || name === "empty-segment") {+ const segment = value.segments[unusedIndex];+ assert.equal(segment.file_backing, "none");+ assert.equal(segment.offset, "0xffffffffffffffff");+ if (name === "unused-segment") assert.equal(segment.permissions, null);+ else assert.notEqual(segment.permissions, null);+ }+ assert.equal(value.relocation_inventory_completeness, "unknown");+ if (name === "library" || name === "packed-relative") {+ assert.equal(value.entry_point.reported_value, "0x0");+ assert.equal(value.entry_point.meaning, "absent");+ }+ if (name === "packed-relative") {+ assert.ok(value.packed_relative_relocations.length > 0);+ for (const table of value.packed_relative_relocations) {+ assert.equal(table.evidence_kind, "derived");+ assert.equal(table.offset_meaning, "linked-virtual-address");+ assert.equal(table.entry_source_locations, null);+ assert.equal(table.addends, null);+ assert.ok(table.entries.length > 0);+ const start = Number(BigInt(table.location.offset));+ const length = Number(BigInt(table.location.bytes));+ assert.deepEqual(+ Buffer.from(table.encoded_bytes_base64, "base64"),+ bytes.subarray(start, start + length),+ );+ }+ }+ reports.set(name, value);+ assert.deepEqual(await readFile(path), bytes);+ cases++;+ }+ }+ const protectedReport = reports.get("protected");+ const fileSymbols = protectedReport.symbols.filter(+ (symbol) => symbol.type === "STT_FILE",+ );+ assert.ok(fileSymbols.length > 0);+ assert.ok(+ fileSymbols.every((symbol) => symbol.value_meaning === "no-address"),+ );+ const plain = reports.get("plain");+ assert.equal(protectedReport.mitigations.position_independent, true);+ assert.equal(protectedReport.mitigations.nx_indicator, true);+ assert.equal(protectedReport.mitigations.stack_canary_indicator, true);+ assert.equal(protectedReport.mitigations.relro, "Full");+ assert.equal(plain.mitigations.position_independent, false);+ assert.equal(plain.mitigations.nx_indicator, null);+ assert.equal(plain.mitigations.executable_stack_indicator, true);+ assert.equal(protectedReport.mitigations.executable_stack_indicator, false);+ assert.equal(plain.mitigations.stack_canary_indicator, false);+ assert.equal(plain.mitigations.relro, null);+ const relocatable = reports.get("relocatable");+ assert.equal(relocatable.entry_point.meaning, "not-applicable");+ assert.ok(relocatable.relocations.length > 0);+ assert.ok(+ relocatable.relocations.every(+ (item) => item.target.kind === "section-offset",+ ),+ );+ assert.ok(+ relocatable.relocations.some((item) => BigInt(item.addend ?? "0") < 0n),+ );+ assert.equal(+ relocatable.symbols.find((symbol) => symbol.name.display === "common_value")+ .value_meaning,+ "alignment",+ );+ assert.equal(+ reports+ .get("library")+ .symbols.find((symbol) => symbol.name.display === "tls_value")+ .value_meaning,+ "tls-offset",+ );+ assert.equal(+ reports.get("high").entry_point.reported_value,+ "0x20000000000001",+ );+ assert.equal(+ reports+ .get("high")+ .symbols.find((symbol) => symbol.name.display === "absolute_value").value,+ "0x20000000000007",+ );+ assert.equal(+ reports+ .get("high")+ .symbols.find((symbol) => symbol.name.display === "absolute_value")+ .value_meaning,+ "absolute-value",+ );+ assert.ok(+ reports.get("stripped").symbols.length < protectedReport.symbols.length,+ );+ const object = await readFile(join(root.path, "relocatable"));+ const name = relocatable.symbols.find(+ (symbol) => symbol.name.display === "read_values",+ ).name;+ const changed = Buffer.from(object);+ changed[Number(BigInt(name.location.offset))] = 0xff;+ const opaque = join(root.path, "opaque-name.o");+ await writeFile(opaque, changed);+ for (const mode of ["cli", "mcp"]) {+ const value = await inspect(mode, opaque);+ const symbol = value.symbols.find((item) =>+ item.name.display.endsWith("ead_values"),+ );+ assert.equal(Buffer.from(symbol.name.bytes_base64, "base64")[0], 0xff);+ assert.equal(symbol.name.location.offset, name.location.offset);+ assert.deepEqual(await readFile(opaque), changed);+ cases++;+ }+ const sectionBearingBytes = await readFile(join(root.path, "protected"));+ const dynamicSegment = protectedReport.segments.find(+ (segment) => segment.type === "PT_DYNAMIC",+ );+ const interpreterSegment = protectedReport.segments.find(+ (segment) => segment.type === "PT_INTERP",+ );+ assert.notEqual(dynamicSegment, undefined);+ assert.notEqual(interpreterSegment, undefined);+ const dependency = protectedReport.linkage.needed_libraries[0];+ assert.notEqual(dependency, undefined);+ assert.notEqual(dependency.location, null);+ for (const [profile, original] of [+ ["section-bearing", sectionBearingBytes],+ ["sectionless", sectionlessBytes],+ ]) {+ for (const facet of ["dependency", "interpreter"]) {+ const bytes = Buffer.from(original);+ const reference =+ facet === "dependency"+ ? dependency+ : protectedReport.linkage.interpreters[0];+ assert.notEqual(reference, undefined);+ assert.notEqual(reference.location, null);+ const raw = Buffer.from(reference.bytes_base64, "base64");+ const changedIndex = facet === "dependency" ? 0 : 1;+ raw[changedIndex] = 0xff;+ bytes[Number(BigInt(reference.location.offset)) + changedIndex] = 0xff;+ const path = join(root.path, `opaque-${profile}-${facet}`);+ await writeFile(path, bytes);+ for (const mode of ["cli", "mcp"]) {+ const value = await inspect(mode, path);+ const actual =+ facet === "dependency"+ ? value.linkage.needed_libraries[0]+ : value.linkage.interpreters[0];+ assert.deepEqual(actual, {+ ...reference,+ display: raw.toString("utf8"),+ bytes_base64: raw.toString("base64"),+ });+ assert.equal(+ value.artifact.sha256,+ createHash("sha256").update(bytes).digest("hex"),+ );+ assert.deepEqual(await readFile(path), bytes);+ cases++;+ }+ }+ }+ for (const fixture of sectionNameFixtures(+ sectionBearingBytes,+ protectedReport,+ )) {+ const path = join(root.path, `section-names-${fixture.name}`);+ await writeFile(path, fixture.bytes);+ for (const mode of ["cli", "mcp"]) {+ if (+ fixture.expectation === "resolved" &&+ mode === "mcp" &&+ !verifyLargeMcp+ )+ continue;+ // Ordinary cases retain the SDK default. Only this complete 65,281-row+ // case selects a larger receive budget; production data is not truncated.+ const value =+ fixture.expectation === "resolved" && mode === "mcp"+ ? await withLargeResultMcp(+ { entrypoint, environment, maxBufferSize: 256 * 1024 * 1024 },+ (largeClient) =>+ inspect(mode, path, undefined, environment, largeClient),+ )+ : await inspect(+ mode,+ path,+ fixture.expectation === "invalid_input"+ ? "invalid_input"+ : undefined,+ );+ if (fixture.expectation === "absent") {+ assert.deepEqual(value.symbols, protectedReport.symbols);+ assert.deepEqual(+ value.sections.map((section) => section.name),+ protectedReport.sections.map(() => ({+ display: "",+ bytes_base64: null,+ location: null,+ unknown_reason:+ "ELF declares no section-name table (SHN_UNDEF index 0).",+ })),+ );+ assert.deepEqual(+ value.sections.map((section) => section.name_offset),+ protectedReport.sections.map((section) => section.name_offset),+ );+ } else if (fixture.expectation === "resolved") {+ assert.equal(value.sections.length, fixture.sectionCount);+ assert.deepEqual(+ value.sections[fixture.tableIndex].name,+ protectedReport.sections[sectionBearingBytes.readUInt16LE(62)].name,+ );+ assert.deepEqual(value.symbols, protectedReport.symbols);+ }+ cases++;+ }+ assert.deepEqual(await readFile(path), fixture.bytes);+ }+ // Malformed references must fail before the decoder reads unrelated bytes.+ const neededTagOffsets = [];+ let stringSizeTagOffset;+ for (+ let offset = Number(BigInt(dynamicSegment.offset));+ offset <+ Number(BigInt(dynamicSegment.offset) + BigInt(dynamicSegment.file_size));+ offset += 16+ ) {+ const tag = sectionBearingBytes.readBigUInt64LE(offset);+ if (tag === 0n) break;+ if (tag === 1n) neededTagOffsets.push(offset + 8);+ if (tag === 10n) stringSizeTagOffset = offset + 8;+ }+ assert.ok(neededTagOffsets.length > 0);+ assert.notEqual(stringSizeTagOffset, undefined);+ for (const [profile, original] of [+ ["section-bearing", sectionBearingBytes],+ ["sectionless", sectionlessBytes],+ ]) {+ for (const problem of ["offset-at-end", "truncated-table"]) {+ const bytes = Buffer.from(original);+ if (problem === "offset-at-end")+ bytes.writeBigUInt64LE(+ bytes.readBigUInt64LE(stringSizeTagOffset),+ neededTagOffsets[0],+ );+ else {+ assert.ok(bytes.readBigUInt64LE(neededTagOffsets[0]) > 0n);+ bytes.writeBigUInt64LE(1n, stringSizeTagOffset);+ }+ const path = join(root.path, `invalid-dependency-${profile}-${problem}`);+ await writeFile(path, bytes);+ for (const mode of ["cli", "mcp"]) {+ await inspect(mode, path, "invalid_input");+ cases++;+ }+ assert.deepEqual(await readFile(path), bytes);+ }+ }+ for (const type of ["SHT_SYMTAB", "SHT_DYNSYM"]) {+ const table = protectedReport.sections.find(+ (section) => section.type === type,+ );+ const other = protectedReport.sections.find(+ (section) => section.type === "SHT_PROGBITS",+ );+ assert.notEqual(table, undefined);+ assert.notEqual(other, undefined);+ const header = Number(BigInt(table.header_location.offset));+ const strings = protectedReport.sections[table.link];+ assert.equal(strings.type, "SHT_STRTAB");+ for (const problem of [+ "out-of-range",+ "null",+ "wrong-type",+ "undeclared-header",+ ]) {+ let bytes = Buffer.from(sectionBearingBytes);+ let link =+ problem === "null"+ ? 0+ : problem === "wrong-type"+ ? other.index+ : protectedReport.sections.length + 100;+ if (problem === "undeclared-header") {+ // Upstream can read an otherwise valid header beyond declared e_shnum.+ const end =+ Number(bytes.readBigUInt64LE(40)) ++ protectedReport.sections.length * bytes.readUInt16LE(58);+ const extended = Buffer.alloc(Math.max(bytes.length, end + 64));+ bytes.copy(extended);+ const start = Number(BigInt(strings.header_location.offset));+ bytes.copy(extended, end, start, start + 64);+ bytes = extended;+ link = protectedReport.sections.length;+ }+ bytes.writeUInt32LE(link, header + 40);+ const path = join(root.path, `invalid-symbol-link-${type}-${problem}`);+ await writeFile(path, bytes);+ for (const mode of ["cli", "mcp"]) {+ await inspect(mode, path, "invalid_input");+ cases++;+ }+ assert.deepEqual(await readFile(path), bytes);+ }+ }+ const shortDynamic = Buffer.from(sectionBearingBytes);+ shortDynamic.writeBigUInt64LE(+ 16n,+ Number(BigInt(dynamicSegment.header_location.offset)) + 32,+ );+ assert.notEqual(+ shortDynamic.readBigUInt64LE(Number(BigInt(dynamicSegment.offset))),+ 0n,+ );+ const paddedInterpreter = Buffer.from(sectionBearingBytes);+ const interpreterStart = Number(BigInt(interpreterSegment.offset));+ paddedInterpreter[interpreterStart + 2] = 0;+ const paddedInterpreterPath = join(root.path, "padded-interpreter");+ await writeFile(paddedInterpreterPath, paddedInterpreter);+ for (const mode of ["cli", "mcp"]) {+ const value = await inspect(mode, paddedInterpreterPath);+ assert.deepEqual(value.linkage.interpreters, [+ {+ display: "/l",+ bytes_base64: Buffer.from("/l").toString("base64"),+ location: { offset: interpreterSegment.offset, bytes: "0x3" },+ unknown_reason: null,+ },+ ]);+ assert.equal(+ value.segments[interpreterSegment.index].file_size,+ interpreterSegment.file_size,+ );+ assert.deepEqual(await readFile(paddedInterpreterPath), paddedInterpreter);+ cases++;+ }+ const unterminatedInterpreter = Buffer.from(sectionBearingBytes);+ unterminatedInterpreter.fill(+ 0x58,+ interpreterStart,+ interpreterStart + Number(BigInt(interpreterSegment.file_size)),+ );+ const zeroSymbolEntries = ["SHT_SYMTAB", "SHT_DYNSYM"].map((type) => {+ const section = protectedReport.sections.find((item) => item.type === type);+ assert.notEqual(+ section,+ undefined,+ `Required fixture table absent: ${type}`,+ );+ const bytes = Buffer.from(sectionBearingBytes);+ bytes.writeBigUInt64LE(+ 0n,+ Number(BigInt(section.header_location.offset)) + 56,+ );+ return [`zero-entry-${type}`, bytes, "invalid_input"];+ });+ const undersizedSymbolEntries = ["SHT_SYMTAB", "SHT_DYNSYM"].map((type) => {+ const section = protectedReport.sections.find((item) => item.type === type);+ assert.notEqual(section, undefined);+ const bytes = Buffer.from(sectionBearingBytes);+ const header = Number(BigInt(section.header_location.offset));+ bytes.writeBigUInt64LE(8n, header + 32);+ bytes.writeBigUInt64LE(8n, header + 56);+ return [`undersized-entry-${type}`, bytes, "invalid_input"];+ });+ const relocationSection = relocatable.sections.find(+ (item) => item.type === "SHT_RELA",+ );+ assert.notEqual(relocationSection, undefined);+ const undersizedRelocationEntries = [+ ["REL", 9],+ ["RELA", 4],+ ].map(([type, sectionType]) => {+ const bytes = Buffer.from(object);+ const header = Number(BigInt(relocationSection.header_location.offset));+ bytes.writeUInt32LE(sectionType, header + 4);+ bytes.writeBigUInt64LE(8n, header + 32);+ bytes.writeBigUInt64LE(8n, header + 56);+ return [`undersized-entry-${type}`, bytes, "invalid_input"];+ });+ const invalidRelocationReferences = [+ ["missing-symbol-table", relocatable.sections.length + 100],+ ["wrong-symbol-table-kind", 1],+ ["positive-symbol-without-table", 0],+ ["missing-relocation-symbol", null],+ ].map(([name, link]) => {+ const bytes = Buffer.from(object);+ const header = Number(BigInt(relocationSection.header_location.offset));+ if (link === null) {+ const offset = Number(BigInt(relocationSection.offset)) + 8;+ const type = bytes.readBigUInt64LE(offset) & 0xffffffffn;+ bytes.writeBigUInt64LE((0xffffffffn << 32n) | type, offset);+ } else bytes.writeUInt32LE(link, header + 40);+ return [name, bytes, "invalid_input"];+ });+ const inactiveTarget = relocatable.sections.find(+ (section) => section.name.display === ".comment",+ );+ assert.notEqual(+ inactiveTarget,+ undefined,+ "Required inactive-target fixture absent",+ );+ for (const [name, targetIndex, reason] of [+ ["undefined-relocation-target", 0, "undefined-section-reference"],+ [+ "inactive-relocation-target",+ inactiveTarget.index,+ "inactive-section-header",+ ],+ ]) {+ const bytes = Buffer.from(object);+ bytes.writeUInt32LE(+ targetIndex,+ Number(BigInt(relocationSection.header_location.offset)) + 44,+ );+ if (targetIndex !== 0)+ bytes.writeUInt32LE(+ 0,+ Number(BigInt(inactiveTarget.header_location.offset)) + 4,+ );+ const inactiveSymbol = relocatable.symbols.find(+ (symbol) => symbol.name.display === "read_values",+ );+ assert.notEqual(inactiveSymbol, undefined);+ if (targetIndex !== 0)+ bytes.writeUInt16LE(+ targetIndex,+ Number(BigInt(inactiveSymbol.location.offset)) + 6,+ );+ const path = join(root.path, name);+ await writeFile(path, bytes);+ for (const mode of ["cli", "mcp"]) {+ const value = await inspect(mode, path);+ const rows = value.relocations.filter(+ (item) => item.section_index === relocationSection.index,+ );+ assert.ok(rows.length > 0);+ for (const row of rows)+ assert.deepEqual(row.target, {+ kind: "unknown-section",+ reported_section_index: targetIndex,+ offset: row.reported_offset,+ unknown_reason: reason,+ });+ if (targetIndex !== 0)+ assert.equal(+ value.symbols.find((symbol) => symbol.name.display === "read_values")+ .value_meaning,+ "unknown-section-index",+ );+ assert.deepEqual(await readFile(path), bytes);+ cases++;+ }+ }+ const relative = protectedReport.relocations.find(+ (item) => item.type === 8 && item.symbol_index === 0,+ );+ assert.notEqual(relative, undefined, "Required relative relocation absent");+ const relativeOwner = protectedReport.sections[relative.section_index];+ const noSymbolTable = Buffer.from(sectionBearingBytes);+ const relativeHeader = Number(BigInt(relativeOwner.header_location.offset));+ noSymbolTable.writeBigUInt64LE(+ BigInt(relative.location.offset),+ relativeHeader + 24,+ );+ noSymbolTable.writeBigUInt64LE(+ BigInt(relative.location.bytes),+ relativeHeader + 32,+ );+ noSymbolTable.writeUInt32LE(0, relativeHeader + 40);+ const zeroSymbolPath = join(root.path, "relative-without-symbol-table");+ await writeFile(zeroSymbolPath, noSymbolTable);+ for (const mode of ["cli", "mcp"]) {+ const value = await inspect(mode, zeroSymbolPath);+ const reported = value.relocations.find(+ (item) => item.section_index === relative.section_index,+ );+ assert.equal(reported.symbol_table_index, 0);+ assert.equal(reported.symbol_index, 0);+ assert.equal(reported.symbol_reference_meaning, "zero-symbol-value");+ assert.deepEqual(await readFile(zeroSymbolPath), noSymbolTable);+ cases++;+ }+ const undersizedProgramHeader = Buffer.from(sectionBearingBytes);+ const missingTargetSection = Buffer.from(object);+ missingTargetSection.writeUInt32LE(+ relocatable.sections.length + 100,+ Number(BigInt(relocationSection.header_location.offset)) + 44,+ );+ undersizedProgramHeader.writeUInt16LE(8, 54);+ undersizedProgramHeader.writeUInt16LE(1, 56);+ const symbolTable = relocatable.sections.find(+ (section) => section.type === "SHT_SYMTAB",+ );+ assert.notEqual(symbolTable, undefined);+ const symbol = relocatable.symbols.find(+ (item) => item.name.display === "read_values",+ );+ assert.notEqual(symbol, undefined);+ const extendedWords = Buffer.alloc(+ Number(BigInt(symbolTable.size) / BigInt(symbolTable.entry_size)) * 4,+ );+ extendedWords.writeUInt32LE(symbol.section_index, symbol.entry_index * 4);+ const headers = Buffer.from(+ object.subarray(+ Number(BigInt(relocatable.sections[0].header_location.offset)),+ Number(+ BigInt(relocatable.sections.at(-1).header_location.offset) ++ BigInt(relocatable.sections.at(-1).header_location.bytes),+ ),+ ),+ );+ const extendedHeader = Buffer.alloc(64);+ extendedHeader.writeUInt32LE(18, 4); // SHT_SYMTAB_SHNDX+ extendedHeader.writeBigUInt64LE(BigInt(object.length), 24);+ extendedHeader.writeBigUInt64LE(BigInt(extendedWords.length), 32);+ extendedHeader.writeUInt32LE(symbolTable.index, 40);+ extendedHeader.writeBigUInt64LE(4n, 48);+ extendedHeader.writeBigUInt64LE(4n, 56);+ const extendedObject = Buffer.concat([+ object,+ extendedWords,+ headers,+ extendedHeader,+ ]);+ extendedObject.writeBigUInt64LE(+ BigInt(object.length + extendedWords.length),+ 40,+ );+ extendedObject.writeUInt16LE(relocatable.sections.length + 1, 60);+ extendedObject.writeUInt16LE(+ 0xffff,+ Number(BigInt(symbol.location.offset)) + 6,+ );+ const extendedPath = join(root.path, "external-symbol-index.o");+ await writeFile(extendedPath, extendedObject);+ for (const mode of ["cli", "mcp"]) {+ const value = await inspect(mode, extendedPath);+ const reported = value.symbols.find(+ (item) => item.name.display === "read_values",+ );+ assert.equal(reported.section_index, 0xffff);+ assert.equal(reported.value_meaning, "unknown-section-index");+ assert.ok(+ value.sections.some((section) => section.type === "SHT_SYMTAB_SHNDX"),+ );+ assert.deepEqual(await readFile(extendedPath), extendedObject);+ cases++;+ }+ for (const [name, option, expected] of [+ ["address-space", "--as=2147483648", '"address_space_bytes": 2147483648'],+ ["cpu", "--cpu=20", '"cpu_seconds": 20'],+ ["file-size", "--fsize=33554432", '"file_size_bytes": 33554432'],+ ]) {+ const wrapper = join(root.path, `python-limit-${name}`);+ const quotedPython = "'" + python.replaceAll("'", "'\"'\"'") + "'";+ await writeFile(+ wrapper,+ `#!/bin/sh\nexec /usr/bin/prlimit ${option} -- ${quotedPython} "$@"\n`,+ { mode: 0o700 },+ );+ const limitedEnvironment = { ...environment, REA_PWNTOOLS_PYTHON: wrapper };+ const limitedClient = new Client({+ name: "limited-layout-verifier",+ version: "1",+ });+ const limitedTransport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "mcp"],+ env: limitedEnvironment,+ stderr: "pipe",+ });+ try {+ await limitedClient.connect(limitedTransport);+ for (const mode of ["cli", "mcp"]) {+ const value = await inspect(+ mode,+ join(root.path, "protected"),+ undefined,+ limitedEnvironment,+ limitedClient,+ );+ assert.ok(value.limitations.some((item) => item.includes(expected)));+ cases++;+ }+ } finally {+ try {+ await limitedClient.close();+ } finally {+ await limitedTransport.close();+ }+ }+ }+ const unsupported = Buffer.from(object);+ const originalSectionOffset = Number(object.readBigUInt64LE(40));+ const sectionSize = object.readUInt16LE(58);+ const originalSectionCount = object.readUInt16LE(60);+ const sectionCount = 30000;+ const sectionOffset = Math.ceil(object.length / 8) * 8;+ const sectionHeavy = Buffer.alloc(sectionOffset + sectionCount * sectionSize);+ object.copy(sectionHeavy);+ object.copy(+ sectionHeavy,+ sectionOffset,+ originalSectionOffset,+ originalSectionOffset + originalSectionCount * sectionSize,+ );+ for (let index = originalSectionCount; index < sectionCount; index++) {+ sectionHeavy.writeUInt32LE(1, sectionOffset + index * sectionSize + 4);+ sectionHeavy.writeBigUInt64LE(1n, sectionOffset + index * sectionSize + 48);+ }+ sectionHeavy.writeBigUInt64LE(BigInt(sectionOffset), 40);+ sectionHeavy.writeUInt16LE(sectionCount, 60);+ const sectionHeavyPath = join(root.path, "section-heavy.o");+ await writeFile(sectionHeavyPath, sectionHeavy);+ const memoryWrapper = join(root.path, "python-memory-constraint");+ const quotedPython = "'" + python.replaceAll("'", "'\"'\"'") + "'";+ await writeFile(+ memoryWrapper,+ `#!/bin/sh\nexec /usr/bin/prlimit --as=100663296 -- ${quotedPython} "$@"\n`,+ { mode: 0o700 },+ );+ const memoryEnvironment = {+ ...environment,+ REA_PWNTOOLS_PYTHON: memoryWrapper,+ };+ const memoryClient = new Client({+ name: "memory-layout-verifier",+ version: "1",+ });+ const memoryTransport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "mcp"],+ env: memoryEnvironment,+ stderr: "pipe",+ });+ try {+ await memoryClient.connect(memoryTransport);+ for (const mode of ["cli", "mcp"]) {+ const error = await inspect(+ mode,+ sectionHeavyPath,+ "resource_constraint",+ memoryEnvironment,+ memoryClient,+ );+ assert.equal(error.code, "resource_constraint");+ assert.equal(error.details.resource, "memory");+ assert.ok(+ error.details.reported_limits === null ||+ error.details.reported_limits.address_space_bytes === 100663296,+ );+ assert.equal(error.details.captured_output.truncated, false);+ assert.ok(error.remediation.action.includes("memory"));+ cases++;+ }+ assert.deepEqual(await readFile(sectionHeavyPath), sectionHeavy);+ } finally {+ try {+ await memoryClient.close();+ } finally {+ await memoryTransport.close();+ }+ }+ // Extended section numbering keeps this valid while providing enough work+ // to reach the one-second CPU limit even on faster CI runners.+ const cpuSectionCount = 300000;+ const cpuHeavy = Buffer.alloc(sectionOffset + cpuSectionCount * sectionSize);+ sectionHeavy.copy(cpuHeavy);+ for (let index = sectionCount; index < cpuSectionCount; index++) {+ cpuHeavy.writeUInt32LE(1, sectionOffset + index * sectionSize + 4);+ cpuHeavy.writeBigUInt64LE(1n, sectionOffset + index * sectionSize + 48);+ }+ cpuHeavy.writeUInt16LE(0, 60);+ cpuHeavy.writeBigUInt64LE(BigInt(cpuSectionCount), sectionOffset + 32);+ const cpuHeavyPath = join(root.path, "cpu-section-heavy.o");+ await writeFile(cpuHeavyPath, cpuHeavy);+ const cpuWrapper = join(root.path, "python-cpu-constraint");+ await writeFile(+ cpuWrapper,+ `#!/bin/sh\nexec /usr/bin/prlimit --cpu=1: --core=0: -- ${quotedPython} "$@"\n`,+ { mode: 0o700 },+ );+ const cpuEnvironment = { ...environment, REA_PWNTOOLS_PYTHON: cpuWrapper };+ const cpuClient = new Client({ name: "cpu-layout-verifier", version: "1" });+ const cpuTransport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "mcp"],+ env: cpuEnvironment,+ stderr: "pipe",+ });+ try {+ await cpuClient.connect(cpuTransport);+ for (const mode of ["cli", "mcp"]) {+ const error = await inspect(+ mode,+ cpuHeavyPath,+ "resource_constraint",+ cpuEnvironment,+ cpuClient,+ );+ assert.equal(error.details.resource, "cpu");+ assert.equal(error.details.reported_limits.cpu_seconds, 1);+ assert.ok(JSON.stringify(error).includes("SIGXCPU"));+ assert.ok(error.remediation.action.includes("CPU"));+ cases++;+ }+ assert.deepEqual(await readFile(cpuHeavyPath), cpuHeavy);+ } finally {+ try {+ await cpuClient.close();+ } finally {+ await cpuTransport.close();+ }+ }+ for (const limit of [1024, 1]) {+ const wrapper = join(root.path, `python-file-size-${limit}`);+ await writeFile(+ wrapper,+ `#!/bin/sh\nexec /usr/bin/prlimit --fsize=${limit}: --core=0: -- ${quotedPython} "$@"\n`,+ { mode: 0o700 },+ );+ const fileEnvironment = { ...environment, REA_PWNTOOLS_PYTHON: wrapper };+ const fileClient = new Client({+ name: "file-size-layout-verifier",+ version: "1",+ });+ const fileTransport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "mcp"],+ env: fileEnvironment,+ stderr: "pipe",+ });+ try {+ await fileClient.connect(fileTransport);+ for (const mode of ["cli", "mcp"]) {+ const error = await inspect(+ mode,+ sectionHeavyPath,+ "resource_constraint",+ fileEnvironment,+ fileClient,+ );+ assert.equal(error.details.resource, "file-size");+ if (limit === 1024)+ assert.equal(error.details.reported_limits.file_size_bytes, limit);+ else {+ assert.equal(error.details.reported_limits, null);+ assert.ok(JSON.stringify(error).includes("limit report unavailable"));+ }+ assert.ok(error.remediation.action.includes("file-size"));+ cases++;+ }+ assert.deepEqual(await readFile(sectionHeavyPath), sectionHeavy);+ } finally {+ try {+ await fileClient.close();+ } finally {+ await fileTransport.close();+ }+ }+ }+ unsupported.writeUInt16LE(183, 18);+ const core = Buffer.from(object);+ core.writeUInt16LE(4, 16);+ for (const [name, bytes, category] of [+ ["not-elf", Buffer.from("ordinary local text"), "invalid_input"],+ ["truncated", object.subarray(0, 32), "invalid_input"],+ [+ "truncated-tables",+ object.subarray(0, object.length - 1),+ "invalid_input",+ ],+ ...zeroSymbolEntries,+ ...undersizedSymbolEntries,+ ...undersizedRelocationEntries,+ ...invalidRelocationReferences,+ ["unterminated-dynamic-segment", shortDynamic, "invalid_input"],+ ["unterminated-interpreter", unterminatedInterpreter, "invalid_input"],+ [+ "missing-relocation-target-section",+ missingTargetSection,+ "invalid_input",+ ],+ ["undersized-program-header", undersizedProgramHeader, "invalid_input"],+ ["arm64", unsupported, "unsupported_provider"],+ ["core", core, "unsupported_provider"],+ ]) {+ const path = join(root.path, name);+ await writeFile(path, bytes);+ for (const mode of ["cli", "mcp"]) {+ await inspect(mode, path, category);+ assert.deepEqual(await readFile(path), bytes);+ cases++;+ }+ }+ const packedFile = await readFile(join(root.path, "packed-relative"));+ const packedTable =+ reports.get("packed-relative").packed_relative_relocations[0];+ assert.notEqual(packedTable, undefined);+ packedFile.writeBigUInt64LE(1n, Number(BigInt(packedTable.location.offset)));+ const badPackedPath = join(root.path, "relr-bitmap-without-anchor");+ await writeFile(badPackedPath, packedFile);+ for (const mode of ["cli", "mcp"]) {+ await inspect(mode, badPackedPath, "invalid_input");+ assert.deepEqual(await readFile(badPackedPath), packedFile);+ cases++;+ }+ const brokenPython = join(root.path, "broken-configured-python");+ await writeFile(+ brokenPython,+ "#!/rea-missing-configured-python-interpreter\n",+ { mode: 0o700 },+ );+ const unmarkedLaunchers = [];+ for (const status of [75, 76]) {+ const path = join(root.path, `unmarked-launcher-${status}`);+ await writeFile(+ path,+ `#!/bin/sh\nprintf 'launcher exited ${status}\\n' >&2\nexit ${status}\n`,+ { mode: 0o700 },+ );+ unmarkedLaunchers.push(path);+ }+ for (const [configuredPython, category] of [+ [root.path, "unavailable"],+ [brokenPython, "unavailable"],+ ...unmarkedLaunchers.map((path) => [path, "execution_failure"]),+ ]) {+ const selectedEnvironment = {+ ...environment,+ REA_PWNTOOLS_PYTHON: configuredPython,+ };+ const selectedClient = new Client({+ name: "unavailable-layout-verifier",+ version: "1",+ });+ const selectedTransport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "mcp"],+ env: selectedEnvironment,+ stderr: "pipe",+ });+ try {+ await selectedClient.connect(selectedTransport);+ for (const mode of ["cli", "mcp"]) {+ const error = await inspect(+ mode,+ join(root.path, "protected"),+ category,+ selectedEnvironment,+ selectedClient,+ );+ if (category === "unavailable") {+ assert.equal(error.code, "provider_unavailable");+ assert.equal(+ error.details.rejections[0].diagnostics.executable_path,+ configuredPython,+ );+ } else {+ assert.equal(error.code, "execution_failure");+ assert.ok(JSON.stringify(error).includes("launcher exited"));+ assert.ok(JSON.stringify(error).includes("resource_failure_marker"));+ }+ cases++;+ }+ } finally {+ try {+ await selectedClient.close();+ } finally {+ await selectedTransport.close();+ }+ }+ }+ for (const mode of ["cli", "mcp"]) {+ await inspect(mode, join(root.path, "absent"), "invalid_input");+ cases++;+ }+ for (const name of ["protected", "sectionless"]) {+ const trace = join(root.path, `exec.trace.${name}`);+ await execute(+ strace,+ [+ "-ff",+ "-e",+ "trace=execve,execveat",+ "-s",+ "4096",+ "-o",+ trace,+ process.execPath,+ entrypoint,+ "inspect-binary-layout",+ join(root.path, name),+ "--json",+ ],+ {+ env: { ...environment, PATH: "/usr/bin:/bin" },+ timeout: 45_000,+ maxBuffer: 256 * 1024 * 1024,+ },+ );+ }+ const executions = [];+ for (const file of await readdir(root.path)) {+ if (!file.startsWith("exec.trace.")) continue;+ for (const line of (await readFile(join(root.path, file), "utf8")).split(+ "\n",+ )) {+ if (!/execve(?:at)?\(/.test(line)) continue;+ const match = /^execve\("([^\"]+)"/.exec(line);+ assert.notEqual(+ match,+ null,+ `Unresolved executable identity in syscall trace: ${line}`,+ );+ assert.ok(+ line.endsWith(" = 0") || / = -1 [A-Z]+/.test(line),+ `Incomplete exec observation: ${line}`,+ );+ const ownershipInspection =+ ["/usr/bin/ps", "/bin/ps"].includes(match[1]) &&+ line.includes('["ps", "-axo", "pid=,ppid=,pgid=,stat=,command="]');+ assert.ok(+ [process.execPath, python].includes(match[1]) || ownershipInspection,+ `Unexpected attempted host execution: ${line}`,+ );+ executions.push(match[1]);+ }+ }+ assert.ok(executions.includes(process.execPath));+ assert.ok(executions.includes(python));+ cases += 2;+} catch (cause) {+ failures.push(cause);+} finally {+ for (const close of [+ () => client.close(),+ () => transport.close(),+ () => root.close(),+ ]) {+ try {+ await close();+ } catch (cause) {+ failures.push(cause);+ }+ }+}+const verifier = await completeVerifierRun(run);+try {+ assert.equal(verifier.process_lineage.status, "verified");+ assert.deepEqual(verifier.process_lineage.descendants, []);+} catch (cause) {+ failures.push(cause);+}+if (failures.length > 0) {+ console.error(+ JSON.stringify(+ { status: "failed", public_cases: cases, verifier },+ null,+ 2,+ ),+ );+ throw new AggregateError(+ failures,+ "Offline binary layout verification failed; cleanup failures are retained.",+ );+}+console.log(+ JSON.stringify(+ {+ status: "passed",+ public_cases: cases,+ bootstrap_boundary_cases: bootstrapCases,+ large_index_mcp: verifyLargeMcp ? "verified" : "not-requested",+ profile: "pwntools4.15.0/pyelftools0.33/Unicorn2.1.2",+ target_execution: "exec-syscalls-verified-absent",+ verifier,+ },+ null,+ 2,+ ),+);++async function inspect(+ mode,+ path,+ category,+ selectedEnvironment = environment,+ selectedClient = client,+) {+ let envelope;+ if (mode === "mcp") {+ const response = await selectedClient.callTool(+ {+ name: "inspect_binary_layout",+ arguments: { path },+ },+ { timeout: 300_000 },+ );+ const value = JSON.parse(mcpTextValue(response));+ if (category !== undefined) {+ assert.equal(response.isError, true);+ assert.equal(value.error.category, category, JSON.stringify(value.error));+ return value.error;+ }+ assert.notEqual(response.isError, true, mcpTextValue(response));+ envelope = value.evidence;+ assert.deepEqual(value.result, envelope.normalized_result);+ } else {+ let response;+ try {+ response = await execute(+ process.execPath,+ [entrypoint, "inspect-binary-layout", path, "--json"],+ {+ env: selectedEnvironment,+ timeout: 40_000,+ maxBuffer: 256 * 1024 * 1024,+ },+ );+ } catch (cause) {+ if (category === undefined) throw cause;+ if (typeof cause.code !== "number") throw cause;+ const error = JSON.parse(cause.stdout);+ assert.equal(error.category, category, JSON.stringify(error));+ return error;+ }+ assert.equal(category, undefined, "Expected selected input to fail");+ envelope = JSON.parse(response.stdout);+ }+ const evidence = parseEvidence(envelope);+ assert.equal(evidence.subject.local_path, path);+ assert.equal(+ evidence.provider.version,+ );+ assert.deepEqual(evidence.normalized_result, evidence.raw_result);+ assert.equal(evidence.normalized_result.diagnostics.truncated, false);+ return evidence.normalized_result;+}diff --git a/skills/reverse-engineer-anything/SKILL.md b/skills/reverse-engineer-anything/SKILL.mdindex 3d4dac785..0657e88eb 100644--- a/skills/reverse-engineer-anything/SKILL.md+++ b/skills/reverse-engineer-anything/SKILL.md@@ -2,9 +2,9 @@name: reverse-engineer-anythingdescription: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.metadata:- version: "29"- tool_count: 135- catalog_digest: "bfa2ed377826f8e561d1b8a9024d4ab0cf11f09d8b1af86c80d2884c1d72dbf3"+ version: "30"+ tool_count: 136+ catalog_digest: "fc75e5d817f64311dacc23ef2bde4223fd12d2d5a9c49e93051ac9f7857b2d8c"---# REA@@ -99,6 +99,11 @@ explicit path or endpoint and do not need it.[historical captures](https://github.com/morluto/rea/blob/main/docs/web-network-captures.md) for the exact upstreamprofile and credential exclusions.- User-owned Electron runtime already open: `list_electron_targets`.+- Explicit Linux ELF file for offline layout, symbols, relocations or static+ mitigation evidence: `inspect_binary_layout`. This target-free operation uses+ caller-supplied pwntools without opening a disassembler database. Preserve its+ raw locations and inference/coverage limits; see the+ [offline binary guide](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md).- Native executable, library, or analysis database: `open_binary`, thenuse focused analysis tools directly; call `binary_overview` when metadata orinventory context is useful and available from the selected provider.diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.tsindex a2dcad5c3..ab2c25d94 100644--- a/src/application/CapabilityInventory.ts+++ b/src/application/CapabilityInventory.ts@@ -33,6 +33,7 @@ type ProviderDescriptor = ProviderCapability;export type AvailabilityPolicy = {readonly processCaptureEnabled: boolean;readonly optionalProviderLoadFailures?: OptionalProviderLoadFailures;+ readonly binaryLayoutEnabled?: boolean;readonly firmwareInspectionEnabled?: boolean;readonly firmwareExtractionEnabled?: boolean;readonly androidAnalysisEnabled?: boolean;@@ -280,6 +281,14 @@ const workflowAvailabilityFor = ({remediation:"On Linux x64, provide an absolute REA_WAKARU_COMMAND for Wakaru 1.13.0 and util-linux prlimit. No binary target is required.",};+ if (name === "inspect_binary_layout")+ return policy.binaryLayoutEnabled === true+ ? { reason: "available", remediation: null }+ : {+ reason: "provider_missing",+ remediation:+ "On Linux x64, set absolute REA_PWNTOOLS_PYTHON to caller-supplied Python with pwntools 4.15.0. No active binary target is required.",+ };if (kind === "firmware-provider") {const enabled =name === "inspect_firmware_regions"diff --git a/src/application/binaryDiagnostics/BinaryLayoutPort.ts b/src/application/binaryDiagnostics/BinaryLayoutPort.tsnew file mode 100644index 000000000..a6936a60f--- /dev/null+++ b/src/application/binaryDiagnostics/BinaryLayoutPort.ts@@ -0,0 +1,17 @@+import type { ExecutionOptions } from "../AnalysisProvider.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import type {+ BinaryLayout,+ InspectBinaryLayoutInput,+} from "../../domain/native/binaryLayout.js";+import type { Result } from "../../domain/result.js";+import type { ProviderIdentity } from "../AnalysisProvider.js";++/** Replaceable offline binary-layout provider; owns its parser and process protocol. */+export interface BinaryLayoutPort {+ readonly identity: ProviderIdentity;+ inspect(+ input: InspectBinaryLayoutInput,+ options?: ExecutionOptions,+ ): Promise<Result<BinaryLayout, AnalysisError>>;+}diff --git a/src/application/binaryDiagnostics/BinaryLayoutService.test.ts b/src/application/binaryDiagnostics/BinaryLayoutService.test.tsnew file mode 100644index 000000000..dcfad2311--- /dev/null+++ b/src/application/binaryDiagnostics/BinaryLayoutService.test.ts@@ -0,0 +1,131 @@+import { expect, it } from "vitest";+import { BinaryLayoutService } from "./BinaryLayoutService.js";+import {+ binaryLayoutFixture,+ BINARY_LAYOUT_TEST_PROVIDER,+} from "../../../tests/fixtures/binaryDiagnostics/layout.js";+import { parseEvidence } from "../../domain/evidence.js";+import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";+import { err, ok } from "../../domain/result.js";++it("binds original bytes, inline observations, unknowns and producing identity", async () => {+ const fixture = binaryLayoutFixture();+ const service = new BinaryLayoutService({+ identity: BINARY_LAYOUT_TEST_PROVIDER,+ inspect: () => Promise.resolve(ok(fixture)),+ });+ const result = await service.inspect({ path: fixture.artifact.path });+ if (!result.ok) throw result.error;+ const evidence = parseEvidence(result.value);+ expect(evidence.normalized_result).toEqual(fixture);+ expect(evidence.raw_result).toEqual(fixture);+ expect(evidence.subject?.digest.sha256).toBe(fixture.artifact.sha256);+ expect(evidence.provider).toEqual(BINARY_LAYOUT_TEST_PROVIDER);+ expect(evidence.confidence).toBe("observed");+});++it.each([+ { path: "relative.elf" },+ { path: "/selected.elf", approval: true },+ { path: 123 },+ {},+])(+ "rejects malformed selection before starting the provider: %j",+ async (input) => {+ const service = new BinaryLayoutService({+ identity: BINARY_LAYOUT_TEST_PROVIDER,+ inspect: () => {+ throw new Error("must not run");+ },+ });+ expect(await service.inspect(input)).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisInputError" },+ });+ },+);++it("preserves a provider's actionable unsupported reason", async () => {+ const failure = new AnalysisCapabilityUnavailableError(+ "fixture-layout",+ "inspect_binary_layout",+ "ELF core belongs to recorded-crash analysis.",+ );+ const service = new BinaryLayoutService({+ identity: BINARY_LAYOUT_TEST_PROVIDER,+ inspect: () => Promise.resolve(err(failure)),+ });+ expect(await service.inspect({ path: "/source.elf" })).toEqual(err(failure));+});++it("cancels before invocation and after an acquired observation", async () => {+ const controller = new AbortController();+ const service = new BinaryLayoutService({+ identity: BINARY_LAYOUT_TEST_PROVIDER,+ inspect: () => {+ controller.abort();+ return Promise.resolve(ok(binaryLayoutFixture()));+ },+ });+ expect(+ await service.inspect(+ { path: "/artifacts/source-owned.elf" },+ { signal: controller.signal },+ ),+ ).toMatchObject({+ ok: false,+ error: {+ _tag: "AnalysisCancelledError",+ capturedOutput: binaryLayoutFixture().diagnostics,+ },+ });+ const untouched = new BinaryLayoutService({+ identity: BINARY_LAYOUT_TEST_PROVIDER,+ inspect: () => {+ throw new Error("must not run");+ },+ });+ expect(+ await untouched.inspect(+ { path: "/source.elf" },+ { signal: controller.signal },+ ),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisCancelledError" } });+});++it.each(["different-path", "invalid-digest", "outside-range"])(+ "rejects provider evidence at the next boundary: %s",+ async (problem) => {+ const fixture = binaryLayoutFixture();+ if (problem === "different-path") fixture.artifact.path = "/different.elf";+ if (problem === "invalid-digest") fixture.artifact.sha256 = "unobserved";+ if (problem === "outside-range")+ fixture.segments.push({+ index: 0,+ type: "PT_LOAD",+ offset: "0x80",+ header_location: { offset: "0x0", bytes: "0x38" },+ file_backing: "file",+ file_size: "0x1",+ memory_size: "0x1",+ virtual_address: "0x20000000000001",+ physical_address: "0x0",+ alignment: "0x1",+ flags: "0x5",+ permissions: { read: true, write: false, execute: true },+ });+ const service = new BinaryLayoutService({+ identity: BINARY_LAYOUT_TEST_PROVIDER,+ inspect: () => Promise.resolve(ok(fixture)),+ });+ expect(+ await service.inspect({ path: "/artifacts/source-owned.elf" }),+ ).toMatchObject({+ ok: false,+ error: {+ _tag: "AnalysisOutputError",+ capturedOutput: fixture.diagnostics,+ },+ });+ },+);diff --git a/src/application/binaryDiagnostics/BinaryLayoutService.ts b/src/application/binaryDiagnostics/BinaryLayoutService.tsnew file mode 100644index 000000000..7fb1d308e--- /dev/null+++ b/src/application/binaryDiagnostics/BinaryLayoutService.ts@@ -0,0 +1,91 @@+import { isAbsolute } from "node:path";+import type { ExecutionOptions } from "../AnalysisProvider.js";+import type { BinaryLayoutPort } from "./BinaryLayoutPort.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import {+ AnalysisCancelledError,+ AnalysisInputError,+ AnalysisOutputError,+} from "../../domain/analysisErrorCore.js";+import { createEvidence, type Evidence } from "../../domain/evidence.js";+import {+ inspectBinaryLayoutInputSchema,+ binaryLayoutSchema,+} from "../../domain/native/binaryLayout.js";+import { projectInputIssues } from "../../domain/inputIssueProjection.js";+import { err, ok, type Result } from "../../domain/result.js";++const OPERATION = "inspect_binary_layout";++/** Shared CLI/MCP validation and Evidence composition for offline layout inspection. */+export class BinaryLayoutService {+ constructor(readonly provider: BinaryLayoutPort) {}++ /** Bind complete observations to the caller-selected artifact before creating Evidence. */+ async inspect(+ rawInput: unknown,+ options?: ExecutionOptions,+ ): Promise<Result<Evidence, AnalysisError>> {+ if (options?.signal?.aborted)+ return err(new AnalysisCancelledError(OPERATION));+ const input = inspectBinaryLayoutInputSchema.safeParse(rawInput);+ if (!input.success)+ return err(+ new AnalysisInputError(+ OPERATION,+ { cause: input.error },+ projectInputIssues(input.error.issues, rawInput),+ ),+ );+ if (!isAbsolute(input.data.path))+ return err(+ new AnalysisInputError(OPERATION, undefined, [+ {+ path: ["path"],+ reason: "invalid_format",+ message: "Expected an absolute filesystem path on this host.",+ },+ ]),+ );+ const inspected = await this.provider.inspect(input.data, options);+ if (!inspected.ok) return inspected;+ const diagnostics = binaryLayoutSchema.shape.diagnostics.safeParse(+ inspected.value.diagnostics,+ );+ const outputOptions = diagnostics.success+ ? { capturedOutput: diagnostics.data }+ : undefined;+ if (options?.signal?.aborted)+ return err(new AnalysisCancelledError(OPERATION, outputOptions));+ const report = binaryLayoutSchema.safeParse(inspected.value);+ if (!report.success || report.data.artifact.path !== input.data.path)+ return err(+ new AnalysisOutputError(+ OPERATION,+ "Binary layout provider returned malformed evidence or changed the selected artifact identity.",+ outputOptions,+ ),+ );+ const value = report.data;+ return ok(+ createEvidence(+ {+ path: value.artifact.path,+ format: "elf",+ architecture: "x86_64",+ sha256: value.artifact.sha256,+ },+ this.provider.identity,+ {+ operation: OPERATION,+ parameters: input.data,+ result: value,+ rawResult: value,+ confidence: "observed",+ limitations: value.limitations,+ locations: [{ kind: "artifact-path", path: value.artifact.path }],+ },+ ),+ );+ }+}diff --git a/src/cli.ts b/src/cli.tsindex 10f1a0949..6fa48dd33 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -1,3 +1,4 @@+import { registerBinaryDiagnosticsCommands } from "./cli/binaryDiagnosticsCommands.js";import { Cli } from "incur";import { createLogger, parseLogLevel } from "./logger.js";@@ -59,6 +60,7 @@ export const createCli = (registerManagedCommands(cli, logger);registerAndroidCommands(cli, logger, environment);registerFirmwareCommands(cli, logger, environment);+ registerBinaryDiagnosticsCommands(cli, logger, environment);registerEvidenceCommands(cli, logger);registerProcessCommands(cli, logger, environment);registerBrowserCommands(cli, logger);diff --git a/src/cli/binaryDiagnosticsCommands.ts b/src/cli/binaryDiagnosticsCommands.tsnew file mode 100644index 000000000..e6f63f7ef--- /dev/null+++ b/src/cli/binaryDiagnosticsCommands.ts@@ -0,0 +1,35 @@+import { z } from "incur";+import { resolve } from "node:path";+import { createBinaryLayoutService } from "../composition/binaryDiagnostics.js";+import { CLI_COMMANDS } from "../cliCommandNames.js";+import { logCliCommand } from "../cliLogging.js";+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";+import type { Logger } from "../logger.js";+import type { CliInstance } from "./types.js";+import { withCommandCancellation } from "./commandCancellation.js";++/** Inspect operator-selected files through the same shared workflow as MCP. */+export const registerBinaryDiagnosticsCommands = (+ cli: CliInstance,+ logger: Logger,+ environment: Readonly<NodeJS.ProcessEnv>,+): void => {+ const service = createBinaryLayoutService(environment);+ cli.command(CLI_COMMANDS.inspectBinaryLayout, {+ description:+ "Inspect binary file/linked layout without executing the selected object",+ args: z.object({+ path: z.string().describe("Local ELF binary or relocatable object"),+ }),+ run: ({ args }) =>+ withCommandCancellation((signal) =>+ logCliCommand(logger, CLI_COMMANDS.inspectBinaryLayout, async () => {+ const result = await service.inspect(+ { path: resolve(args.path) },+ { signal },+ );+ return result.ok ? result.value : projectAnalysisError(result.error);+ }),+ ),+ });+};diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.tsindex 4006827ea..021ff04fc 100644--- a/src/cliCommandNames.ts+++ b/src/cliCommandNames.ts@@ -37,6 +37,7 @@ export const CLI_COMMANDS = Object.freeze({resolveNativeCallTargets: "resolve-native-call-targets",inspectAssetCatalog: "inspect-asset-catalog",inspectManagedArtifact: "inspect-managed-artifact",+ inspectBinaryLayout: "inspect-binary-layout",inspectFirmwareRegions: "inspect-firmware-regions",extractFirmware: "extract-firmware",inspectAndroidPackage: "inspect-android-package",diff --git a/src/composition/binaryDiagnostics.ts b/src/composition/binaryDiagnostics.tsnew file mode 100644index 000000000..cece28a5e--- /dev/null+++ b/src/composition/binaryDiagnostics.ts@@ -0,0 +1,8 @@+import { BinaryLayoutService } from "../application/binaryDiagnostics/BinaryLayoutService.js";+import { PwntoolsLayoutProvider } from "../native/pwntools/PwntoolsLayoutProvider.js";++/** Compose the offline adapter without import-time I/O or dependency acquisition. */+export const createBinaryLayoutService = (+ environment: Readonly<NodeJS.ProcessEnv> = process.env,+): BinaryLayoutService =>+ new BinaryLayoutService(new PwntoolsLayoutProvider(environment));diff --git a/src/contracts/contractSnapshot.test.ts b/src/contracts/contractSnapshot.test.tsindex f923cc3e9..82ee4acd9 100644--- a/src/contracts/contractSnapshot.test.ts+++ b/src/contracts/contractSnapshot.test.ts@@ -1,3 +1,4 @@+import { BINARY_DIAGNOSTICS_TOOL_CONTRACTS } from "./native/binaryDiagnosticsToolContracts.js";import { describe, expect, it } from "vitest";import { z } from "zod";@@ -69,6 +70,7 @@ describe("tool contract surface", () => {...OFFICIAL_TOOL_CONTRACTS,...ENHANCED_TOOL_CONTRACTS,...NATIVE_TOOL_CONTRACTS,+ ...BINARY_DIAGNOSTICS_TOOL_CONTRACTS,...ARTIFACT_TOOL_CONTRACTS,...ANDROID_TOOL_CONTRACTS,...FIRMWARE_TOOL_CONTRACTS,diff --git a/src/contracts/errorSchemas.ts b/src/contracts/errorSchemas.tsindex 3ea7f5c76..da7dd924e 100644--- a/src/contracts/errorSchemas.ts+++ b/src/contracts/errorSchemas.ts@@ -9,6 +9,7 @@ const categorySchema = z.enum(["truncated","cancelled","timeout",+ "resource_constraint","unavailable","execution_failure",]);@@ -38,6 +39,7 @@ export const analysisErrorProjectionSchema = z.discriminatedUnion("code", [generic("capability_unavailable"),generic("provider_unavailable"),generic("provider_timeout"),+ generic("resource_constraint"),generic("cancelled"),z.object({diff --git a/src/contracts/native/binaryDiagnosticsToolContracts.ts b/src/contracts/native/binaryDiagnosticsToolContracts.tsnew file mode 100644index 000000000..c49780c03--- /dev/null+++ b/src/contracts/native/binaryDiagnosticsToolContracts.ts@@ -0,0 +1,26 @@+import {+ inspectBinaryLayoutInputSchema,+ binaryLayoutSchema,+} from "../../domain/native/binaryLayout.js";+import type { ToolContract } from "../toolContractTypes.js";+import { toolContractMetadata } from "../toolEffects.js";+import { evidenceResultOf } from "../toolOutputSchemas.js";++/** Offline binary diagnostics are independent of macOS process/UI providers. */+export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [+ {+ name: "inspect_binary_layout",+ ...toolContractMetadata("inspect_binary_layout"),+ kind: "native-provider",+ description:+ "Inspect an explicit local binary without launching it as a host process. Returns file-backed section/segment ranges, linked addresses, original symbol/REL/RELA table identities, complete encoded RELR tables and upstream-derived offsets with unknown per-word locations/addends, raw name bytes, dependency/interpreter names and static mitigation inferences inline with artifact SHA-256 Evidence. Initial profile: ELF64 x86-64 little-endian EXEC/DYN/REL on Linux x64 via caller-supplied Python with unchanged pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2. Runtime addresses/library paths, overall relocation inventory completeness and complete derived GOT/PLT coverage remain unknown. Zero executable entry values mean absence; relocatable entries are not applicable. Upstream can emulate PLT instructions with Unicorn for derived static maps. Uses bounded complete output and owned temporary files/processes; malformed, unsupported or oversized objects return no partial success.",+ inputSchema: inspectBinaryLayoutInputSchema,+ outputSchema: evidenceResultOf(binaryLayoutSchema),+ examples: [+ {+ title: "Inspect ELF linked and file layout",+ input: { path: "/artifacts/application.elf" },+ },+ ],+ },+] as const satisfies readonly ToolContract[];diff --git a/src/contracts/toolContracts.test.ts b/src/contracts/toolContracts.test.tsindex 449e5f785..44c1e9abd 100644--- a/src/contracts/toolContracts.test.ts+++ b/src/contracts/toolContracts.test.ts@@ -1,3 +1,4 @@+import { BINARY_DIAGNOSTICS_TOOL_CONTRACTS } from "./native/binaryDiagnosticsToolContracts.js";import { describe, expect, it } from "vitest";import { ENHANCED_TOOL_CONTRACTS } from "./enhancedToolContracts.js";@@ -23,6 +24,7 @@ const GROUPS = {official: OFFICIAL_TOOL_CONTRACTS,enhanced: ENHANCED_TOOL_CONTRACTS,native: NATIVE_TOOL_CONTRACTS,+ binary_diagnostics: BINARY_DIAGNOSTICS_TOOL_CONTRACTS,artifact: ARTIFACT_TOOL_CONTRACTS,managed: MANAGED_TOOL_CONTRACTS,android: ANDROID_TOOL_CONTRACTS,diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.tsindex 40ed7a6db..370c83efc 100644--- a/src/contracts/toolContracts.ts+++ b/src/contracts/toolContracts.ts@@ -1,3 +1,4 @@+import { BINARY_DIAGNOSTICS_TOOL_CONTRACTS } from "./native/binaryDiagnosticsToolContracts.js";import { NATIVE_TOOL_CONTRACTS } from "./native/nativeToolContracts.js";import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";import { MANAGED_TOOL_CONTRACTS } from "./managed/managedToolContracts.js";@@ -23,6 +24,7 @@ export const TOOL_CONTRACTS = [...OFFICIAL_TOOL_CONTRACTS,...ENHANCED_TOOL_CONTRACTS,...NATIVE_TOOL_CONTRACTS,+ ...BINARY_DIAGNOSTICS_TOOL_CONTRACTS,...ARTIFACT_TOOL_CONTRACTS,...MANAGED_TOOL_CONTRACTS,...ANDROID_TOOL_CONTRACTS,diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.tsindex a5c30788d..5db06293e 100644--- a/src/contracts/toolEffects.ts+++ b/src/contracts/toolEffects.ts@@ -65,6 +65,11 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {launchesProcess: true,accessesNetwork: true,}),+ inspect_binary_layout: effects({+ mutatesSession: true,+ writesFilesystem: true,+ launchesProcess: true,+ }),inspect_firmware_regions: effects({mutatesSession: true,launchesProcess: true,diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.tsindex 33db95a58..90843234b 100644--- a/src/domain/analysisErrorBase.ts+++ b/src/domain/analysisErrorBase.ts@@ -8,6 +8,7 @@ const ANALYSIS_ERROR_TAGS = ["AnalysisCapabilityUnavailableError","AnalysisCancelledError","AnalysisTimeoutError",+ "AnalysisResourceConstraintError","ProviderSelectionError","ProviderAdapterError","BrowserObservationError",@@ -30,8 +31,28 @@ const ANALYSIS_ERROR_TAGS = [/** Stable tag for an expected analysis failure. */export type AnalysisErrorTag = (typeof ANALYSIS_ERROR_TAGS)[number];+/** Retained command output associated with a typed failure; truncation stays explicit. */+export interface AnalysisCapturedOutput {+ readonly stdout: string;+ readonly stderr: string;+ readonly truncated: boolean;+}++/** Optional provider-neutral context that must survive typed error projection. */+export interface AnalysisErrorOptions extends ErrorOptions {+ readonly capturedOutput?: AnalysisCapturedOutput;+}+/** Base class for expected analysis, provider, and session failures. */export abstract class AnalysisError extends Error {+ readonly capturedOutput: AnalysisCapturedOutput | undefined;+ constructor(message: string, options?: AnalysisErrorOptions) {+ super(message, options);+ this.capturedOutput =+ options?.capturedOutput === undefined+ ? undefined+ : { ...options.capturedOutput };+ }abstract readonly _tag: AnalysisErrorTag;readonly userMessage: string | undefined = undefined;readonly userCategory: "cancelled" | undefined = undefined;diff --git a/src/domain/analysisErrorCore.ts b/src/domain/analysisErrorCore.tsindex dd89321f0..691347fac 100644--- a/src/domain/analysisErrorCore.ts+++ b/src/domain/analysisErrorCore.ts@@ -1,5 +1,23 @@import type { JsonValue } from "./jsonValue.js";-import { AnalysisError } from "./analysisErrorBase.js";+import {+ AnalysisError,+ type AnalysisErrorOptions,+} from "./analysisErrorBase.js";++/** Provider reported a resource failure, distinct from malformed input or unsupported coverage. */+export class AnalysisResourceConstraintError extends AnalysisError {+ readonly _tag = "AnalysisResourceConstraintError";++ constructor(+ readonly operation: string,+ readonly resource: "memory" | "cpu" | "file-size",+ readonly reason: string,+ readonly reportedLimits: Readonly<Record<string, JsonValue>> | null,+ options?: AnalysisErrorOptions,+ ) {+ super(`Resource constraint during ${operation}: ${reason}`, options);+ }+}/** Provider-neutral invalid analysis input or output at an application boundary. */export class AnalysisProtocolError extends AnalysisError {@@ -12,7 +30,7 @@ export class AnalysisInputError extends AnalysisError {constructor(readonly operation: string,- options?: ErrorOptions,+ options?: AnalysisErrorOptions,readonly issues: readonly AnalysisInputIssue[] = [],) {super(`Invalid analysis input for ${operation}`, options);@@ -43,7 +61,7 @@ export class AnalysisOutputError extends AnalysisError {constructor(readonly operation: string,readonly reason: string,- options?: ErrorOptions,+ options?: AnalysisErrorOptions,) {super(`Invalid analysis output for ${operation}: ${reason}`, options);}@@ -58,7 +76,7 @@ export class AnalysisCapabilityUnavailableError extends AnalysisError {readonly providerId: string,readonly operation: string,readonly reason: string,- options?: ErrorOptions & { readonly userMessage?: string },+ options?: AnalysisErrorOptions & { readonly userMessage?: string },) {super(`Provider ${providerId} cannot execute ${operation}: ${reason}`,@@ -72,8 +90,11 @@ export class AnalysisCapabilityUnavailableError extends AnalysisError {export class AnalysisCancelledError extends AnalysisError {readonly _tag = "AnalysisCancelledError";- constructor(readonly operation: string) {- super(`Analysis operation was cancelled: ${operation}`);+ constructor(+ readonly operation: string,+ options?: AnalysisErrorOptions,+ ) {+ super(`Analysis operation was cancelled: ${operation}`, options);}}@@ -84,9 +105,11 @@ export class AnalysisTimeoutError extends AnalysisError {constructor(readonly operation: string,readonly timeoutMs: number,+ options?: AnalysisErrorOptions,) {super(`Analysis operation timed out after ${String(timeoutMs)}ms: ${operation}`,+ options,);}}diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.tsindex f4baf9f18..af486b87b 100644--- a/src/domain/analysisErrorPresentation.ts+++ b/src/domain/analysisErrorPresentation.ts@@ -2,6 +2,7 @@ import {AnalysisAccessDeniedError,AnalysisArtifactChangedError,AnalysisInputError,+ AnalysisResourceConstraintError,} from "./analysisErrorCore.js";import { ArtifactOperationError } from "./artifactOperationError.js";import {@@ -32,6 +33,12 @@ import { type AnalysisErrorProjection } from "./analysisErrorProjection.js";export const analysisErrorRemediationAction = (error: AnalysisError,): string => {+ if (error instanceof AnalysisResourceConstraintError)+ return error.resource === "cpu"+ ? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."+ : error.resource === "file-size"+ ? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits."+ : "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits.";if (error instanceof HopperTimeoutError)return error.providerState === "busy"? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."@@ -123,12 +130,14 @@ const STATIC_ERROR_CATEGORIES: Readonly<AnalysisCancelledError: "cancelled",HopperCancelledError: "cancelled",AnalysisTimeoutError: "timeout",+ AnalysisResourceConstraintError: "resource_constraint",HopperTimeoutError: "timeout",NoBinaryOpenError: "unavailable",BinaryTargetError: "unavailable",};export const analysisErrorUserMessage = (error: AnalysisError): string => {+ if (error instanceof AnalysisResourceConstraintError) return error.reason;if (error instanceof AnalysisAccessDeniedError)return "Host filesystem permissions denied read access to the selected path.";if (error instanceof AnalysisArtifactChangedError)@@ -263,6 +272,7 @@ const KNOWN_ERROR_TAGS = {AnalysisCapabilityUnavailableError: true,AnalysisCancelledError: true,AnalysisTimeoutError: true,+ AnalysisResourceConstraintError: true,ProviderSelectionError: true,ProviderAdapterError: true,BrowserObservationError: true,diff --git a/src/domain/analysisErrorProjection.test.ts b/src/domain/analysisErrorProjection.test.tsindex 6b83265a2..e0952a7f3 100644--- a/src/domain/analysisErrorProjection.test.ts+++ b/src/domain/analysisErrorProjection.test.ts@@ -3,6 +3,9 @@ import {AnalysisCapabilityUnavailableError,AnalysisInputError,AnalysisOutputError,+ AnalysisCancelledError,+ AnalysisTimeoutError,+ AnalysisResourceConstraintError,} from "./analysisErrorCore.js";import { ArtifactOperationError } from "./artifactOperationError.js";import { BinaryTargetError } from "./configurationErrors.js";@@ -16,6 +19,87 @@ import {import { ProviderAdapterError } from "./providerAdapterError.js";import { UnknownRegistryError } from "./unknownRegistryError.js";import { projectAnalysisError } from "./analysisErrorProjection.js";+import { ProviderSelectionError } from "./providerSelectionError.js";+import { analysisErrorProjectionSchema } from "../contracts/errorSchemas.js";++const retainedOutput = {+ stdout: "selected output\u0000",+ stderr: "upstream warning",+ truncated: true,+};++it.each([+ ["memory", null],+ ["memory", { address_space_bytes: 67108864 }],+ ["cpu", null],+ ["cpu", { cpu_seconds: 1 }],+ ["file-size", null],+ ["file-size", { file_size_bytes: 1024 }],+] as const)(+ "projects reported %s constraints with observed or unknown limits: %j",+ (resource, limits) => {+ const projected = projectAnalysisError(+ new AnalysisResourceConstraintError(+ "inspect_binary_layout",+ resource,+ resource === "memory"+ ? "Memory allocation failed; exact cause unknown."+ : "Observed SIGXCPU; exact signal cause unknown.",+ limits,+ { capturedOutput: retainedOutput },+ ),+ );+ expect(projected).toMatchObject({+ code: "resource_constraint",+ category: "resource_constraint",+ retryable: false,+ details: {+ resource,+ reported_limits: limits,+ captured_output: retainedOutput,+ },+ });+ expect(projected.remediation.action).toContain(+ resource === "cpu"+ ? "CPU"+ : resource === "file-size"+ ? "file-size"+ : "memory",+ );+ expect(projected.remediation.action).not.toContain("doctor");+ expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(+ true,+ );+ },+);+it.each([+ new AnalysisInputError("inspect", { capturedOutput: retainedOutput }),+ new AnalysisOutputError("inspect", "invalid reply", {+ capturedOutput: retainedOutput,+ }),+ new AnalysisCapabilityUnavailableError(+ "provider",+ "inspect",+ "unsupported profile",+ { capturedOutput: retainedOutput },+ ),+ new AnalysisCancelledError("inspect", { capturedOutput: retainedOutput }),+ new AnalysisTimeoutError("inspect", 30, { capturedOutput: retainedOutput }),+ new ProviderSelectionError({+ operation: "inspect",+ reason: "provider_unavailable",+ requestedProviderId: "provider",+ candidateIds: [],+ capturedOutput: retainedOutput,+ }),+])(+ "retains captured output without changing the typed primary failure: $._tag",+ (failure) => {+ expect(projectAnalysisError(failure).details?.captured_output).toEqual(+ retainedOutput,+ );+ },+);describe("analysis error projection: provider failures", () => {it("projects the primary browser failure alongside incomplete cleanup", () => {diff --git a/src/domain/analysisErrorProjection.ts b/src/domain/analysisErrorProjection.tsindex 2f61a932f..848b10275 100644--- a/src/domain/analysisErrorProjection.ts+++ b/src/domain/analysisErrorProjection.ts@@ -14,6 +14,7 @@ import {AnalysisInputError,AnalysisOutputError,AnalysisTimeoutError,+ AnalysisResourceConstraintError,} from "./analysisErrorCore.js";import { ArtifactOperationError } from "./artifactOperationError.js";import { BinaryTargetError } from "./configurationErrors.js";@@ -39,7 +40,11 @@ export const projectAnalysisError = (): AnalysisErrorProjection => {assertKnownAnalysisErrorTag(error._tag);const code = errorCode(error);- const details = errorDetails(error);+ const primaryDetails = errorDetails(error);+ const details =+ error.capturedOutput === undefined+ ? primaryDetails+ : { ...primaryDetails, captured_output: { ...error.capturedOutput } };return {code,category: analysisErrorCategory(error),@@ -138,6 +143,7 @@ const STATIC_ERROR_CODES = {AnalysisCancelledError: "cancelled",HopperCancelledError: "cancelled",AnalysisTimeoutError: "provider_timeout",+ AnalysisResourceConstraintError: "resource_constraint",HopperTimeoutError: "provider_timeout",HopperProcessError: "provider_unavailable",HopperStartError: "provider_unavailable",@@ -181,6 +187,13 @@ const errorDetails = (const requestErrorDetails = (error: AnalysisError,): Readonly<Record<string, JsonValue>> | undefined => {+ if (error instanceof AnalysisResourceConstraintError)+ return {+ operation: error.operation,+ resource: error.resource,+ reason: error.reason,+ reported_limits: error.reportedLimits,+ };if (error instanceof AnalysisArtifactChangedError)return {operation: error.operation,@@ -409,6 +422,7 @@ export interface AnalysisErrorProjection extends Readonly<| "capability_unavailable"| "provider_unavailable"| "provider_timeout"+ | "resource_constraint"| "cancelled"| "artifact_integrity_mismatch"| "artifact_operation_failed"@@ -427,6 +441,7 @@ export interface AnalysisErrorProjection extends Readonly<| "truncated"| "cancelled"| "timeout"+ | "resource_constraint"| "unavailable"| "execution_failure";readonly message: string;diff --git a/src/domain/native/binaryLayout.test.ts b/src/domain/native/binaryLayout.test.tsnew file mode 100644index 000000000..9f8f970e0--- /dev/null+++ b/src/domain/native/binaryLayout.test.ts@@ -0,0 +1,362 @@+import { expect, it } from "vitest";+import { binaryLayoutSchema, type BinaryLayout } from "./binaryLayout.js";++const report = () => ({+ artifact: { path: "/fixture.elf", sha256: "a".repeat(64), bytes: 128 },+ format: "elf",+ architecture: { machine: "EM_X86_64", bits: 64, byte_order: "little" },+ image_type: "ET_EXEC",+ entry_point: {+ reported_value: "0x20000000000001",+ meaning: "linked-virtual-address",+ execution_status: "unknown",+ },+ runtime_load_base: null,+ sections: [+ {+ index: 0,+ name: {+ display: "opaque",+ bytes_base64: "b3BhcXVl",+ location: { offset: "0x40", bytes: "0x7" },+ unknown_reason: null,+ },+ name_offset: "0x0",+ type: "SHT_NOBITS",+ header_location: { offset: "0x0", bytes: "0x40" },+ address: "0x20000000000001",+ offset: "0xffffffffffffffff",+ size: "0x2000",+ alignment: "0x1",+ flags: "0x3",+ link: 0,+ info: 0,+ entry_size: "0x0",+ file_backing: "none",+ },+ ],+ segments: [],+ symbols: [],+ relocations: [],+ packed_relative_relocations: [],+ relocation_inventory_completeness: "unknown",+ linkage: {+ needed_libraries: [],+ interpreters: [],+ got: [],+ plt: [],+ convenience_maps_completeness: "unknown",+ runtime_library_paths: null,+ },+ mitigations: {+ evidence_kind: "inferred",+ position_independent: false,+ nx_indicator: null,+ executable_stack_indicator: false,+ stack_canary_indicator: false,+ relro: null,+ },+ diagnostics: { stdout: "", stderr: "", truncated: false },+ limitations: [],+});++it("retains high linked values and NOBITS without inventing file backing", () => {+ const value = binaryLayoutSchema.parse(report());+ expect(value.entry_point.reported_value).toBe("0x20000000000001");+ expect(value.sections[0]?.offset).toBe("0xffffffffffffffff");+ expect(value.runtime_load_base).toBeNull();+});++it.each([+ "file-backed-outside",+ "header-outside",+ "wrong-index",+ "noncanonical-base64",+ "wrong-machine",+ "outside-elf64",+])("rejects a malformed source representation: %s", (problem) => {+ const value = report();+ const section = value.sections[0];+ if (section === undefined) throw new Error("section missing");+ if (problem === "file-backed-outside") section.file_backing = "file";+ if (problem === "header-outside") section.header_location.offset = "0x80";+ if (problem === "wrong-index") section.index = 1;+ if (problem === "wrong-machine") value.architecture.machine = "EM_AARCH64";+ if (problem === "outside-elf64")+ value.entry_point.reported_value = "0x10000000000000000";+ if (problem === "noncanonical-base64") section.name.bytes_base64 = "AR==";+ expect(binaryLayoutSchema.safeParse(value).success).toBe(false);+});++it.each([+ ["PT_NULL", "0xffffffffffffffff", "none", null, true],+ ["PT_LOAD", "0x0", "none", { read: true, write: true, execute: false }, true],+ [+ "PT_LOAD",+ "0x1",+ "file",+ { read: true, write: false, execute: false },+ false,+ ],+ ["PT_NULL", "0x1", "file", null, false],+ [+ "PT_NULL",+ "0x1",+ "none",+ { read: false, write: false, execute: false },+ false,+ ],+ [+ "PT_LOAD",+ "0x1",+ "none",+ { read: true, write: false, execute: false },+ false,+ ],+])(+ "validates actual segment backing/meaning for %s size %s",+ (type, fileSize, backing, permissions, valid) => {+ const value = {+ ...report(),+ segments: [+ {+ index: 0,+ type,+ header_location: { offset: "0x0", bytes: "0x38" },+ offset: "0xffffffffffffffff",+ file_size: fileSize,+ memory_size: fileSize,+ virtual_address: "0x0",+ physical_address: "0x0",+ alignment: "0x0",+ flags: "0x0",+ file_backing: backing,+ permissions,+ },+ ],+ };+ expect(binaryLayoutSchema.safeParse(value).success).toBe(valid);+ },+);++it.each([+ ["ET_EXEC", "0x0", "absent", true],+ ["ET_DYN", "0x0", "linked-virtual-address", false],+ ["ET_REL", "0x0", "not-applicable", true],+ ["ET_EXEC", "0x1", "absent", false],+])(+ "validates actual entry meaning: %s %s %s",+ (imageType, entry, meaning, valid) => {+ expect(+ binaryLayoutSchema.safeParse({+ ...report(),+ image_type: imageType,+ entry_point: {+ reported_value: entry,+ meaning,+ execution_status: "unknown",+ },+ }).success,+ ).toBe(valid);+ },+);++it.each([+ "valid",+ "byte-length",+ "section-identity",+ "decoded-order",+ "noncanonical-bytes",+])(+ "retains original packed bytes and derived offset provenance: %s",+ (problem) => {+ const value = report();+ const section = value.sections[0];+ if (section === undefined) throw new Error("section missing");+ section.type = "SHT_RELR";+ section.file_backing = "file";+ section.offset = "0x60";+ section.size = "0x8";+ const table = {+ section_index: 0,+ location: { offset: "0x60", bytes: "0x8" },+ encoded_bytes_base64: "AAAAAAAAAAA=",+ entries: [{ decoded_index: 0, reported_offset: "0x20000000000001" }],+ offset_meaning: "linked-virtual-address",+ evidence_kind: "derived",+ entry_source_locations: null,+ addends: null,+ };+ if (problem === "byte-length") table.location.bytes = "0x7";+ if (problem === "section-identity") table.section_index = 1;+ if (problem === "decoded-order")+ table.entries[0] = { decoded_index: 1, reported_offset: "0x0" };+ if (problem === "noncanonical-bytes") table.encoded_bytes_base64 = "AB==";+ expect(+ binaryLayoutSchema.safeParse({+ ...value,+ packed_relative_relocations: [table],+ }).success,+ ).toBe(problem === "valid");+ },+);++it.each([+ "valid",+ "zero-symbol",+ "zero-without-table",+ "missing-table",+ "wrong-table-kind",+ "missing-symbol",+ "symbol-outside-table",+ "positive-without-table",+ "owner-link-mismatch",+ "wrong-meaning",+ "valid-section-target",+ "missing-target",+ "wrong-target-owner",+ "wrong-target-offset",+ "undefined-target",+ "inactive-target",+ "false-resolved-zero-target",+ "wrong-unknown-target",+ "missing-string-table",+ "wrong-string-table-kind",+])("validates relocation symbol reference semantics: %s", (problem) => {+ const value = binaryLayoutSchema.parse(report());+ value.artifact.bytes = 512;+ const base = value.sections[0];+ if (base === undefined) throw new Error("section missing");+ value.sections.push(+ {+ ...base,+ index: 1,+ type: "SHT_SYMTAB",+ link: 3,+ header_location: { offset: "0x40", bytes: "0x40" },+ offset: "0x100",+ size: "0x30",+ entry_size: "0x18",+ file_backing: "file",+ },+ {+ ...base,+ index: 2,+ type: "SHT_RELA",+ header_location: { offset: "0x80", bytes: "0x40" },+ offset: "0x130",+ size: "0x18",+ entry_size: "0x18",+ link: 1,+ file_backing: "file",+ },+ {+ ...base,+ index: 3,+ type: "SHT_STRTAB",+ offset: "0x40",+ size: "0x7",+ file_backing: "file",+ },+ );+ value.symbols.push({+ table_index: 1,+ entry_index: 1,+ name: base.name,+ name_offset: "0x0",+ location: { offset: "0x118", bytes: "0x18" },+ value: "0x0",+ value_meaning: "undefined",+ size: "0x0",+ binding: "STB_GLOBAL",+ type: "STT_NOTYPE",+ visibility: "STV_DEFAULT",+ section_index: "SHN_UNDEF",+ });+ const relocation: BinaryLayout["relocations"][number] = {+ section_index: 2,+ entry_index: 0,+ reported_offset: "0x0",+ target: { kind: "linked-virtual-address", address: "0x0" },+ location: { offset: "0x130", bytes: "0x18" },+ type: 1,+ symbol_table_index: 1,+ symbol_index: 1,+ symbol_reference_meaning: "symbol-table-entry",+ addend: "0",+ };+ const table = value.sections[1];+ const owner = value.sections[2];+ if (table === undefined || owner === undefined)+ throw new Error("table or relocation owner missing");+ if (problem.startsWith("zero")) {+ relocation.symbol_index = 0;+ relocation.symbol_reference_meaning = "zero-symbol-value";+ }+ if (problem === "zero-without-table" || problem === "positive-without-table")+ owner.link = relocation.symbol_table_index = 0;+ if (problem === "missing-table")+ owner.link = relocation.symbol_table_index = 99;+ if (problem === "wrong-table-kind") table.type = "SHT_PROGBITS";+ if (problem === "missing-string-table") table.link = 99;+ if (problem === "wrong-string-table-kind") table.link = 0;+ if (problem === "missing-symbol") value.symbols = [];+ if (problem === "symbol-outside-table") table.size = "0x18";+ if (problem === "owner-link-mismatch") owner.link = 0;+ if (problem === "wrong-meaning")+ relocation.symbol_reference_meaning = "zero-symbol-value";+ if (problem.includes("target")) {+ value.image_type = "ET_REL";+ value.entry_point.meaning = "not-applicable";+ owner.info = 1;+ relocation.target = {+ kind: "section-offset",+ section_index:+ problem === "missing-target"+ ? 99+ : problem === "wrong-target-owner"+ ? 2+ : 1,+ offset: problem === "wrong-target-offset" ? "0x1" : "0x0",+ };+ if (problem === "missing-target") owner.info = 99;+ if (problem === "false-resolved-zero-target") {+ owner.info = 0;+ relocation.target.section_index = 0;+ }+ if (+ ["undefined-target", "inactive-target", "wrong-unknown-target"].includes(+ problem,+ )+ ) {+ if (problem === "inactive-target")+ value.sections.push({ ...base, index: 4, type: "SHT_NULL" });+ owner.info =+ problem === "undefined-target"+ ? 0+ : problem === "inactive-target"+ ? 4+ : 1;+ relocation.target = {+ kind: "unknown-section",+ reported_section_index: owner.info,+ offset: "0x0",+ unknown_reason:+ problem === "undefined-target"+ ? "undefined-section-reference"+ : "inactive-section-header",+ };+ }+ }+ value.relocations.push(relocation);+ expect(binaryLayoutSchema.safeParse(value).success).toBe(+ [+ "valid",+ "zero-symbol",+ "zero-without-table",+ "valid-section-target",+ "undefined-target",+ "inactive-target",+ ].includes(problem),+ );+});diff --git a/src/domain/native/binaryLayout.ts b/src/domain/native/binaryLayout.tsnew file mode 100644index 000000000..95a55b866--- /dev/null+++ b/src/domain/native/binaryLayout.ts@@ -0,0 +1,443 @@+import { z } from "zod";++const unsignedHex = z.string().regex(/^0x(?:0|[1-9a-f][0-9a-f]{0,15})$/);+const index = z.number().int().nonnegative();+const scalar = z.union([z.string(), z.number().int()]);+const range = z.strictObject({ offset: unsignedHex, bytes: unsignedHex });+const canonicalBase64 = z+ .string()+ .regex(+ /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/][AQgw]==|[A-Za-z0-9+/]{2}[AEIMQUYcgkosw048]=)?$/,+ );+const name = z.strictObject({+ display: z.string(),+ bytes_base64: canonicalBase64.nullable(),+ location: range.nullable(),+ unknown_reason: z.string().nullable(),+});++/** Explicit local object selection, independent of an active disassembler target. */+export const inspectBinaryLayoutInputSchema = z.strictObject({+ path: z+ .string()+ .min(1)+ .describe("Absolute filesystem path to the selected binary"),+});++/** File and linked-image evidence; numeric ELF values never pass through unsafe JSON numbers. */+const binaryLayoutObjectSchema = z.strictObject({+ artifact: z.strictObject({+ path: z.string().min(1),+ sha256: z.string().regex(/^[a-f0-9]{64}$/),+ bytes: index,+ }),+ format: z.literal("elf"),+ architecture: z.strictObject({+ machine: z.literal("EM_X86_64"),+ bits: z.literal(64),+ byte_order: z.literal("little"),+ }),+ image_type: z.enum(["ET_EXEC", "ET_DYN", "ET_REL"]),+ entry_point: z.strictObject({+ reported_value: unsignedHex,+ meaning: z.enum(["linked-virtual-address", "not-applicable", "absent"]),+ execution_status: z.literal("unknown"),+ }),+ runtime_load_base: z.null(),+ sections: z.array(+ z.strictObject({+ index,+ name,+ name_offset: unsignedHex,+ type: scalar,+ header_location: range,+ address: unsignedHex,+ offset: unsignedHex,+ size: unsignedHex,+ alignment: unsignedHex,+ flags: unsignedHex,+ link: index,+ info: index,+ entry_size: unsignedHex,+ file_backing: z.enum(["file", "none"]),+ }),+ ),+ segments: z.array(+ z.strictObject({+ index,+ type: scalar,+ header_location: range,+ offset: unsignedHex,+ file_size: unsignedHex,+ memory_size: unsignedHex,+ virtual_address: unsignedHex,+ physical_address: unsignedHex,+ alignment: unsignedHex,+ flags: unsignedHex,+ file_backing: z.enum(["file", "none"]),+ permissions: z+ .strictObject({+ read: z.boolean(),+ write: z.boolean(),+ execute: z.boolean(),+ })+ .nullable(),+ }),+ ),+ symbols: z.array(+ z.strictObject({+ table_index: index,+ entry_index: index,+ name,+ name_offset: unsignedHex,+ location: range,+ value: unsignedHex,+ value_meaning: z.enum([+ "undefined",+ "alignment",+ "absolute-value",+ "no-address",+ "unknown-section-index",+ "section-offset",+ "tls-offset",+ "linked-virtual-address",+ ]),+ size: unsignedHex,+ binding: scalar,+ type: scalar,+ visibility: scalar,+ section_index: scalar,+ }),+ ),+ relocations: z.array(+ z.strictObject({+ section_index: index,+ entry_index: index,+ reported_offset: unsignedHex,+ target: z.discriminatedUnion("kind", [+ z.strictObject({+ kind: z.literal("section-offset"),+ section_index: index,+ offset: unsignedHex,+ }),+ z.strictObject({+ kind: z.literal("linked-virtual-address"),+ address: unsignedHex,+ }),+ z.strictObject({+ kind: z.literal("unknown-section"),+ reported_section_index: index,+ offset: unsignedHex,+ unknown_reason: z.enum([+ "undefined-section-reference",+ "inactive-section-header",+ ]),+ }),+ ]),+ location: range,+ type: index,+ symbol_table_index: index,+ symbol_index: index,+ symbol_reference_meaning: z.enum([+ "zero-symbol-value",+ "symbol-table-entry",+ ]),+ addend: z+ .string()+ .regex(/^-?(?:0|[1-9][0-9]{0,18})$/)+ .nullable(),+ }),+ ),+ packed_relative_relocations: z.array(+ z.strictObject({+ section_index: index,+ location: range,+ encoded_bytes_base64: canonicalBase64,+ entries: z.array(+ z.strictObject({ decoded_index: index, reported_offset: unsignedHex }),+ ),+ offset_meaning: z.enum(["linked-virtual-address", "unknown"]),+ evidence_kind: z.literal("derived"),+ entry_source_locations: z.null(),+ addends: z.null(),+ }),+ ),+ relocation_inventory_completeness: z.literal("unknown"),+ linkage: z.strictObject({+ needed_libraries: z.array(name),+ interpreters: z.array(name),+ got: z.array(+ z.strictObject({ display_name: z.string(), address: unsignedHex }),+ ),+ plt: z.array(+ z.strictObject({ display_name: z.string(), address: unsignedHex }),+ ),+ convenience_maps_completeness: z.literal("unknown"),+ runtime_library_paths: z.null(),+ }),+ mitigations: z.strictObject({+ evidence_kind: z.literal("inferred"),+ position_independent: z.boolean(),+ nx_indicator: z.boolean().nullable(),+ executable_stack_indicator: z.boolean(),+ stack_canary_indicator: z.boolean(),+ relro: z.enum(["Partial", "Full"]).nullable(),+ }),+ diagnostics: z.strictObject({+ stdout: z.string(),+ stderr: z.string(),+ truncated: z.boolean(),+ }),+ limitations: z.array(z.string()),+});++/** Decoder payload excludes the artifact identity observed by the owning process boundary. */+export const binaryLayoutPayloadSchema = binaryLayoutObjectSchema.omit({+ artifact: true,+ diagnostics: true,+});++/** Check source ranges again at the public boundary, independently of upstream parsing. */+export const binaryLayoutSchema = binaryLayoutObjectSchema.superRefine(+ (value, context) => {+ const size = BigInt(value.artifact.bytes);+ const check = (+ offset: string,+ length: string,+ path: (string | number)[],+ ): void => {+ const start = BigInt(offset);+ const bytes = BigInt(length);+ if (start > size || bytes > size - start)+ context.addIssue({+ code: "custom",+ path,+ message:+ "Reported file-backed range lies outside the selected artifact.",+ });+ };+ const checkLocation = (+ where: z.infer<typeof range>,+ path: (string | number)[],+ ): void => check(where.offset, where.bytes, path);+ const checkName = (+ reported: z.infer<typeof name>,+ path: (string | number)[],+ ): void => {+ if (reported.location !== null)+ checkLocation(reported.location, [...path, "location"]);+ };+ const expectedEntryMeaning =+ value.image_type === "ET_REL"+ ? "not-applicable"+ : value.entry_point.reported_value === "0x0"+ ? "absent"+ : "linked-virtual-address";+ if (value.entry_point.meaning !== expectedEntryMeaning)+ context.addIssue({+ code: "custom",+ path: ["entry_point", "meaning"],+ message:+ "Entry meaning must distinguish zero/unused fields from an actual linked address.",+ });+ for (const [index, section] of value.sections.entries()) {+ if (+ (section.type === "SHT_SYMTAB" || section.type === "SHT_DYNSYM") &&+ value.sections[section.link]?.type !== "SHT_STRTAB"+ )+ context.addIssue({+ code: "custom",+ path: ["sections", index, "link"],+ message:+ "Symbol tables must link to an existing string-table section.",+ });+ if (section.index !== index)+ context.addIssue({+ code: "custom",+ path: ["sections", index, "index"],+ message:+ "Complete section order must preserve original producer indices.",+ });+ checkLocation(section.header_location, [+ "sections",+ index,+ "header_location",+ ]);+ checkName(section.name, ["sections", index, "name"]);+ if (section.file_backing === "file")+ check(section.offset, section.size, ["sections", index]);+ }+ for (const [index, segment] of value.segments.entries()) {+ if (segment.index !== index)+ context.addIssue({+ code: "custom",+ path: ["segments", index, "index"],+ message:+ "Complete segment order must preserve original producer indices.",+ });+ checkLocation(segment.header_location, [+ "segments",+ index,+ "header_location",+ ]);+ const hasFileBytes =+ segment.type !== "PT_NULL" && BigInt(segment.file_size) !== 0n;+ if (segment.file_backing !== (hasFileBytes ? "file" : "none"))+ context.addIssue({+ code: "custom",+ path: ["segments", index, "file_backing"],+ message:+ "File backing must follow the reported segment type and file size.",+ });+ if ((segment.type === "PT_NULL") !== (segment.permissions === null))+ context.addIssue({+ code: "custom",+ path: ["segments", index, "permissions"],+ message:+ "Unused PT_NULL flags have no permission meaning; other segment flags retain their interpretation.",+ });+ if (hasFileBytes)+ check(segment.offset, segment.file_size, ["segments", index]);+ }+ for (const [index, symbol] of value.symbols.entries()) {+ checkLocation(symbol.location, ["symbols", index, "location"]);+ checkName(symbol.name, ["symbols", index, "name"]);+ }+ for (const [index, relocation] of value.relocations.entries())+ checkLocation(relocation.location, ["relocations", index, "location"]);+ validateRelocationReferences(value, context);+ validatePackedRelativeTables(value, context, checkLocation);+ for (const facet of ["needed_libraries", "interpreters"] as const)+ for (const [index, reported] of value.linkage[facet].entries())+ checkName(reported, ["linkage", facet, index]);+ },+);++export type InspectBinaryLayoutInput = z.infer<+ typeof inspectBinaryLayoutInputSchema+>;+export type BinaryLayout = z.infer<typeof binaryLayoutSchema>;++const validateRelocationReferences = (+ value: z.output<typeof binaryLayoutObjectSchema>,+ context: z.RefinementCtx,+): void => {+ const symbols = new Set(+ value.symbols.map(+ (symbol) => `${symbol.table_index}:${symbol.entry_index}`,+ ),+ );+ for (const [index, relocation] of value.relocations.entries()) {+ const owner = value.sections[relocation.section_index];+ const target = relocation.target;+ const targetMatches =+ value.image_type === "ET_REL"+ ? target.kind === "section-offset"+ ? target.section_index !== 0 &&+ target.section_index === owner?.info &&+ value.sections[target.section_index] !== undefined &&+ value.sections[target.section_index]?.type !== "SHT_NULL" &&+ target.offset === relocation.reported_offset+ : target.kind === "unknown-section" &&+ target.reported_section_index === owner?.info &&+ target.offset === relocation.reported_offset &&+ (target.reported_section_index === 0+ ? target.unknown_reason === "undefined-section-reference"+ : value.sections[target.reported_section_index]?.type ===+ "SHT_NULL" &&+ target.unknown_reason === "inactive-section-header")+ : target.kind === "linked-virtual-address" &&+ target.address === relocation.reported_offset;+ if (!targetMatches)+ context.addIssue({+ code: "custom",+ path: ["relocations", index, "target"],+ message:+ "Relocation target must preserve its reported offset and owner reference; SHN_UNDEF and inactive headers remain unknown rather than resolved sections.",+ });+ const table = value.sections[relocation.symbol_table_index];+ const tableExists =+ relocation.symbol_table_index !== 0 &&+ (table?.type === "SHT_SYMTAB" || table?.type === "SHT_DYNSYM");+ const positiveReferenceExists =+ tableExists &&+ BigInt(table.entry_size) >= 24n &&+ BigInt(relocation.symbol_index) <+ BigInt(table.size) / BigInt(table.entry_size) &&+ symbols.has(+ `${relocation.symbol_table_index}:${relocation.symbol_index}`,+ );+ if (+ (owner?.type !== "SHT_REL" && owner?.type !== "SHT_RELA") ||+ owner.link !== relocation.symbol_table_index ||+ (relocation.symbol_table_index !== 0 && !tableExists) ||+ (relocation.symbol_index !== 0 && !positiveReferenceExists) ||+ relocation.symbol_reference_meaning !==+ (relocation.symbol_index === 0+ ? "zero-symbol-value"+ : "symbol-table-entry")+ )+ context.addIssue({+ code: "custom",+ path: ["relocations", index],+ message:+ "Relocation must preserve its REL/RELA owner and resolve positive symbol indices through the linked symbol table; index zero uses a zero symbol value.",+ });+ }+};++const validatePackedRelativeTables = (+ value: z.output<typeof binaryLayoutObjectSchema>,+ context: z.RefinementCtx,+ checkLocation: (+ location: z.output<typeof range>,+ path: (string | number)[],+ ) => void,+): void => {+ for (const [+ tableIndex,+ table,+ ] of value.packed_relative_relocations.entries()) {+ checkLocation(table.location, [+ "packed_relative_relocations",+ tableIndex,+ "location",+ ]);+ const encodedBytes =+ (table.encoded_bytes_base64.length * 3) / 4 -+ (table.encoded_bytes_base64.endsWith("==")+ ? 2+ : table.encoded_bytes_base64.endsWith("=")+ ? 1+ : 0);+ if (+ !Number.isInteger(encodedBytes) ||+ BigInt(encodedBytes) !== BigInt(table.location.bytes)+ )+ context.addIssue({+ code: "custom",+ path: ["packed_relative_relocations", tableIndex],+ message:+ "Complete packed table bytes must match its original file range.",+ });+ const section = value.sections[table.section_index];+ if (+ section?.type !== "SHT_RELR" ||+ section.offset !== table.location.offset ||+ section.size !== table.location.bytes+ )+ context.addIssue({+ code: "custom",+ path: ["packed_relative_relocations", tableIndex, "section_index"],+ message:+ "Packed relative evidence must retain its original RELR section identity and range.",+ });+ for (const [decoded, entry] of table.entries.entries())+ if (entry.decoded_index !== decoded)+ context.addIssue({+ code: "custom",+ path: ["packed_relative_relocations", tableIndex, "entries", decoded],+ message: "Decoded offsets must preserve upstream iterator order.",+ });+ }+};diff --git a/src/domain/providerSelectionError.ts b/src/domain/providerSelectionError.tsindex 2dbb182fa..e6520848f 100644--- a/src/domain/providerSelectionError.ts+++ b/src/domain/providerSelectionError.ts@@ -1,5 +1,8 @@import type { JsonValue } from "./jsonValue.js";-import { AnalysisError } from "./analysisErrorBase.js";+import {+ AnalysisError,+ type AnalysisCapturedOutput,+} from "./analysisErrorBase.js";/** Stable failure classes for target-bound deep-provider selection. */export type ProviderSelectionFailureReason =@@ -19,6 +22,7 @@ export interface ProviderSelectionRejection {/** Complete typed context for one failed deep-provider selection. */export interface ProviderSelectionErrorOptions {+ readonly capturedOutput?: AnalysisCapturedOutput;readonly operation?: string;readonly reason: ProviderSelectionFailureReason;readonly requestedProviderId: string;@@ -38,7 +42,12 @@ export class ProviderSelectionError extends AnalysisError {constructor(options: ProviderSelectionErrorOptions) {const operation = options.operation ?? "open_binary";- super(providerSelectionDiagnostic(options));+ super(+ providerSelectionDiagnostic(options),+ options.capturedOutput === undefined+ ? undefined+ : { capturedOutput: options.capturedOutput },+ );this.operation = operation;this.reason = options.reason;this.requestedProviderId = options.requestedProviderId;diff --git a/src/generatedPackageMetadata.ts b/src/generatedPackageMetadata.tsindex 531f3ddb8..3c4aff2ed 100644--- a/src/generatedPackageMetadata.ts+++ b/src/generatedPackageMetadata.ts@@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {serverSdkVersion: "2.3.1",clientSdkVersion: "2.3.1",coreSdkVersion: "2.3.1",- skillVersion: "29",+ skillVersion: "30",} as const;diff --git a/src/native/pwntools/PwntoolsFailures.ts b/src/native/pwntools/PwntoolsFailures.tsnew file mode 100644index 000000000..5e595f6de--- /dev/null+++ b/src/native/pwntools/PwntoolsFailures.ts@@ -0,0 +1,245 @@+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";+import {+ AnalysisError,+ type AnalysisCapturedOutput,+} from "../../domain/analysisErrorBase.js";+import type { ProviderProcessSnapshot } from "../../process/ProviderProcess.js";+import {+ AnalysisAccessDeniedError,+ AnalysisArtifactChangedError,+ AnalysisCancelledError,+ AnalysisInputError,+ AnalysisOutputError,+ AnalysisTimeoutError,+ AnalysisResourceConstraintError,+} from "../../domain/analysisErrorCore.js";+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";+import { ProviderSelectionError } from "../../domain/providerSelectionError.js";+import { OwnedCommandFailure } from "../../process/OwnedCommand.js";+import type { PwntoolsFailureEvidence } from "./PwntoolsResourceLimits.js";+import {+ PWNTOOLS_PROVIDER_IDENTITY,+ PWNTOOLS_LIMITS,+ PWNTOOLS_MEMORY_FAILURE_EXIT,+ PWNTOOLS_FILE_SIZE_FAILURE_EXIT,+} from "./PwntoolsRelease.js";++const OPERATION = "inspect_binary_layout";++/** Keep read, engine, output and owned-lifecycle failure reasons distinct. */+export const pwntoolsLayoutFailure = (+ cause: unknown,+ phase: string,+ path: string,+ executablePath = path,+ failureEvidence: PwntoolsFailureEvidence = {},+): AnalysisError => {+ const limitReport = failureEvidence.limits;+ if (cause instanceof AnalysisError) return cause;+ if (cause instanceof OwnedCommandFailure) {+ const outputOptions =+ cause.snapshot === null+ ? undefined+ : { capturedOutput: capturedPwntoolsOutput(cause.snapshot) };+ if (cause.cleanupFailure !== null)+ return new ProviderCleanupError(+ PWNTOOLS_PROVIDER_IDENTITY.id,+ cause.resources,+ {+ reason: cause.cleanupFailure,+ ...(cause.snapshot === null+ ? {}+ : {+ captured_output: { ...capturedPwntoolsOutput(cause.snapshot) },+ }),+ previous_error: {+ failure_kind: cause.reason,+ message: cause.message,+ exit_code: cause.snapshot?.exitCode ?? null,+ signal: cause.snapshot?.signal ?? null,+ stdout: cause.snapshot?.stdout.text ?? null,+ stderr: cause.snapshot?.stderr.text ?? null,+ },+ },+ { operation: OPERATION, cause },+ );+ if (cause.reason === "cancelled")+ return new AnalysisCancelledError(OPERATION, outputOptions);+ if (cause.reason === "timeout")+ return new AnalysisTimeoutError(+ OPERATION,+ PWNTOOLS_LIMITS.timeoutMs,+ outputOptions,+ );+ if (cause.reason === "output-limit")+ return new AnalysisOutputError(OPERATION, cause.message, outputOptions);+ if (+ cause.reason === "process" &&+ (cause.snapshot?.signal === "SIGXFSZ" ||+ (failureEvidence.marker?.resource === "file-size" &&+ cause.snapshot?.exitCode === PWNTOOLS_FILE_SIZE_FAILURE_EXIT &&+ cause.snapshot.signal === null))+ )+ return new AnalysisResourceConstraintError(+ OPERATION,+ "file-size",+ (cause.snapshot.signal === "SIGXFSZ"+ ? "Owned Python terminated with SIGXFSZ; the exact signal cause is unknown."+ : "The owned Python bridge reported EFBIG while writing a file; the exact write failure cause is unknown.") ++ (limitReport?.failure === null || limitReport === undefined+ ? ""+ : ` Effective limit report unavailable: ${limitReport.failure}`),+ limitReport?.limits ?? null,+ outputOptions,+ );+ if (cause.reason === "process" && cause.snapshot?.signal === "SIGXCPU")+ return new AnalysisResourceConstraintError(+ OPERATION,+ "cpu",+ "Owned Python terminated with SIGXCPU; the exact signal cause is unknown." ++ (limitReport?.failure === null || limitReport === undefined+ ? ""+ : ` Effective limit report unavailable: ${limitReport.failure}`),+ limitReport?.limits ?? null,+ outputOptions,+ );+ if (+ cause.reason === "process" &&+ failureEvidence.marker?.resource === "memory" &&+ cause.snapshot?.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT &&+ cause.snapshot.signal === null+ )+ return new AnalysisResourceConstraintError(+ OPERATION,+ "memory",+ "The owned Python bridge reported a memory allocation failure without a structured reply; the exact allocation cause is unknown." ++ (limitReport?.failure === null || limitReport === undefined+ ? ""+ : ` Effective limit report unavailable: ${limitReport.failure}`),+ limitReport?.limits ?? null,+ outputOptions,+ );+ }+ if (+ cause instanceof Error &&+ "code" in cause &&+ "syscall" in cause &&+ typeof cause.syscall === "string" &&+ cause.syscall.startsWith("spawn ")+ )+ return pwntoolsUnavailable(+ `Selected Python could not launch (${String(cause.code)}): ${executablePath}. Check the configured executable, its interpreter and host execute access.`,+ executablePath,+ String(cause.code),+ );+ if (cause instanceof ArtifactReaderFailure) {+ if (cause.reason === "integrity")+ return new AnalysisArtifactChangedError(OPERATION, path, cause.message, {+ cause,+ });+ if (cause.reason === "cancelled")+ return new AnalysisCancelledError(OPERATION);+ if (+ cause.reason === "limit" ||+ cause.reason === "path" ||+ cause.reason === "format"+ )+ return new AnalysisInputError(OPERATION, { cause }, [+ {+ path: ["path"],+ reason: cause.reason === "limit" ? "out_of_range" : "invalid_format",+ message: cause.message,+ },+ ]);+ }+ if (cause instanceof Error && "code" in cause) {+ if (phase === "configuration")+ return pwntoolsUnavailable(+ `Selected Python executable is unavailable (${String(cause.code)}): ${path}. Check the caller-selected path and execute access.`,+ path,+ String(cause.code),+ );+ if (+ phase === "artifact-read" &&+ (cause.code === "EACCES" || cause.code === "EPERM")+ )+ return new AnalysisAccessDeniedError(OPERATION, path, cause.code, {+ cause,+ });+ if (+ phase === "artifact-read" &&+ (cause.code === "ENOENT" || cause.code === "ENOTDIR")+ )+ return new AnalysisInputError(OPERATION, { cause }, [+ {+ path: ["path"],+ reason: "invalid_value",+ message: `Selected object could not be read (${String(cause.code)}): ${path}.`,+ },+ ]);+ }+ return new ProviderAdapterError(PWNTOOLS_PROVIDER_IDENTITY.id, OPERATION, {+ cause,+ diagnostics: {+ phase,+ path,+ reason: cause instanceof Error ? cause.message : String(cause),+ ...(failureEvidence.marker === undefined+ ? {}+ : { resource_failure_marker: { ...failureEvidence.marker } }),+ ...(cause instanceof OwnedCommandFailure+ ? {+ failure_kind: cause.reason,+ exit_code: cause.snapshot?.exitCode ?? null,+ signal: cause.snapshot?.signal ?? null,+ stdout: cause.snapshot?.stdout.text ?? null,+ stderr: cause.snapshot?.stderr.text ?? null,+ ...(cause.snapshot === null+ ? {}+ : {+ captured_output: {+ ...capturedPwntoolsOutput(cause.snapshot),+ },+ }),+ }+ : {}),+ },+ });+};++/** Report caller-selected engine absence with its actual configuration and host constraint. */+export const pwntoolsUnavailable = (+ reason: string,+ path: string,+ systemCode?: string,+ capturedOutput?: AnalysisCapturedOutput,+): ProviderSelectionError =>+ new ProviderSelectionError({+ ...(capturedOutput === undefined ? {} : { capturedOutput }),+ operation: OPERATION,+ reason: "provider_unavailable",+ requestedProviderId: PWNTOOLS_PROVIDER_IDENTITY.id,+ candidateIds: [PWNTOOLS_PROVIDER_IDENTITY.id],+ rejections: [+ {+ providerId: PWNTOOLS_PROVIDER_IDENTITY.id,+ code: "provider_unavailable",+ reason,+ diagnostics: {+ configuration_key: "REA_PWNTOOLS_PYTHON",+ executable_path: path,+ ...(systemCode === undefined ? {} : { system_code: systemCode }),+ },+ },+ ],+ });++/** Retain bounded text output and the shared supervisor's observed truncation flag. */+export const capturedPwntoolsOutput = (+ snapshot: ProviderProcessSnapshot,+): AnalysisCapturedOutput => ({+ stdout: snapshot.stdout.text,+ stderr: snapshot.stderr.text,+ truncated: snapshot.diagnosticTruncated === true,+});diff --git a/src/native/pwntools/PwntoolsLayoutProvider.ts b/src/native/pwntools/PwntoolsLayoutProvider.tsnew file mode 100644index 000000000..4e543d105--- /dev/null+++ b/src/native/pwntools/PwntoolsLayoutProvider.ts@@ -0,0 +1,381 @@+import {+ pwntoolsLayoutFailure,+ pwntoolsUnavailable,+ capturedPwntoolsOutput,+} from "./PwntoolsFailures.js";+import { randomUUID } from "node:crypto";+import { access, stat, writeFile } from "node:fs/promises";+import { constants } from "node:fs";+import { isAbsolute, join } from "node:path";+import { fileURLToPath } from "node:url";+import { z } from "zod";+import type { ExecutionOptions } from "../../application/AnalysisProvider.js";+import type { BinaryLayoutPort } from "../../application/binaryDiagnostics/BinaryLayoutPort.js";+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import {+ AnalysisCancelledError,+ AnalysisCapabilityUnavailableError,+ AnalysisInputError,+ AnalysisOutputError,+ AnalysisResourceConstraintError,+} from "../../domain/analysisErrorCore.js";+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";+import { err, ok, type Result } from "../../domain/result.js";+import {+ binaryLayoutPayloadSchema,+ binaryLayoutSchema,+ type BinaryLayout,+ type InspectBinaryLayoutInput,+} from "../../domain/native/binaryLayout.js";+import { runOwnedCommand } from "../../process/OwnedCommand.js";+import { OwnedCommandFailure } from "../../process/OwnedCommand.js";+import {+ pwntoolsResourceLimitsSchema,+ type PwntoolsLimitReport,+ type PwntoolsFailureEvidence,+} from "./PwntoolsResourceLimits.js";+import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";+import {+ PWNTOOLS_PROVIDER_IDENTITY,+ PWNTOOLS_LIMITS,+ PWNTOOLS_FILE_SIZE_FAILURE_EXIT,+ PWNTOOLS_MEMORY_FAILURE_EXIT,+} from "./PwntoolsRelease.js";++const OPERATION = "inspect_binary_layout";+const decoded = binaryLayoutPayloadSchema;+const replySchema = z.discriminatedUnion("ok", [+ z.strictObject({+ ok: z.literal(true),+ profile: z.literal(PWNTOOLS_PROVIDER_IDENTITY.version),+ value: decoded,+ }),+ z.strictObject({+ ok: z.literal(false),+ reason: z.enum([+ "format",+ "unsupported",+ "unavailable",+ "resource-limit",+ "output-limit",+ "decoder",+ ]),+ message: z.string(),+ reported_limits: pwntoolsResourceLimitsSchema.nullable().optional(),+ }),+]);++type Launcher = NonNullable<Parameters<typeof runOwnedCommand>[2]>["launcher"];++/** Thin owned-process adapter; all ELF parsing and heuristics come from unchanged upstream code. */+export class PwntoolsLayoutProvider implements BinaryLayoutPort {+ readonly identity = PWNTOOLS_PROVIDER_IDENTITY;+ constructor(+ readonly environment: Readonly<NodeJS.ProcessEnv>,+ readonly launcher?: Launcher,+ readonly createRuntime: () => Promise<+ Pick<PrivateRuntimeRoot, "path" | "close">+ > = () => PrivateRuntimeRoot.create({ prefix: "rea-elf-layout-" }),+ ) {}++ /** Snapshot one explicit artifact and return complete static observations without launching the selected object as a host process. */+ async inspect(+ input: InspectBinaryLayoutInput,+ options?: ExecutionOptions,+ ): Promise<Result<BinaryLayout, AnalysisError>> {+ let root: Pick<PrivateRuntimeRoot, "path" | "close"> | undefined;+ let result: Result<BinaryLayout, AnalysisError>;+ let phase: "configuration" | "artifact-read" | "decoder" = "configuration";+ const executablePath = this.environment.REA_PWNTOOLS_PYTHON ?? "";+ let selectedPath = executablePath;+ try {+ if (options?.signal?.aborted) throw new AnalysisCancelledError(OPERATION);+ if (process.platform !== "linux" || process.arch !== "x64")+ throw new AnalysisCapabilityUnavailableError(+ this.identity.id,+ OPERATION,+ "The real-verified pwntools layout profile currently supports Linux x64 only.",+ );+ if (!isAbsolute(selectedPath))+ throw pwntoolsUnavailable(+ "Set REA_PWNTOOLS_PYTHON to an absolute caller-supplied Python executable with pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2; REA never installs Python or packages.",+ selectedPath,+ );+ await access(selectedPath, constants.X_OK);+ if (!(await stat(selectedPath)).isFile())+ throw pwntoolsUnavailable(+ "Selected Python executable must be a regular executable file, not a directory: " ++ selectedPath,+ selectedPath,+ );+ phase = "artifact-read";+ selectedPath = input.path;+ const snapshot = await readStableArtifact(+ input.path,+ PWNTOOLS_LIMITS.inputBytes,+ options?.signal,+ );+ phase = "decoder";+ root = await this.createRuntime();+ const requestPath = join(root.path, "request.json");+ const snapshotPath = join(root.path, "object.snapshot");+ const replyPath = join(root.path, "reply.json");+ await writeFile(snapshotPath, snapshot.bytes, {+ flag: "wx",+ mode: 0o600,+ ...(options?.signal === undefined ? {} : { signal: options.signal }),+ });+ await writeFile(+ requestPath,+ JSON.stringify({ snapshot_path: snapshotPath, reply_path: replyPath }),+ { flag: "wx", mode: 0o600 },+ );+ const execution = await runOwnedCommand(+ {+ command: this.environment.REA_PWNTOOLS_PYTHON ?? "",+ arguments: [+ "-I",+ fileURLToPath(+ new URL("../../../bridge/pwntools/layout.py", import.meta.url),+ ),+ join(root.path, "resource.failure"),+ requestPath,+ ],+ cwd: root.path,+ runId: `rea-elf-layout-${randomUUID()}`,+ hostEnvironment: {+ ...this.environment,+ PWNLIB_NOTERM: "1",+ OPENBLAS_NUM_THREADS: "1",+ OMP_NUM_THREADS: "1",+ },+ },+ {+ timeoutMs: PWNTOOLS_LIMITS.timeoutMs,+ diagnosticBytes: PWNTOOLS_LIMITS.diagnosticBytes,+ },+ {+ ...(options?.signal === undefined ? {} : { signal: options.signal }),+ ...(this.launcher === undefined ? {} : { launcher: this.launcher }),+ },+ );+ const capturedOutput = capturedPwntoolsOutput(execution);+ let reply: z.output<typeof replySchema>;+ try {+ const file = await readStableArtifact(+ replyPath,+ PWNTOOLS_LIMITS.outputBytes,+ options?.signal,+ );+ reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8")));+ } catch (cause: unknown) {+ if (options?.signal?.aborted)+ throw new AnalysisCancelledError(OPERATION, { capturedOutput });+ throw new AnalysisOutputError(+ OPERATION,+ `Owned ELF decoder reply failed for ${input.path}: ${cause instanceof z.ZodError ? cause.issues[0]?.message + " at " + (cause.issues[0]?.path.map(String).join(".") ?? "root") : cause instanceof Error ? cause.message : String(cause)}`,+ { cause, capturedOutput },+ );+ }+ if (!reply.ok) {+ if (reply.reason === "resource-limit")+ throw new AnalysisResourceConstraintError(+ OPERATION,+ "memory",+ reply.message,+ reply.reported_limits ?? null,+ { capturedOutput },+ );+ if (reply.reason === "format")+ throw new AnalysisInputError(OPERATION, { capturedOutput }, [+ {+ path: ["path"],+ reason: "invalid_format",+ message: reply.message,+ },+ ]);+ if (reply.reason === "unavailable")+ throw pwntoolsUnavailable(+ reply.message,+ this.environment.REA_PWNTOOLS_PYTHON ?? "",+ undefined,+ capturedOutput,+ );+ if (reply.reason === "unsupported")+ throw new AnalysisCapabilityUnavailableError(+ this.identity.id,+ OPERATION,+ reply.message,+ { userMessage: reply.message, capturedOutput },+ );+ if (reply.reason === "output-limit")+ throw new AnalysisOutputError(OPERATION, reply.message, {+ capturedOutput,+ });+ throw new ProviderAdapterError(this.identity.id, OPERATION, {+ diagnostics: {+ phase,+ failure_kind: reply.reason,+ reason: reply.message,+ stdout: execution.stdout.text,+ stderr: execution.stderr.text,+ captured_output: { ...capturedOutput },+ },+ });+ }+ const validated = binaryLayoutSchema.safeParse({+ ...reply.value,+ artifact: {+ path: input.path,+ sha256: snapshot.sha256,+ bytes: snapshot.bytes.length,+ },+ diagnostics: {+ stdout: execution.stdout.text,+ stderr: execution.stderr.text,+ truncated: capturedOutput.truncated,+ },+ });+ if (!validated.success)+ throw new AnalysisOutputError(+ OPERATION,+ `ELF reply contains invalid source ranges or value meanings: ${validated.error.issues[0]?.message ?? "schema mismatch"}`,+ { capturedOutput },+ );+ for (const table of validated.data.packed_relative_relocations) {+ const start = Number(BigInt(table.location.offset));+ const length = Number(BigInt(table.location.bytes));+ if (+ !Buffer.from(table.encoded_bytes_base64, "base64").equals(+ snapshot.bytes.subarray(start, start + length),+ )+ )+ throw new AnalysisOutputError(+ OPERATION,+ "Reported packed relocation bytes differ from the selected snapshot at their original file range.",+ { capturedOutput },+ );+ }+ result = ok(validated.data);+ } catch (cause: unknown) {+ let limitReport: PwntoolsLimitReport | undefined;+ let marker: PwntoolsFailureEvidence["marker"];+ if (+ cause instanceof OwnedCommandFailure &&+ cause.snapshot?.signal === null &&+ (cause.snapshot.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT ||+ cause.snapshot.exitCode === PWNTOOLS_FILE_SIZE_FAILURE_EXIT) &&+ root !== undefined+ ) {+ try {+ const reported = await readStableArtifact(+ join(root.path, "resource.failure"),+ 1,+ );+ const expected =+ cause.snapshot.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT+ ? "M"+ : "F";+ if (!reported.bytes.equals(Buffer.from(expected, "ascii")))+ throw new Error(+ "Private bridge failure marker does not match the observed exit status.",+ );+ marker = {+ resource: expected === "M" ? "memory" : "file-size",+ failure: null,+ };+ } catch (markerFailure: unknown) {+ marker = {+ resource: null,+ failure:+ markerFailure instanceof Error+ ? markerFailure.message+ : String(markerFailure),+ };+ }+ }+ if (+ cause instanceof OwnedCommandFailure &&+ (cause.snapshot?.signal === "SIGXCPU" ||+ cause.snapshot?.signal === "SIGXFSZ" ||+ ((cause.snapshot?.exitCode === PWNTOOLS_FILE_SIZE_FAILURE_EXIT ||+ cause.snapshot?.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT) &&+ cause.snapshot.signal === null)) &&+ root !== undefined+ ) {+ try {+ const reported = await readStableArtifact(+ join(root.path, "limits.json"),+ 4096,+ );+ limitReport = {+ limits: pwntoolsResourceLimitsSchema.parse(+ JSON.parse(reported.bytes.toString("utf8")),+ ),+ failure: null,+ };+ } catch (reportFailure: unknown) {+ limitReport = {+ limits: null,+ failure:+ reportFailure instanceof Error+ ? reportFailure.message+ : String(reportFailure),+ };+ }+ }+ result = err(+ options?.signal?.aborted &&+ (cause === options.signal.reason ||+ (cause instanceof Error && cause.name === "AbortError"))+ ? new AnalysisCancelledError(OPERATION)+ : pwntoolsLayoutFailure(cause, phase, selectedPath, executablePath, {+ ...(limitReport === undefined ? {} : { limits: limitReport }),+ ...(marker === undefined ? {} : { marker }),+ }),+ );+ }+ if (root !== undefined) {+ try {+ await root.close();+ } catch (cause: unknown) {+ return err(+ new ProviderCleanupError(+ this.identity.id,+ [root.path],+ {+ reason: cause instanceof Error ? cause.message : String(cause),+ previous_error: result.ok+ ? null+ : projectAnalysisError(result.error),+ ...(result.ok+ ? {+ captured_output: {+ stdout: result.value.diagnostics.stdout,+ stderr: result.value.diagnostics.stderr,+ truncated: result.value.diagnostics.truncated,+ },+ }+ : {}),+ },+ { operation: OPERATION },+ ),+ );+ }+ }+ return result.ok && options?.signal?.aborted+ ? err(+ new AnalysisCancelledError(OPERATION, {+ capturedOutput: {+ stdout: result.value.diagnostics.stdout,+ stderr: result.value.diagnostics.stderr,+ truncated: result.value.diagnostics.truncated,+ },+ }),+ )+ : result;+ }+}diff --git a/src/native/pwntools/PwntoolsRelease.ts b/src/native/pwntools/PwntoolsRelease.tsnew file mode 100644index 000000000..f041304f1--- /dev/null+++ b/src/native/pwntools/PwntoolsRelease.ts@@ -0,0 +1,19 @@+/** Verified unchanged upstream profile for the Linux ELF adapter. */+export const PWNTOOLS_PROVIDER_IDENTITY = {+ id: "pwntools-elf",+ name: "REA pwntools ELF adapter",+} as const;+/** Bridge-reserved status for MemoryError when no structured reply can be written. */+export const PWNTOOLS_MEMORY_FAILURE_EXIT = 75;+/** Bridge-reserved status for an observed EFBIG failure without a complete reply. */+export const PWNTOOLS_FILE_SIZE_FAILURE_EXIT = 76;+/** Complete evidence budgets; address-space is separate from resident memory. */+export const PWNTOOLS_LIMITS = {+ inputBytes: 32 * 1024 * 1024,+ outputBytes: 64 * 1024 * 1024,+ diagnosticBytes: 1024 * 1024,+ timeoutMs: 30_000,+ addressSpaceBytes: 3 * 1024 * 1024 * 1024,+ cpuSeconds: 30,+} as const;diff --git a/src/native/pwntools/PwntoolsResourceLimits.ts b/src/native/pwntools/PwntoolsResourceLimits.tsnew file mode 100644index 000000000..ad00d92b4--- /dev/null+++ b/src/native/pwntools/PwntoolsResourceLimits.ts@@ -0,0 +1,32 @@+import { z } from "zod";+import { PWNTOOLS_LIMITS } from "./PwntoolsRelease.js";++/** Actual limits reported by the owned bridge after lowering inherited soft limits. */+export const pwntoolsResourceLimitsSchema = z.strictObject({+ address_space_bytes: z+ .number()+ .int()+ .nonnegative()+ .max(PWNTOOLS_LIMITS.addressSpaceBytes),+ cpu_seconds: z.number().int().nonnegative().max(PWNTOOLS_LIMITS.cpuSeconds),+ file_size_bytes: z+ .number()+ .int()+ .nonnegative()+ .max(PWNTOOLS_LIMITS.outputBytes),+});++/** A missing or invalid report leaves limits unknown and retains its read failure. */+export interface PwntoolsLimitReport {+ readonly limits: z.output<typeof pwntoolsResourceLimitsSchema> | null;+ readonly failure: string | null;+}++/** Private failure-branch evidence; a bare launcher exit code is insufficient. */+export interface PwntoolsFailureEvidence {+ readonly limits?: PwntoolsLimitReport;+ readonly marker?: {+ readonly resource: "memory" | "file-size" | null;+ readonly failure: string | null;+ };+}diff --git a/src/server/createServer.ts b/src/server/createServer.tsindex acc5dca05..1a69fecac 100644--- a/src/server/createServer.ts+++ b/src/server/createServer.ts@@ -1,3 +1,6 @@+import { registerBinaryDiagnosticsTools } from "./registerBinaryDiagnosticsTools.js";+import { createBinaryLayoutService } from "../composition/binaryDiagnostics.js";+import type { BinaryLayoutService } from "../application/binaryDiagnostics/BinaryLayoutService.js";import { McpServer } from "@modelcontextprotocol/server";import { isAbsolute } from "node:path";@@ -60,6 +63,7 @@ const ACTIVE_TARGET_INSTRUCTIONS =export interface CreateServerOptions {readonly logger?: Logger;+ readonly binaryLayout?: BinaryLayoutService;readonly firmwareAnalysis?: FirmwareAnalysisPort;readonly javascriptRecovery?: JavaScriptRecoveryPort;readonly webModuleTrace?: WebModuleTraceService;@@ -88,6 +92,11 @@ const installSessionToolAvailability = (webModuleResolutionEnabled:options.webModuleTrace !== undefined ||isAbsolute(process.env.REA_BROWSER_EXECUTABLE ?? ""),+ binaryLayoutEnabled:+ options.binaryLayout !== undefined ||+ (process.platform === "linux" &&+ process.arch === "x64" &&+ isAbsolute(process.env.REA_PWNTOOLS_PYTHON ?? "")),firmwareInspectionEnabled:options.firmwareAnalysis !== undefined ||(process.platform === "linux" &&@@ -190,6 +199,12 @@ export const createServer = (toolLogger,recordEvidence,);+ registerBinaryDiagnosticsTools(+ server,+ options.binaryLayout ?? createBinaryLayoutService(),+ toolLogger,+ recordEvidence,+ );registerFirmwareTools(server,new FirmwareAnalysisService(diff --git a/src/server/registerBinaryDiagnosticsTools.ts b/src/server/registerBinaryDiagnosticsTools.tsnew file mode 100644index 000000000..949e24624--- /dev/null+++ b/src/server/registerBinaryDiagnosticsTools.ts@@ -0,0 +1,32 @@+import type { McpServer } from "@modelcontextprotocol/server";+import type { BinaryLayoutService } from "../application/binaryDiagnostics/BinaryLayoutService.js";+import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";+import { toolContract } from "../contracts/toolContracts.js";+import type { Logger } from "../logger.js";+import { logToolExecution } from "./toolLogging.js";+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";+import { toCallToolResult } from "./toolResult.js";++/** Bind offline layout inspection to its named contract and session Evidence owner. */+export const registerBinaryDiagnosticsTools = (+ server: McpServer,+ service: BinaryLayoutService,+ logger: Logger,+ recordEvidence?: EvidenceWriter["recordEvidence"],+): void => {+ const contract = toolContract("inspect_binary_layout");+ server.registerTool(+ contract.name,+ toolRegistrationOptions(contract),+ async (input, context) => {+ const result = await logToolExecution(logger, contract.name, () =>+ service.inspect(input, { signal: context.mcpReq.signal }),+ );+ if (!result.ok) return toCallToolResult(result, contract);+ const recorded = recordEvidence?.(result.value);+ return recorded !== undefined && !recorded.ok+ ? toCallToolResult(recorded, contract)+ : toCallToolResult(result, contract);+ },+ );+};diff --git a/src/server/sessionAvailabilityPolicy.ts b/src/server/sessionAvailabilityPolicy.tsindex 904594c46..0303828e5 100644--- a/src/server/sessionAvailabilityPolicy.ts+++ b/src/server/sessionAvailabilityPolicy.ts@@ -18,6 +18,7 @@ export interface SessionAvailabilityDefaults {| "androidAnalysisEnabled"| "javascriptRecoveryEnabled"| "webModuleResolutionEnabled"+ | "binaryLayoutEnabled"| "firmwareInspectionEnabled"| "firmwareExtractionEnabled">;@@ -32,6 +33,8 @@ export const sessionAvailabilityPolicy = (configured ??(() => ({processCaptureEnabled: platform !== "win32",+ binaryLayoutEnabled:+ defaults.optionalFeatures?.binaryLayoutEnabled ?? false,firmwareInspectionEnabled:defaults.optionalFeatures?.firmwareInspectionEnabled ?? false,firmwareExtractionEnabled:diff --git a/src/server/toolResult.ts b/src/server/toolResult.tsindex f74dfe32d..ca2319bdd 100644--- a/src/server/toolResult.ts+++ b/src/server/toolResult.ts@@ -9,7 +9,7 @@ import type { Result } from "../domain/result.js";/*** Serialize an application result as MCP text and structured content.* Shared error projection preserves actionable local diagnostics while omitting- * raw causes and captured process output.+ * raw cause objects; explicitly retained bounded command output stays visible.*/export const toCallToolResult = (result: Result<JsonValue, AnalysisError>,diff --git a/tests/boundary/binaryDiagnostics/pwntoolsLayoutProvider.test.ts b/tests/boundary/binaryDiagnostics/pwntoolsLayoutProvider.test.tsnew file mode 100644index 000000000..702458224--- /dev/null+++ b/tests/boundary/binaryDiagnostics/pwntoolsLayoutProvider.test.ts@@ -0,0 +1,691 @@+import {+ createTestWorkspace,+ removeTestWorkspace,+} from "../../support/workspace/workspaceFixture.js";+import { access, readFile, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { z } from "zod";+import { expect, it, onTestFinished } from "vitest";+import { PwntoolsLayoutProvider } from "../../../src/native/pwntools/PwntoolsLayoutProvider.js";+import { PWNTOOLS_PROVIDER_IDENTITY } from "../../../src/native/pwntools/PwntoolsRelease.js";+import { spawnOwnedProviderProcess } from "../../../src/process/ProviderProcess.js";+import { waitForProviderProcessReady } from "../../fixtures/providerProcess.js";+import { PrivateRuntimeRoot } from "../../../src/process/PrivateRuntimeRoot.js";+import { binaryLayoutFixture } from "../../fixtures/binaryDiagnostics/layout.js";+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";++const unsupportedHost = process.platform !== "linux" || process.arch !== "x64";+const requestSchema = z.strictObject({+ snapshot_path: z.string(),+ reply_path: z.string(),+});++it.runIf(!unsupportedHost).each([+ ["SIGXCPU", "reported", "cpu"],+ ["SIGXCPU", "missing", "cpu"],+ ["SIGXCPU", "malformed", "cpu"],+ ["SIGXFSZ", "reported", "file-size"],+ ["EFBIG", "reported", "file-size"],+ ["EFBIG", "malformed", "file-size"],+] as const)(+ "preserves observed %s with %s limit evidence",+ async (failure, scenario, resource) => {+ const { path } = await fixture();+ let ownedPath = "";+ const limits = {+ address_space_bytes: 3221225472,+ cpu_seconds: 1,+ file_size_bytes: 1024,+ };+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ async (spawn) => {+ ownedPath = spawn.cwd ?? "";+ if (failure === "EFBIG")+ await writeFile(join(ownedPath, "resource.failure"), "F");+ if (scenario !== "missing")+ await writeFile(+ join(ownedPath, "limits.json"),+ scenario === "reported"+ ? JSON.stringify(limits)+ : '{"cpu_seconds":999}',+ );+ return spawnOwnedProviderProcess({+ ...spawn,+ command: process.execPath,+ arguments: [+ "-e",+ failure === "EFBIG"+ ? 'process.stdout.write("resource diagnostic", () => { process.exitCode = 76; })'+ : failure === "SIGXFSZ"+ ? 'process.on("SIGXFSZ", () => { process.removeAllListeners("SIGXFSZ"); process.kill(process.pid, "SIGXFSZ"); }); process.stdout.write("resource diagnostic", () => process.kill(process.pid, "SIGXFSZ")); setTimeout(() => {}, 1000);'+ : `process.stdout.write("resource diagnostic", () => process.kill(process.pid, "${failure}"))`,+ ],+ });+ },+ );+ const result = await provider.inspect({ path });+ if (result.ok) throw new Error("Expected observed resource failure");+ const projected = projectAnalysisError(result.error);+ expect(projected).toMatchObject({+ code: "resource_constraint",+ details: {+ resource,+ reported_limits: scenario === "reported" ? limits : null,+ captured_output: { stdout: "resource diagnostic", truncated: false },+ },+ });+ expect(result.error.message).toContain(+ failure === "EFBIG"+ ? "exact write failure cause is unknown"+ : "exact signal cause is unknown",+ );+ if (scenario !== "reported")+ expect(result.error.message).toContain("limit report unavailable");+ expect(projected.remediation.action).toContain(+ resource === "cpu" ? "CPU" : "file-size",+ );+ await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" });+ },+);++it.runIf(!unsupportedHost)(+ "retains actual diagnostic truncation when output overflow and process cleanup both fail",+ async () => {+ const { path } = await fixture();+ let ownedPath = "";+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ async (spawn) => {+ ownedPath = spawn.cwd ?? "";+ const launched = await spawnOwnedProviderProcess({+ ...spawn,+ command: process.execPath,+ arguments: ["-e", 'process.stdout.write("x".repeat(1048577))'],+ });+ return {+ ...launched,+ cleanup: async () => {+ await launched.cleanup?.();+ throw new Error("injected post-cleanup reporting failure");+ },+ };+ },+ );+ const result = await provider.inspect({ path });+ if (result.ok) throw new Error("Expected compounded lifecycle failure");+ expect(result.error).toMatchObject({+ cleanupIncomplete: true,+ diagnostics: {+ reason: "injected post-cleanup reporting failure",+ previous_error: { failure_kind: "output-limit" },+ captured_output: { truncated: true, stderr: "" },+ },+ });+ await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" });+ },+);++it+ .runIf(!unsupportedHost)+ .each([+ "reserved-memory-status",+ "unmarked-memory-status",+ "unmarked-file-status",+ "wrong-marker",+ "ordinary-exit",+ "signal",+ ])(+ "requires matching private bridge failure evidence, without guessing from stderr: %s",+ async (scenario) => {+ const { path } = await fixture();+ let ownedPath = "";+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ async (spawn) => {+ ownedPath = spawn.cwd ?? "";+ if (+ scenario === "reserved-memory-status" ||+ scenario === "wrong-marker"+ )+ await writeFile(+ join(ownedPath, "resource.failure"),+ scenario === "wrong-marker" ? Buffer.from([0xcd]) : "M",+ );+ return spawnOwnedProviderProcess({+ ...spawn,+ command: process.execPath,+ arguments: [+ "-e",+ 'process.stderr.write("MemoryError-like diagnostic\\n");' ++ (scenario === "signal"+ ? 'process.kill(process.pid,"SIGKILL")'+ : `process.exit(${scenario === "unmarked-file-status" ? "76" : ["reserved-memory-status", "unmarked-memory-status", "wrong-marker"].includes(scenario) ? "75" : "7"})`),+ ],+ });+ },+ );+ const result = await provider.inspect({ path });+ if (result.ok) throw new Error("Expected explicit process failure");+ const projected = projectAnalysisError(result.error);+ expect(projected.code).toBe(+ scenario === "reserved-memory-status"+ ? "resource_constraint"+ : "execution_failure",+ );+ expect(JSON.stringify(projected)).toContain("MemoryError-like diagnostic");+ if (scenario === "reserved-memory-status")+ expect(projected.details).toMatchObject({+ resource: "memory",+ reported_limits: null,+ captured_output: { truncated: false },+ });+ await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" });+ },+);++it.runIf(!unsupportedHost).each([1048576, 1048577])(+ "keeps complete diagnostics or fails explicitly when a valid reply emits %s bytes",+ async (bytes) => {+ const { path } = await fixture();+ let ownedPath = "";+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ async (spawn) => {+ ownedPath = spawn.cwd ?? "";+ const requestPath = spawn.arguments.at(-1);+ if (requestPath === undefined) throw new Error("Request path missing");+ const request = requestSchema.parse(+ JSON.parse(await readFile(requestPath, "utf8")),+ );+ const {+ artifact: _artifact,+ diagnostics: _diagnostics,+ ...value+ } = binaryLayoutFixture(path);+ await writeFile(+ request.reply_path,+ JSON.stringify({+ ok: true,+ profile: PWNTOOLS_PROVIDER_IDENTITY.version,+ value,+ }),+ );+ return spawnOwnedProviderProcess({+ ...spawn,+ command: process.execPath,+ arguments: [+ "-e",+ `process.stdout.write("x".repeat(${String(bytes)}))`,+ ],+ });+ },+ );+ const result = await provider.inspect({ path });+ if (bytes === 1048576) {+ if (!result.ok) throw result.error;+ expect(result.value.diagnostics.stdout).toHaveLength(bytes);+ expect(result.value.diagnostics.truncated).toBe(false);+ } else {+ if (result.ok)+ throw new Error("Excess diagnostics must not return partial success");+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "unreadable_output",+ details: { captured_output: { truncated: true } },+ });+ }+ await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" });+ },+);++it.runIf(!unsupportedHost).each([+ null,+ {+ address_space_bytes: 67108864,+ cpu_seconds: 20,+ file_size_bytes: 33554432,+ },+])(+ "preserves reported memory failure, budgets, diagnostics and cleanup: %j",+ async (limits) => {+ const { path } = await fixture();+ let ownedPath = "";+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ async (spawn) => {+ ownedPath = spawn.cwd ?? "";+ const requestPath = spawn.arguments.at(-1);+ if (requestPath === undefined) throw new Error("Request path missing");+ const request = requestSchema.parse(+ JSON.parse(await readFile(requestPath, "utf8")),+ );+ await writeFile(+ request.reply_path,+ JSON.stringify({+ ok: false,+ reason: "resource-limit",+ message: "Memory allocation failed; exact cause unknown.",+ reported_limits: limits,+ }),+ );+ return spawnOwnedProviderProcess({+ ...spawn,+ command: process.execPath,+ arguments: [+ "-e",+ "process.stderr.write('upstream allocation diagnostic')",+ ],+ });+ },+ );+ const result = await provider.inspect({ path });+ if (result.ok) throw new Error("Expected resource failure");+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "resource_constraint",+ category: "resource_constraint",+ details: {+ resource: "memory",+ reported_limits: limits,+ captured_output: {+ stderr: "upstream allocation diagnostic",+ truncated: false,+ },+ },+ });+ await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" });+ expect(await readFile(path, "utf8")).toBe("source-owned-seam-bytes");+ },+);++it.runIf(!unsupportedHost).each(["cancelled", "output-limit", "process"])(+ "releases an acquired decoder and its snapshot after %s",+ async (scenario) => {+ const { path } = await fixture();+ const controller = new AbortController();+ let ownedPath = "";+ let pid: number | undefined;+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ async (spawn) => {+ ownedPath = spawn.cwd ?? "";+ const launched = await spawnOwnedProviderProcess({+ ...spawn,+ command: process.execPath,+ arguments: [+ "-e",+ scenario === "cancelled"+ ? 'process.stdout.write("ready\\n"); setInterval(() => undefined, 1000)'+ : scenario === "output-limit"+ ? 'process.stdout.write("x".repeat(1048577))'+ : 'process.stderr.write("decoder exited unexpectedly"); process.exit(7)',+ ],+ });+ pid = launched.process.pid;+ if (scenario === "cancelled") {+ await waitForProviderProcessReady(launched.process);+ setImmediate(() => controller.abort());+ }+ return launched;+ },+ );+ const result = await provider.inspect(+ { path },+ { signal: controller.signal },+ );+ expect(result).toMatchObject({+ ok: false,+ error: {+ _tag:+ scenario === "cancelled"+ ? "AnalysisCancelledError"+ : scenario === "output-limit"+ ? "AnalysisOutputError"+ : "ProviderAdapterError",+ ...(scenario === "process"+ ? {+ diagnostics: {+ exit_code: 7,+ stderr: "decoder exited unexpectedly",+ },+ }+ : {}),+ },+ });+ if (pid === undefined) throw new Error("Decoder was not acquired");+ const acquiredPid = pid;+ expect(() => process.kill(acquiredPid, 0)).toThrow();+ await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" });+ expect(await readFile(path, "utf8")).toBe("source-owned-seam-bytes");+ },+);++it.runIf(!unsupportedHost)(+ "reports private storage denial as an adapter failure rather than selected-input read denial",+ async () => {+ const { path } = await fixture();+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ undefined,+ () =>+ Promise.reject(+ Object.assign(new Error("private root denied"), { code: "EACCES" }),+ ),+ );+ expect(await provider.inspect({ path })).toMatchObject({+ ok: false,+ error: {+ _tag: "ProviderAdapterError",+ diagnostics: { phase: "decoder", reason: "private root denied" },+ },+ });+ },+);++it.runIf(!unsupportedHost)(+ "preserves a decoder failure when private-root cleanup also fails",+ async () => {+ const { path, root } = await fixture();+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ async (spawn) => {+ const requestPath = spawn.arguments.at(-1);+ if (requestPath === undefined) throw new Error("Request path missing");+ const request = requestSchema.parse(+ JSON.parse(await readFile(requestPath, "utf8")),+ );+ await writeFile(+ request.reply_path,+ JSON.stringify({+ ok: false,+ reason: "format",+ message: "Malformed original ELF table.",+ }),+ );+ return spawnOwnedProviderProcess({+ ...spawn,+ arguments: ["-e", "process.exit(0)"],+ });+ },+ () =>+ Promise.resolve({+ path: root,+ close: () => Promise.reject(new Error("root cleanup failed")),+ }),+ );+ expect(await provider.inspect({ path })).toMatchObject({+ ok: false,+ error: {+ cleanupIncomplete: true,+ cleanupResources: [root],+ diagnostics: {+ reason: "root cleanup failed",+ previous_error: { category: "invalid_input" },+ },+ },+ });+ },+);+const fixture = async () => {+ const workspace = await createTestWorkspace("rea-layout-boundary-");+ const root = workspace.root;+ onTestFinished(() => removeTestWorkspace(root));+ const path = join(root, "selected.elf");+ await writeFile(path, "source-owned-seam-bytes");+ return { root, path };+};++it.runIf(!unsupportedHost)(+ "preserves cancellation during the actual signal-aware snapshot write and closes its acquired root",+ async () => {+ const { path } = await fixture();+ const controller = new AbortController();+ let ownedPath = "";+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ () => {+ throw new Error("Decoder must not launch");+ },+ async () => {+ const root = await PrivateRuntimeRoot.create({+ prefix: "rea-layout-cancel-",+ });+ ownedPath = root.path;+ controller.abort();+ return root;+ },+ );+ expect(+ await provider.inspect({ path }, { signal: controller.signal }),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisCancelledError" } });+ await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" });+ },+);++it+ .runIf(!unsupportedHost)+ .each([+ "success",+ "format",+ "unavailable",+ "unsupported",+ "output-limit",+ "wrong-profile",+ "malformed-reply",+ ])(+ "preserves process/reply boundaries and cleans private snapshots: %s",+ async (scenario) => {+ const { root, path } = await fixture();+ let ownedPath = "";+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ async (spawn) => {+ const requestPath = spawn.arguments.at(-1);+ if (requestPath === undefined) throw new Error("request path missing");+ ownedPath = spawn.cwd ?? "";+ expect(spawn.arguments[0]).toBe("-I");+ const request = requestSchema.parse(+ JSON.parse(await readFile(requestPath, "utf8")),+ );+ expect(await readFile(request.snapshot_path, "utf8")).toBe(+ "source-owned-seam-bytes",+ );+ const {+ artifact: _artifact,+ diagnostics: _diagnostics,+ ...value+ } = binaryLayoutFixture(path);+ await writeFile(+ request.reply_path,+ scenario === "malformed-reply"+ ? "broken-json"+ : JSON.stringify(+ [+ "format",+ "unavailable",+ "unsupported",+ "output-limit",+ ].includes(scenario)+ ? {+ ok: false,+ reason: scenario,+ message: "ELF table is truncated.",+ }+ : {+ ok: true,+ profile:+ scenario === "wrong-profile"+ ? "pwntools@other"+ : PWNTOOLS_PROVIDER_IDENTITY.version,+ value,+ },+ ),+ );+ return spawnOwnedProviderProcess({+ ...spawn,+ command: process.execPath,+ arguments: ["-e", "process.stderr.write('upstream warning')"],+ });+ },+ );+ const result = await provider.inspect({ path });+ if (scenario === "success") {+ if (!result.ok) throw result.error;+ expect(result.value.artifact).toMatchObject({+ path,+ bytes: Buffer.byteLength("source-owned-seam-bytes"),+ });+ expect(result.value.artifact.sha256).toMatch(/^[a-f0-9]{64}$/);+ expect(result.value.diagnostics.stderr).toBe("upstream warning");+ } else+ expect(result).toMatchObject({+ ok: false,+ error: {+ _tag:+ scenario === "format"+ ? "AnalysisInputError"+ : scenario === "unavailable"+ ? "ProviderSelectionError"+ : scenario === "unsupported"+ ? "AnalysisCapabilityUnavailableError"+ : "AnalysisOutputError",+ },+ });+ if (!result.ok)+ expect(projectAnalysisError(result.error).details).toMatchObject({+ captured_output: {+ stdout: "",+ stderr: "upstream warning",+ truncated: false,+ },+ });+ expect(await readFile(path, "utf8")).toBe("source-owned-seam-bytes");+ expect(ownedPath.startsWith(root)).toBe(false);+ await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" });+ },+);++it.runIf(!unsupportedHost)(+ "rejects missing configuration, absent input and prelaunch cancellation distinctly",+ async () => {+ const { path } = await fixture();+ expect(+ await new PwntoolsLayoutProvider({}).inspect({ path }),+ ).toMatchObject({+ ok: false,+ error: { _tag: "ProviderSelectionError", reason: "provider_unavailable" },+ });+ const provider = new PwntoolsLayoutProvider({+ REA_PWNTOOLS_PYTHON: process.execPath,+ });+ expect(await provider.inspect({ path: path + ".absent" })).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisInputError" },+ });+ const controller = new AbortController();+ controller.abort();+ expect(+ await provider.inspect({ path }, { signal: controller.signal }),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisCancelledError" } });+ },+);+it.runIf(unsupportedHost)(+ "reports unverified host coverage before acquiring a provider",+ async () => {+ expect(+ await new PwntoolsLayoutProvider({}).inspect({ path: "/selected.elf" }),+ ).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCapabilityUnavailableError" },+ });+ },+);++it.runIf(!unsupportedHost)(+ "retains decoder warnings when cancellation arrives during successful root cleanup",+ async () => {+ const { path } = await fixture();+ const controller = new AbortController();+ let ownedPath = "";+ const provider = new PwntoolsLayoutProvider(+ { REA_PWNTOOLS_PYTHON: process.execPath },+ async (spawn) => {+ const requestPath = spawn.arguments.at(-1);+ if (requestPath === undefined) throw new Error("Request path missing");+ const request = requestSchema.parse(+ JSON.parse(await readFile(requestPath, "utf8")),+ );+ const {+ artifact: _artifact,+ diagnostics: _diagnostics,+ ...value+ } = binaryLayoutFixture(path);+ await writeFile(+ request.reply_path,+ JSON.stringify({+ ok: true,+ profile: PWNTOOLS_PROVIDER_IDENTITY.version,+ value,+ }),+ );+ return spawnOwnedProviderProcess({+ ...spawn,+ command: process.execPath,+ arguments: ["-e", 'process.stderr.write("retained late warning")'],+ });+ },+ async () => {+ const root = await PrivateRuntimeRoot.create({+ prefix: "rea-layout-late-cancel-",+ });+ ownedPath = root.path;+ return {+ path: root.path,+ close: async () => {+ await root.close();+ controller.abort();+ },+ };+ },+ );+ const result = await provider.inspect(+ { path },+ { signal: controller.signal },+ );+ expect(result).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisCancelledError" },+ });+ if (result.ok) throw new Error("Late cancellation must be preserved");+ expect(projectAnalysisError(result.error).details?.captured_output).toEqual(+ { stdout: "", stderr: "retained late warning", truncated: false },+ );+ await expect(access(ownedPath)).rejects.toMatchObject({ code: "ENOENT" });+ },+);++it.runIf(!unsupportedHost).each(["directory", "missing-interpreter"])(+ "identifies the configured executable on actual launch/preflight failure: %s",+ async (scenario) => {+ const { path, root } = await fixture();+ const executable =+ scenario === "directory" ? root : join(root, "broken-python");+ if (scenario === "missing-interpreter")+ await writeFile(+ executable,+ "#!/rea-missing-interpreter-for-boundary-test\n",+ { mode: 0o700 },+ );+ const result = await new PwntoolsLayoutProvider({+ REA_PWNTOOLS_PYTHON: executable,+ }).inspect({ path });+ if (result.ok) throw new Error("Expected unavailable executable");+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "provider_unavailable",+ details: {+ rejections: [{ diagnostics: { executable_path: executable } }],+ },+ });+ expect(result.error._tag).toBe("ProviderSelectionError");+ expect(await readFile(path, "utf8")).toBe("source-owned-seam-bytes");+ },+);diff --git a/tests/boundary/cli/productCatalog.test.ts b/tests/boundary/cli/productCatalog.test.tsindex 3e8c98b5d..c804c93e2 100644--- a/tests/boundary/cli/productCatalog.test.ts+++ b/tests/boundary/cli/productCatalog.test.ts@@ -1,3 +1,4 @@+import { PWNTOOLS_PROVIDER_IDENTITY } from "../../../src/native/pwntools/PwntoolsRelease.js";import { mkdir, readFile, rm, writeFile } from "node:fs/promises";import { join } from "node:path";import { fileURLToPath } from "node:url";@@ -115,6 +116,7 @@ describe("canonical product catalog", () => {GHIDRA_PROVIDER_IDENTITY,IDA_PROVIDER_IDENTITY,NATIVE_MACOS_PROVIDER_IDENTITY,+ PWNTOOLS_PROVIDER_IDENTITY,ARTIFACT_GRAPH_PROVIDER,ANDROID_APPLICATION_PROVIDER,APPLE_APPLICATION_PROVIDER,diff --git a/tests/boundary/mcp/binaryDiagnosticsMcp.test.ts b/tests/boundary/mcp/binaryDiagnosticsMcp.test.tsnew file mode 100644index 000000000..12ed431d9--- /dev/null+++ b/tests/boundary/mcp/binaryDiagnosticsMcp.test.ts@@ -0,0 +1,76 @@+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";+import { Ajv2020 } from "ajv/dist/2020.js";+import { expect, it, onTestFinished } from "vitest";+import { BinaryLayoutService } from "../../../src/application/binaryDiagnostics/BinaryLayoutService.js";+import { toolContract } from "../../../src/contracts/toolContracts.js";+import { parseEvidence } from "../../../src/domain/evidence.js";+import { ok } from "../../../src/domain/result.js";+import { createServer } from "../../../src/server/createServer.js";+import { createTestBinarySession } from "../../fixtures/binarySession.js";+import {+ binaryLayoutFixture,+ BINARY_LAYOUT_TEST_PROVIDER,+} from "../../fixtures/binaryDiagnostics/layout.js";++it("advertises exact valid schemas and records inline layout without a binary target", async () => {+ const value = binaryLayoutFixture();+ const service = new BinaryLayoutService({+ identity: BINARY_LAYOUT_TEST_PROVIDER,+ inspect: () => Promise.resolve(ok(value)),+ });+ const session = createTestBinarySession(() => {+ throw new Error("deep provider must not start");+ });+ const server = createServer(session, session, { binaryLayout: service });+ const client = new Client({ name: "binary-layout-contract", version: "1" });+ onTestFinished(async () => {+ await client.close();+ await server.close();+ await session.close();+ });+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ await client.connect(clientTransport);+ const advertised = (await client.listTools()).tools.find(+ (tool) => tool.name === "inspect_binary_layout",+ );+ if (advertised?.outputSchema === undefined)+ throw new Error("layout must publish both schemas");+ const ajv = new Ajv2020({ strict: false, validateFormats: false });+ const inputSchema: Record<string, unknown> = advertised.inputSchema;+ const outputSchema: Record<string, unknown> = advertised.outputSchema;+ expect(ajv.validateSchema(inputSchema)).toBe(true);+ expect(ajv.validateSchema(outputSchema)).toBe(true);+ expect(ajv.validate(inputSchema, { path: value.artifact.path })).toBe(true);+ expect(+ ajv.validate(inputSchema, {+ path: value.artifact.path,+ approval: true,+ }),+ ).toBe(false);+ const response = await client.callTool({+ name: "inspect_binary_layout",+ arguments: { path: value.artifact.path },+ });+ expect(response.isError).not.toBe(true);+ expect(+ ajv.validate(outputSchema, response.structuredContent),+ JSON.stringify(ajv.errors),+ ).toBe(true);+ const parsed = toolContract("inspect_binary_layout").outputSchema.parse(+ response.structuredContent,+ );+ const evidence = parseEvidence(parsed.evidence);+ expect(parsed.result).toEqual(value);+ expect(parsed.result).toEqual(evidence.normalized_result);+ expect(session.evidenceById(evidence.evidence_id)).toEqual(evidence);+ expect(+ (+ await client.callTool({+ name: "inspect_binary_layout",+ arguments: { path: "relative.elf" },+ })+ ).isError,+ ).toBe(true);+});diff --git a/tests/fixtures/binaryDiagnostics/layout.ts b/tests/fixtures/binaryDiagnostics/layout.tsnew file mode 100644index 000000000..28cbf03c1--- /dev/null+++ b/tests/fixtures/binaryDiagnostics/layout.ts@@ -0,0 +1,48 @@+import type { BinaryLayout } from "../../../src/domain/native/binaryLayout.js";++/** Small source-owned provider observation for validation and transport tests. */+export const binaryLayoutFixture = (+ path = "/artifacts/source-owned.elf",+): BinaryLayout => ({+ artifact: { path, sha256: "a".repeat(64), bytes: 128 },+ format: "elf",+ architecture: { machine: "EM_X86_64", bits: 64, byte_order: "little" },+ image_type: "ET_REL",+ entry_point: {+ reported_value: "0x0",+ meaning: "not-applicable",+ execution_status: "unknown",+ },+ runtime_load_base: null,+ sections: [],+ segments: [],+ symbols: [],+ relocations: [],+ packed_relative_relocations: [],+ relocation_inventory_completeness: "unknown",+ linkage: {+ needed_libraries: [],+ interpreters: [],+ got: [],+ plt: [],+ convenience_maps_completeness: "unknown",+ runtime_library_paths: null,+ },+ mitigations: {+ evidence_kind: "inferred",+ position_independent: false,+ nx_indicator: null,+ executable_stack_indicator: false,+ stack_canary_indicator: false,+ relro: null,+ },+ diagnostics: { stdout: "producer warning", stderr: "", truncated: false },+ limitations: ["Runtime addresses remain unknown."],+});++/** Producer identity belongs to the test seam, not a simulated installed engine claim. */+export const BINARY_LAYOUT_TEST_PROVIDER = {+ id: "fixture-layout",+ name: "Source-owned layout seam",+ version: "1",+} as const;diff --git a/third_party/pwntools/README.md b/third_party/pwntools/README.mdnew file mode 100644index 000000000..ed9690851--- /dev/null+++ b/third_party/pwntools/README.md@@ -0,0 +1,40 @@+# Offline ELF upstream profile++REA uses caller-supplied, unchanged Python packages. It vendors no pwntools,+pyelftools or Unicorn implementation and never installs these dependencies.++| Upstream | Exact verified profile | License | Role |+| --- | --- | --- | --- |+| [pwntools](https://github.com/Gallopsled/pwntools) | 4.15.0; tag commit `3ad86ec5adab1abf9781ca7552a6f5d7cff7a33c` | MIT | ELF analysis and static mitigation/GOT/PLT heuristics |+| [pyelftools](https://github.com/eliben/pyelftools) | 0.33 | Public domain | Original ELF sections, segments, symbols and relocations |+| [Unicorn](https://github.com/unicorn-engine/unicorn) | 2.1.2 | GPL-2.0 | Upstream PLT emulation; distinct from executing the target as a host process |++The adapter checks all three runtime versions before importing the ELF engine.+Original upstream code/licenses remain in the caller-selected environment.+No target or core binaries are committed. Fixtures are compiled in owned+temporary storage from repository source and are never executed.++`bridge/pwntools/layout.py` is an owned allocation-failure bootstrap;+`layout_impl.py` is the adapter. It reads original tables through+unchanged upstream APIs, preserves raw name bytes/ranges, and serializes uint64+values as strings. It never accesses `ELF.libs`, `ELF.maps`, `ELF.libc` or+`process.corefile`, which have materially different execution authority.++The real verification lane traces host exec syscalls, checks original artifact+hashes and observes released owned processes. No negative claim relies only on+an unmodified target's sentinel: upstream can execute a patched copy when its+runtime-library accessors are used.++The instance-local adapter subclass forwards the documented pyelftools 0.33+`iter_segments(type=...)` / `iter_sections(type=...)` filters missing from+pwntools 4.15.0 cached overrides. No upstream file or global method is changed.+Sectionless dynamic string tables use unique DT_STRTAB/DT_STRSZ mappings to+file-backed PT_LOAD bytes; ambiguous or non-file-backed mappings are explicitly+unsupported. Section-name table escapes follow the [ELF ABI](https://gabi.xinuos.com/elf/02-eheader.html):+SHN_XINDEX represents actual indices at least 0xff00; ordinary absence uses index+zero. Raw name offsets remain reported when the name table is absent.++PLT convenience inference uses the unchanged upstream Unicorn instruction+emulator. REA labels those maps as derived static evidence. The no-execution+verification claim concerns launching the selected object as a host process,+not the absence of static instruction emulation inside an analysis engine.