From 79173bb6be2f67c451b75c956f48ce9f821412f8 Mon Sep 17 00:00:00 2001 From: r0ny123 <49360849+r0ny123@users.noreply.github.com> Date: Thu, 3 Sep 2026 17:56:46 +0530 Subject: [PATCH 1/9] return an empty named-stream map when the PDB Info stream is absent, as diagnose() already promises --- purepdb/pdb.py | 7 ++++++- tests/_synth.py | 6 +++++- tests/test_diagnose.py | 22 ++++++++++++++++++++++ 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/purepdb/pdb.py b/purepdb/pdb.py index 923a797..0270ed7 100644 --- a/purepdb/pdb.py +++ b/purepdb/pdb.py @@ -1046,7 +1046,12 @@ def named_streams(self) -> dict[str, int]: `/names` and `/LinkInfo` are what real linkers put here. """ - return parse_named_stream_map(self.msf.read_stream(STREAM_PDB_INFO)) + if not self.msf.is_valid_stream(STREAM_PDB_INFO): + return {} + try: + return parse_named_stream_map(self.msf.read_stream(STREAM_PDB_INFO)) + except MsfError: + return {} def string_table(self) -> StringTable | None: """The `/names` global string table, or None when the PDB has none.""" diff --git a/tests/_synth.py b/tests/_synth.py index 8fb3705..4bda745 100644 --- a/tests/_synth.py +++ b/tests/_synth.py @@ -9,6 +9,7 @@ from __future__ import annotations import struct +from collections.abc import Sequence from purepdb.dbi import SEC_CONTRIB_V2, SEC_CONTRIB_VER60 from purepdb.msf import BIG_MSF_MAGIC @@ -18,13 +19,16 @@ def _ceil_div(a, b): return (a + b - 1) // b -def build_msf(streams: list[bytes], block_size: int = 512) -> bytes: +def build_msf(streams: Sequence[bytes | None], block_size: int = 512) -> bytes: """Serialise a list of streams into a valid MSF 7.00 container.""" bs = block_size next_block = 3 # 0=superblock, 1=FPM1, 2=FPM2 placed = [] # (size, [block indices], data) for data in streams: + if data is None: + placed.append((0xFFFFFFFF, [], b"")) + continue n = _ceil_div(len(data), bs) if data else 0 blocks = list(range(next_block, next_block + n)) next_block += n diff --git a/tests/test_diagnose.py b/tests/test_diagnose.py index b816563..75d695f 100644 --- a/tests/test_diagnose.py +++ b/tests/test_diagnose.py @@ -118,3 +118,25 @@ def test_line_info_after_the_symbols_is_not_parsed_as_records(): pdb = PDB.from_bytes(build_msf(streams)) names = [p.name for p in pdb.module_procs()] assert names == ["real"], "must stop at sym_byte_size" + + +def test_missing_pdb_info_stream_is_explained(): + mods = module_info("main.obj", "main.obj", sym_stream=5, sym_byte_size=4) + streams = [ + b"", + None, # stream 1 (PDB Info) is absent + b"", + dbi_stream(public_stream=4, symrecord_stream=7, module_list=mods, + dbg_header=[0xFFFF] * 5 + [6]), + publics_hash_stream([]), + module_sym_stream(b""), + section_header(".text", 0x1000), + b"", + ] + pdb = PDB.from_bytes(build_msf(streams)) + d = pdb.diagnose() + assert d.pdb_info_error is not None + assert d.has_string_table is False + assert any("the PDB Info stream cannot be read" in w for w in d.warnings) + assert pdb.string_table() is None + assert list(pdb.lines()) == [] From ae43f1ee5b64d0ffeb46db5c4d8ebb5629ed5845 Mon Sep 17 00:00:00 2001 From: r0ny123 <49360849+r0ny123@users.noreply.github.com> Date: Thu, 3 Sep 2026 17:57:59 +0530 Subject: [PATCH 2/9] raise MsfError instead of ValueError from PublicsStream.parse --- purepdb/gsi.py | 6 ++++-- purepdb/pdb.py | 2 +- tests/test_publics.py | 13 ++++++++++++- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/purepdb/gsi.py b/purepdb/gsi.py index 5643397..8022b2a 100644 --- a/purepdb/gsi.py +++ b/purepdb/gsi.py @@ -32,6 +32,8 @@ import struct from dataclasses import dataclass +from .msf import MsfError + _PUBLICS_HEADER = struct.Struct( " PublicsStream: if len(data) < _PUBLICS_HEADER.size: - raise ValueError("publics stream too small for its header") + raise MsfError("publics stream too small for its header") (sym_hash, addr_map_size, num_thunks, size_of_thunk, isect, _pad, off_thunk, num_sections) = _PUBLICS_HEADER.unpack_from(data, 0) start = _PUBLICS_HEADER.size + sym_hash end = start + addr_map_size if end > len(data): - raise ValueError( + raise MsfError( f"publics address map runs past end of stream " f"(need {end} bytes, have {len(data)})" ) diff --git a/purepdb/pdb.py b/purepdb/pdb.py index 0270ed7..e91a4c5 100644 --- a/purepdb/pdb.py +++ b/purepdb/pdb.py @@ -665,7 +665,7 @@ def publics_stream(self) -> PublicsStream | None: return None try: return PublicsStream.parse(self.msf.read_stream(idx)) - except (ValueError, struct.error): + except (MsfError, struct.error): return None def public_symbols(self) -> list[codeview.PublicSymbol]: diff --git a/tests/test_publics.py b/tests/test_publics.py index 02ce5a1..ce880c6 100644 --- a/tests/test_publics.py +++ b/tests/test_publics.py @@ -8,7 +8,9 @@ import struct -from purepdb import PDB +import pytest + +from purepdb import PDB, MsfError from purepdb.gsi import PublicsStream from tests._synth import ( build_msf, @@ -139,3 +141,12 @@ def test_folded_addresses_keep_every_name_as_an_alias(): assert set(fn.aliases) == {"?fold_a@@YAXXZ", "?fold_b@@YAXXZ"} assert fn.names[0] == "fold_a" assert len(fn.names) == 3 + + +def test_publics_stream_parse_raises_msf_error_on_truncated_data(): + with pytest.raises(MsfError): + PublicsStream.parse(b"") + # Header claims 100 bytes of address map, but buffer only has the 28-byte header. + hdr = struct.pack(" Date: Thu, 3 Sep 2026 17:58:29 +0530 Subject: [PATCH 3/9] validate DBI substream sizes against stream bounds and sign --- purepdb/dbi.py | 23 +++++++++++++++++++++++ tests/test_errors.py | 25 +++++++++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/purepdb/dbi.py b/purepdb/dbi.py index 419824c..e3c14ef 100644 --- a/purepdb/dbi.py +++ b/purepdb/dbi.py @@ -217,19 +217,42 @@ def parse(cls, data: bytes) -> DbiStream: ) off = _HEADER.size + + def _check_substream(name: str, size: int) -> None: + if size < 0: + raise MsfError(f"DBI {name} substream size is negative ({size})") + if off + size > len(data): + raise MsfError( + f"DBI {name} substream runs past end of stream " + f"(starts at {off}, size {size}, stream length {len(data)})" + ) + + _check_substream("ModuleInfo", modinfo_size) self.modules, self.module_list_stopped_at = _parse_module_list( data[off : off + modinfo_size] ) off += modinfo_size + + _check_substream("SectionContribution", seccontrib_size) self.section_contributions = _parse_section_contributions( data[off : off + seccontrib_size] ) off += seccontrib_size + + _check_substream("SectionMap", secmap_size) self.section_map = parse_section_map(data[off : off + secmap_size]) off += secmap_size + + _check_substream("SourceInfo", srcinfo_size) off += srcinfo_size + + _check_substream("TypeServerMap", tsmap_size) off += tsmap_size + + _check_substream("EC", ec_size) off += ec_size + + _check_substream("OptionalDebugHeader", dbg_hdr_size) self.dbg_header = _parse_dbg_header(data[off : off + dbg_hdr_size]) return self diff --git a/tests/test_errors.py b/tests/test_errors.py index 8f11573..4e65ebb 100644 --- a/tests/test_errors.py +++ b/tests/test_errors.py @@ -303,3 +303,28 @@ def test_a_module_record_with_an_unterminated_name_stops_the_walk(): pdb = PDB.from_bytes(build_msf(streams)) assert [m.module_name for m in pdb.dbi.modules] == ["main.obj"] assert pdb.functions() == [] + + +def test_dbi_substream_corrupted_sizes_raise_msf_error(): + from pathlib import Path + + fixture = Path(__file__).resolve().parent / "data" / "sqlite" / "x86" / "sqlite3.pdb" + if not fixture.exists(): + pytest.skip("fixture absent") + pdb = PDB.open(str(fixture)) + raw_dbi = pdb.msf.read_stream(3) + # Substream size slots in DBI header: + # 24: ModInfo, 28: SecContrib, 32: SecMap, 36: SrcInfo, 40: TSMap, 48: DbgHdr, 52: EC + size_offsets = [24, 28, 32, 36, 40, 48, 52] + for offset in size_offsets: + # Corrupted negative size: + corrupted = bytearray(raw_dbi) + struct.pack_into(" Date: Thu, 3 Sep 2026 17:59:57 +0530 Subject: [PATCH 4/9] report damaged C13 line info in diagnostics instead of truncating silently --- purepdb/__init__.py | 2 ++ purepdb/c13.py | 45 ++++++++++++++++++++++++++++++++++++++++++--- purepdb/pdb.py | 21 ++++++++++++++++++++- tests/test_lines.py | 36 ++++++++++++++++++++++++++++++++++++ 4 files changed, 100 insertions(+), 4 deletions(-) diff --git a/purepdb/__init__.py b/purepdb/__init__.py index 5b81bd1..95c3efd 100644 --- a/purepdb/__init__.py +++ b/purepdb/__init__.py @@ -9,6 +9,7 @@ empty list. """ +from .c13 import C13Truncation from .codeview import ( CompileInfo, Constant, @@ -48,6 +49,7 @@ __all__ = [ "PDB", + "C13Truncation", "CompileInfo", "Constant", "DataSymbol", diff --git a/purepdb/c13.py b/purepdb/c13.py index c8152f2..c40e3c9 100644 --- a/purepdb/c13.py +++ b/purepdb/c13.py @@ -78,7 +78,16 @@ class LineEntry: is_statement: bool -def iter_subsections(data: bytes): +@dataclass +class C13Truncation: + """Where a C13 subsection or line walk stopped early, and why.""" + + offset: int + reason: str + + +def iter_subsections(data: bytes, *, + truncation: list[C13Truncation] | None = None): """Yield each C13 subsection. Stops at the first header that does not fit. A subsection whose kind carries `DEBUG_S_IGNORE` is stepped over rather @@ -92,11 +101,23 @@ def iter_subsections(data: bytes): kind, length = struct.unpack_from(" len(data) - pos: + if truncation is not None: + truncation.append(C13Truncation( + pos - 8, + f"subsection {kind:#x} length {length} runs " + f"{length - (len(data) - pos)} bytes past the end of the " + f"{len(data)}-byte C13 stream", + )) return if not kind & DEBUG_S_IGNORE: yield Subsection(kind=kind, payload=data[pos : pos + length]) pos += length pos += -pos % 4 + if pos < len(data) and truncation is not None: + truncation.append(C13Truncation( + pos, + f"{len(data) - pos} trailing byte(s) are too few for a subsection header", + )) def parse_file_checksums(payload: bytes) -> dict[int, int]: @@ -116,9 +137,15 @@ def parse_file_checksums(payload: bytes) -> dict[int, int]: return out -def parse_lines(payload: bytes) -> list[LineEntry]: +def parse_lines(payload: bytes, *, + truncation: list[C13Truncation] | None = None) -> list[LineEntry]: """Decode one DEBUG_S_LINES subsection.""" if len(payload) < _LINE_FRAGMENT_HEADER.size: + if truncation is not None and len(payload) > 0: + truncation.append(C13Truncation( + 0, + f"DEBUG_S_LINES payload is {len(payload)} byte(s), too short for header", + )) return [] base_offset, segment, flags, _code_size = _LINE_FRAGMENT_HEADER.unpack_from(payload, 0) have_columns = bool(flags & LF_HAVE_COLUMNS) @@ -132,7 +159,13 @@ def parse_lines(payload: bytes) -> list[LineEntry]: if have_columns: needed += num_lines * 4 if needed > len(payload) - entries_at: - break + if truncation is not None: + truncation.append(C13Truncation( + pos, + f"line block at byte {pos:#x} needs {needed} bytes for {num_lines} " + f"lines, exceeding remaining {len(payload) - entries_at} bytes", + )) + return out for i in range(num_lines): offset, packed = _LINE_ENTRY.unpack_from(payload, entries_at + i * _LINE_ENTRY.size) @@ -149,4 +182,10 @@ def parse_lines(payload: bytes) -> list[LineEntry]: step = block_size if block_size > _LINE_BLOCK_HEADER.size else ( _LINE_BLOCK_HEADER.size + needed) pos += step + if pos < len(payload) and truncation is not None: + truncation.append(C13Truncation( + pos, + f"{len(payload) - pos} trailing byte(s) in DEBUG_S_LINES are " + f"too few for a block header", + )) return out diff --git a/purepdb/pdb.py b/purepdb/pdb.py index e91a4c5..905758c 100644 --- a/purepdb/pdb.py +++ b/purepdb/pdb.py @@ -293,6 +293,8 @@ class Diagnostics: files teaches a reader to skip the list, which costs the entries that do matter. The count and the note beside it in `purepdb diagnose` are the explanation, in the report rather than in the alarm channel.""" + c13_truncations: list[tuple[str, c13.C13Truncation]] = field(default_factory=list) + """Where a C13 line-info walk stopped short of consuming its buffer, and why.""" @property def truncated_streams(self) -> int: @@ -466,6 +468,13 @@ def warnings(self) -> list[str]: f"/names stream is not, so file-name offsets cannot be resolved " f"and lines() yields nothing" ) + if self.c13_truncations: + where, first = self.c13_truncations[0] + out.append( + f"{len(self.c13_truncations)} C13 line-info section(s) stopped early; " + f"lines after that point are missing. First: {where} at " + f"byte {first.offset:#x} ({first.reason})" + ) if self.pdb_info_error is not None: out.append( f"the PDB Info stream cannot be read ({self.pdb_info_error}), " @@ -1120,8 +1129,17 @@ def diagnose(self) -> Diagnostics: malformed = 0 malformed_inline = 0 line_bytes = 0 + c13_truncations: list[tuple[str, c13.C13Truncation]] = [] for mod in self.dbi.modules: - line_bytes += len(self.module_c13_bytes(mod)) + c13_bytes = self.module_c13_bytes(mod) + line_bytes += len(c13_bytes) + if c13_bytes: + mod_c13_report: list[c13.C13Truncation] = [] + for sub in c13.iter_subsections(c13_bytes, truncation=mod_c13_report): + if sub.kind == c13.DEBUG_S_LINES: + c13.parse_lines(sub.payload, truncation=mod_c13_report) + for t in mod_c13_report: + c13_truncations.append((f"module {mod.index} ({mod.module_name})", t)) body = self.module_symbol_bytes(mod) if not body: continue @@ -1204,6 +1222,7 @@ def diagnose(self) -> Diagnostics: pdb_info_error=pdb_info_error, module_list_stopped_at=self.dbi.module_list_stopped_at, thread_local_records=thread_locals, + c13_truncations=c13_truncations, ) def _is_code(self, segment: int) -> bool: diff --git a/tests/test_lines.py b/tests/test_lines.py index c9b69d1..3c15e43 100644 --- a/tests/test_lines.py +++ b/tests/test_lines.py @@ -315,7 +315,9 @@ def test_diagnose_reports_the_line_info_on_every_fixture(rel): d = _open(rel).diagnose() assert d.line_bytes > 0 assert d.has_string_table + assert d.c13_truncations == [] assert not any("/names" in w for w in d.warnings) + assert not any("C13 line-info" in w for w in d.warnings) def test_line_info_without_the_names_stream_is_warned_about(): @@ -347,3 +349,37 @@ def test_a_pdb_with_no_line_info_is_not_warned_about(): d = pdb.diagnose() assert d.line_bytes == 0 assert not any("/names" in w for w in d.warnings) + assert d.c13_truncations == [] + + +def test_truncated_c13_subsection_header_is_warned_about(): + # Only 4 bytes: not enough for the 8-byte (kind, length) subsection header. + pdb = _pdb(c13_region=b"\x01\x00\x00\x00") + d = pdb.diagnose() + assert len(d.c13_truncations) == 1 + assert any("C13 line-info section(s) stopped early" in w for w in d.warnings) + + +def test_c13_subsection_length_past_end_is_warned_about(): + # Header claims 500 bytes payload, but only 8 bytes remain. + region = struct.pack(" Date: Thu, 3 Sep 2026 18:00:13 +0530 Subject: [PATCH 5/9] exercise pdb.publics_stream() in the fuzzer --- tools/fuzz.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/fuzz.py b/tools/fuzz.py index 02f20fb..872f203 100644 --- a/tools/fuzz.py +++ b/tools/fuzz.py @@ -69,6 +69,7 @@ def exercise(data: bytes) -> list: pdb.original_sections, pdb.functions(), pdb.public_symbols(), + pdb.publics_stream(), pdb.module_procs(), pdb.data_symbols(), pdb.thread_locals(), From 94d854bac629218e84b138bacb92221930060506 Mon Sep 17 00:00:00 2001 From: r0ny123 <49360849+r0ny123@users.noreply.github.com> Date: Thu, 3 Sep 2026 18:00:56 +0530 Subject: [PATCH 6/9] offset inline sites by CV signature size only when stripped --- purepdb/pdb.py | 28 ++++++++++++++++++---------- tests/test_inline.py | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 10 deletions(-) diff --git a/purepdb/pdb.py b/purepdb/pdb.py index 905758c..b979b6f 100644 --- a/purepdb/pdb.py +++ b/purepdb/pdb.py @@ -698,6 +698,20 @@ def public_symbols(self) -> list[codeview.PublicSymbol]: return publics return sorted(publics, key=lambda p: rank[p.record_offset]) + def _module_symbol_bytes_and_offset(self, mod) -> tuple[bytes, int]: + """The symbol-record region of one module's stream, and the signature offset. + + Returns (bytes, CV_SIGNATURE_SIZE) when a CV_SIGNATURE_C13 signature was + stripped, or (bytes, 0) otherwise. + """ + if not mod.has_symbols or not self.msf.is_valid_stream(mod.sym_stream): + return b"", 0 + raw = self.msf.read_stream(mod.sym_stream) + end = min(mod.sym_byte_size, len(raw)) + if len(raw) >= 4 and struct.unpack_from(" bytes: """The symbol-record region of one module's stream, signature stripped. @@ -707,13 +721,7 @@ def module_symbol_bytes(self, mod) -> bytes: line-info bytes as if they were records. Returns b"" when the module has no symbols. """ - if not mod.has_symbols or not self.msf.is_valid_stream(mod.sym_stream): - return b"" - raw = self.msf.read_stream(mod.sym_stream) - end = min(mod.sym_byte_size, len(raw)) - if len(raw) >= 4 and struct.unpack_from(" bytes: """The C13 line-info region of one module's stream. @@ -878,7 +886,7 @@ def inline_sites(self) -> list[InlineFunction]: ids = self.id_table() out: list[InlineFunction] = [] for mod in self.dbi.modules: - body = self.module_symbol_bytes(mod) + body, base_offset = self._module_symbol_bytes_and_offset(mod) if not body: continue procs: list[tuple[int, codeview.ProcSymbol]] = [] @@ -886,10 +894,10 @@ def inline_sites(self) -> list[InlineFunction]: for rec in codeview.iter_records(body): try: if rec.kind in codeview.PROC_KINDS: - procs.append((rec.offset + CV_SIGNATURE_SIZE, + procs.append((rec.offset + base_offset, codeview.parse_proc(rec.kind, rec.payload))) elif rec.kind == codeview.S_INLINESITE: - sites.append((rec.offset + CV_SIGNATURE_SIZE, + sites.append((rec.offset + base_offset, codeview.parse_inline_site(rec.payload))) except EOFError: continue # shorter than its kind requires; skip the record diff --git a/tests/test_inline.py b/tests/test_inline.py index a1d2a86..8c6dfcc 100644 --- a/tests/test_inline.py +++ b/tests/test_inline.py @@ -394,3 +394,35 @@ def test_a_healthy_file_reports_no_unplaced_sites(): d = pdb.diagnose() assert (d.inline_sites, d.unplaced_inline_sites) == (1, 0) assert d.warnings == [w for w in d.warnings if "inline site" not in w] + + +def test_inline_site_in_stream_without_c13_signature(): + """When a module symbol stream does not start with CV_SIGNATURE_C13, + no 4-byte signature is stripped and offsets start at 0.""" + from tests._synth import make_record + + site = inline_site(inlinee=0x1000, annotations=bytes([0x0B, 0x04, 0x04, 0x03])) + proc = gproc32("outer", 1, 0x40, code_size=0x100) + end = make_record(codeview.S_END, b"") + end_offset = len(proc) + len(site) + module_records = proc[:8] + struct.pack(" Date: Thu, 3 Sep 2026 18:01:36 +0530 Subject: [PATCH 7/9] remove dead Reader.align, document ContributionMap, and update changelog --- CHANGELOG.md | 22 +++++++++++++++++++++- purepdb/dbi.py | 2 ++ purepdb/reader.py | 5 ----- 3 files changed, 23 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a97190..81f558f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,27 @@ resolve *differently* would be breaking, and would say so here. ## [Unreleased] -Nothing yet. +### Added + +- `Diagnostics.c13_truncations` records where and why a C13 line-info walk + stopped early, accompanied by an explanatory warning in `Diagnostics.warnings`. + `C13Truncation` is exported in `purepdb.__all__`. + +### Fixed + +- `PDB.named_streams()` returns `{}` when the PDB Info stream is absent or + invalid, matching its documented contract and preventing `MsfError` from + escaping `string_table()`, `lines()`, and `diagnose()`. +- `PublicsStream.parse()` raises `MsfError` rather than `ValueError` on + truncated input, ensuring `PdbError` remains the only exception surface a + caller must handle. +- `DbiStream.parse()` validates substream sizes as non-negative and bounded by + the stream length, raising `MsfError` on corrupted sizes instead of silently + aliasing or dropping substreams. +- `PDB.inline_sites()` adjusts procedure and inline-site offsets by + `CV_SIGNATURE_SIZE` only when a CodeView signature was actually stripped from + the module symbol stream, preventing mismatched coordinate spaces when + evaluating procedure enclosures. ## [0.5.0] - 2026-08-28 diff --git a/purepdb/dbi.py b/purepdb/dbi.py index e3c14ef..442c230 100644 --- a/purepdb/dbi.py +++ b/purepdb/dbi.py @@ -115,6 +115,7 @@ class SectionContribution: module_index: int # index into DbiStream.modules def contains(self, segment: int, offset: int) -> bool: + """Whether this contribution covers the given segment:offset.""" return self.segment == segment and self.offset <= offset < self.offset + self.size @@ -134,6 +135,7 @@ def __init__(self, contributions: list[SectionContribution]): self._keys = [(c.segment, c.offset) for c in self._sorted] def __len__(self) -> int: + """Total number of contributions, including empty ones.""" return len(self.contributions) def find(self, segment: int, offset: int) -> SectionContribution | None: diff --git a/purepdb/reader.py b/purepdb/reader.py index 4751065..3ee03a5 100644 --- a/purepdb/reader.py +++ b/purepdb/reader.py @@ -58,10 +58,5 @@ def cstring(self) -> str: self.pos = end + 1 return s.decode("utf-8", errors="replace") - def align(self, boundary: int) -> None: - rem = self.pos % boundary - if rem: - self.pos += boundary - rem - def seek(self, pos: int) -> None: self.pos = pos From 545b36451888e1a060222d721e94e4820151390b Mon Sep 17 00:00:00 2001 From: r0ny123 <49360849+r0ny123@users.noreply.github.com> Date: Thu, 3 Sep 2026 22:37:03 +0530 Subject: [PATCH 8/9] write the deliberate choices down, and raise PdbError from the publics stream Review follow-up on the audit fixes. PublicsStream.parse now raises plain PdbError rather than MsfError -- the publics stream is not an MSF container, and the exception should not claim to be one. The DBI substream bound checks carry the reason a header that lies about the bounds raises outright while in-substream damage degrades gracefully, pinned by a test that cuts a DBI stream short. The C13 re-decode in diagnose() carries its measured cost (18ms of 180ms on the 3 MB sqlite fixture) and why a header-only twin of the block walk was rejected. --- CHANGELOG.md | 10 +++++++--- purepdb/dbi.py | 11 +++++++++++ purepdb/gsi.py | 6 +++--- purepdb/pdb.py | 12 +++++++++++- tests/test_errors.py | 19 +++++++++++++++++++ tests/test_publics.py | 13 +++++++++---- 6 files changed, 60 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 81f558f..760851d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,12 +25,16 @@ resolve *differently* would be breaking, and would say so here. - `PDB.named_streams()` returns `{}` when the PDB Info stream is absent or invalid, matching its documented contract and preventing `MsfError` from escaping `string_table()`, `lines()`, and `diagnose()`. -- `PublicsStream.parse()` raises `MsfError` rather than `ValueError` on +- `PublicsStream.parse()` raises `PdbError` rather than `ValueError` on truncated input, ensuring `PdbError` remains the only exception surface a - caller must handle. + caller must handle. Plain `PdbError` rather than `MsfError`: the publics + stream is not an MSF container. - `DbiStream.parse()` validates substream sizes as non-negative and bounded by the stream length, raising `MsfError` on corrupted sizes instead of silently - aliasing or dropping substreams. + aliasing or dropping substreams. This includes a DBI stream shorter than its + header claims, which now raises rather than degrading to a partial module + list -- the graceful paths cover damage inside substreams, not a header that + lies about the bounds themselves. - `PDB.inline_sites()` adjusts procedure and inline-site offsets by `CV_SIGNATURE_SIZE` only when a CodeView signature was actually stripped from the module symbol stream, preventing mismatched coordinate spaces when diff --git a/purepdb/dbi.py b/purepdb/dbi.py index 442c230..7b7ab30 100644 --- a/purepdb/dbi.py +++ b/purepdb/dbi.py @@ -220,6 +220,17 @@ def parse(cls, data: bytes) -> DbiStream: off = _HEADER.size + # Both checks here are deliberate, and the second one is a choice. + # A negative size slices backwards, aliasing the header or an earlier + # substream -- bytes that were never substream data at all. A size past + # the stream end means the header's own arithmetic disagrees with the + # container holding it. Both are container-level damage, so both raise: + # the graceful degradation further down -- a module list that stops + # mid-record (`module_list_stopped_at`), record walks that report a + # `codeview.Truncation` -- is for damage *inside* a substream whose + # bounds the header describes correctly. Deciding whether damage is + # contained is not a judgement made from bytes the header has already + # lied about. def _check_substream(name: str, size: int) -> None: if size < 0: raise MsfError(f"DBI {name} substream size is negative ({size})") diff --git a/purepdb/gsi.py b/purepdb/gsi.py index 8022b2a..02270bb 100644 --- a/purepdb/gsi.py +++ b/purepdb/gsi.py @@ -32,7 +32,7 @@ import struct from dataclasses import dataclass -from .msf import MsfError +from .msf import PdbError _PUBLICS_HEADER = struct.Struct( " PublicsStream: if len(data) < _PUBLICS_HEADER.size: - raise MsfError("publics stream too small for its header") + raise PdbError("publics stream too small for its header") (sym_hash, addr_map_size, num_thunks, size_of_thunk, isect, _pad, off_thunk, num_sections) = _PUBLICS_HEADER.unpack_from(data, 0) start = _PUBLICS_HEADER.size + sym_hash end = start + addr_map_size if end > len(data): - raise MsfError( + raise PdbError( f"publics address map runs past end of stream " f"(need {end} bytes, have {len(data)})" ) diff --git a/purepdb/pdb.py b/purepdb/pdb.py index b979b6f..cfd775b 100644 --- a/purepdb/pdb.py +++ b/purepdb/pdb.py @@ -674,7 +674,7 @@ def publics_stream(self) -> PublicsStream | None: return None try: return PublicsStream.parse(self.msf.read_stream(idx)) - except (MsfError, struct.error): + except (PdbError, struct.error): return None def public_symbols(self) -> list[codeview.PublicSymbol]: @@ -1142,6 +1142,16 @@ def diagnose(self) -> Diagnostics: c13_bytes = self.module_c13_bytes(mod) line_bytes += len(c13_bytes) if c13_bytes: + # The truncation reports come from re-decoding every + # DEBUG_S_LINES payload here and discarding the entries: + # 18ms of the 180ms diagnose() costs on the 3 MB sqlite + # fixture. Deliberate, for the same reason + # `count_malformed_records` runs twice per module below -- + # `parse_lines` is the only implementation of the block walk, + # and a header-only twin kept beside it would drift from it. + # `lines()` cannot be reused for this: it is a generator a + # caller may never consume, and it resolves file names, + # which this loop does not want. mod_c13_report: list[c13.C13Truncation] = [] for sub in c13.iter_subsections(c13_bytes, truncation=mod_c13_report): if sub.kind == c13.DEBUG_S_LINES: diff --git a/tests/test_errors.py b/tests/test_errors.py index 4e65ebb..56cf3d5 100644 --- a/tests/test_errors.py +++ b/tests/test_errors.py @@ -328,3 +328,22 @@ def test_dbi_substream_corrupted_sizes_raise_msf_error(): struct.pack_into(" Date: Sat, 12 Sep 2026 20:47:30 +0000 Subject: [PATCH 9/9] read a DBI stream cut short as far as it goes, and say so; report C13 padding as padding Two of the checks this branch added were sharper than the contract allows. A substream size past the end of the DBI stream raised MsfError out of PDB.open(), which turned a file missing the last eight bytes of its debug header -- every function recoverable -- into one that would not open, with no diagnostic to say why; the negative size still raises, because the next offset then goes backwards and every later slice aliases bytes that were never substream data, but the overrun is now read as far as the stream goes, recorded in DbiStream.substream_overrun, and reported by diagnose() as Diagnostics.dbi_overrun with a warning naming the substream. And a C13 region ending in a few zero bytes -- a producer rounding it up -- was reported as lines going missing when none did; fewer than eight bytes cannot be a header, and only bytes with something in them are evidence of a cut. The inline-site coordinate change is not observable on a well-formed stream, and its test now says so and adds the one input where the two spaces disagree, a damaged End two bytes past the site. The CLI's diagnose gets a test for the C13 warning it prints. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017jQKALSgFN7VecWTqzWSmD --- CHANGELOG.md | 29 +++++++++++++-------- purepdb/c13.py | 7 ++++-- purepdb/dbi.py | 60 +++++++++++++++++++++++--------------------- purepdb/pdb.py | 14 +++++++++++ tests/test_cli.py | 23 +++++++++++++++++ tests/test_errors.py | 52 ++++++++++++++++++++++++++------------ tests/test_inline.py | 20 ++++++++++++++- tests/test_lines.py | 23 +++++++++++++++++ 8 files changed, 170 insertions(+), 58 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 760851d..43b1df7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,16 +29,25 @@ resolve *differently* would be breaking, and would say so here. truncated input, ensuring `PdbError` remains the only exception surface a caller must handle. Plain `PdbError` rather than `MsfError`: the publics stream is not an MSF container. -- `DbiStream.parse()` validates substream sizes as non-negative and bounded by - the stream length, raising `MsfError` on corrupted sizes instead of silently - aliasing or dropping substreams. This includes a DBI stream shorter than its - header claims, which now raises rather than degrading to a partial module - list -- the graceful paths cover damage inside substreams, not a header that - lies about the bounds themselves. -- `PDB.inline_sites()` adjusts procedure and inline-site offsets by - `CV_SIGNATURE_SIZE` only when a CodeView signature was actually stripped from - the module symbol stream, preventing mismatched coordinate spaces when - evaluating procedure enclosures. +- `DbiStream.parse()` checks its substream sizes. A negative one raises + `MsfError`: it makes the next substream's offset go backwards, so every + later slice would alias bytes that were never substream data. A size past + the end of the stream is read as far as the stream goes and recorded in + `DbiStream.substream_overrun`, which `diagnose()` reports as + `Diagnostics.dbi_overrun` with a warning naming the substream -- a file + missing the last eight bytes of its debug header still yields every + function, and now says what it is missing. (Raising for the overrun too was + tried on this branch and reverted: it turned such a file into one that + would not open, with no diagnostic to say why.) +- C13 trailing bytes are reported as a truncation only when they hold + something. Fewer than eight bytes after the last subsection cannot be a + header; zero ones are a producer's padding, and the lines before them are + all present. +- `PDB.inline_sites()` compares a site's offset against its procedure's End in + the stream's own coordinate space, adding `CV_SIGNATURE_SIZE` only when a + signature was actually stripped. Not observable on a well-formed stream -- + a site precedes the S_END its procedure names by more than four bytes -- but + the two offsets were being compared in different spaces. ## [0.5.0] - 2026-08-28 diff --git a/purepdb/c13.py b/purepdb/c13.py index c40e3c9..a44159c 100644 --- a/purepdb/c13.py +++ b/purepdb/c13.py @@ -113,7 +113,10 @@ def iter_subsections(data: bytes, *, yield Subsection(kind=kind, payload=data[pos : pos + length]) pos += length pos += -pos % 4 - if pos < len(data) and truncation is not None: + # Fewer than eight bytes after the last subsection cannot be a header. + # Zero bytes there are padding -- a producer rounding the region up -- + # and only bytes with something in them are evidence of a cut. + if pos < len(data) and truncation is not None and any(data[pos:]): truncation.append(C13Truncation( pos, f"{len(data) - pos} trailing byte(s) are too few for a subsection header", @@ -182,7 +185,7 @@ def parse_lines(payload: bytes, *, step = block_size if block_size > _LINE_BLOCK_HEADER.size else ( _LINE_BLOCK_HEADER.size + needed) pos += step - if pos < len(payload) and truncation is not None: + if pos < len(payload) and truncation is not None and any(payload[pos:]): truncation.append(C13Truncation( pos, f"{len(payload) - pos} trailing byte(s) in DEBUG_S_LINES are " diff --git a/purepdb/dbi.py b/purepdb/dbi.py index 7b7ab30..0c1afb1 100644 --- a/purepdb/dbi.py +++ b/purepdb/dbi.py @@ -164,6 +164,11 @@ class DbiStream: Non-None means `modules` is short: the modules past that point were never read, and every symbol in their streams is absent.""" + substream_overrun: str | None = None + """The first substream whose declared size ran past the end of the DBI + stream, or None. That substream was read as far as the stream goes and + every one after it as empty, so modules, contributions, the section map + or the debug-header slots may be missing -- which `diagnose()` says.""" def dbg_stream(self, slot: int) -> int: """The stream index in an Optional Debug Header slot, or 0xFFFF.""" @@ -220,52 +225,49 @@ def parse(cls, data: bytes) -> DbiStream: off = _HEADER.size - # Both checks here are deliberate, and the second one is a choice. - # A negative size slices backwards, aliasing the header or an earlier - # substream -- bytes that were never substream data at all. A size past - # the stream end means the header's own arithmetic disagrees with the - # container holding it. Both are container-level damage, so both raise: - # the graceful degradation further down -- a module list that stops - # mid-record (`module_list_stopped_at`), record walks that report a - # `codeview.Truncation` -- is for damage *inside* a substream whose - # bounds the header describes correctly. Deciding whether damage is - # contained is not a judgement made from bytes the header has already - # lied about. - def _check_substream(name: str, size: int) -> None: + # The two ways a substream size can be wrong are not the same kind of + # wrong. A negative size makes the *next* substream's offset go + # backwards, so every later slice aliases the header or an earlier + # substream -- bytes that were never substream data -- and anything + # read from them is fiction. That raises. A size past the end of the + # stream is a stream cut short: what is there is real, the parsers + # below already stop at the end of what they are handed, and a file + # missing the last eight bytes of its debug header used to yield every + # function. So it is read as far as it goes and recorded, once, where + # `diagnose()` can turn it into a sentence -- an empty result with an + # explanation rather than a refusal, which is the contract. + def _check_substream(name: str, size: int) -> int: if size < 0: raise MsfError(f"DBI {name} substream size is negative ({size})") if off + size > len(data): - raise MsfError( - f"DBI {name} substream runs past end of stream " - f"(starts at {off}, size {size}, stream length {len(data)})" - ) - - _check_substream("ModuleInfo", modinfo_size) + if self.substream_overrun is None: + self.substream_overrun = ( + f"the {name} substream starts at byte {off} and claims " + f"{size} bytes of a {len(data)}-byte stream") + return max(0, len(data) - off) + return size + + modinfo_size = _check_substream("ModuleInfo", modinfo_size) self.modules, self.module_list_stopped_at = _parse_module_list( data[off : off + modinfo_size] ) off += modinfo_size - _check_substream("SectionContribution", seccontrib_size) + seccontrib_size = _check_substream("SectionContribution", seccontrib_size) self.section_contributions = _parse_section_contributions( data[off : off + seccontrib_size] ) off += seccontrib_size - _check_substream("SectionMap", secmap_size) + secmap_size = _check_substream("SectionMap", secmap_size) self.section_map = parse_section_map(data[off : off + secmap_size]) off += secmap_size - _check_substream("SourceInfo", srcinfo_size) - off += srcinfo_size - - _check_substream("TypeServerMap", tsmap_size) - off += tsmap_size - - _check_substream("EC", ec_size) - off += ec_size + off += _check_substream("SourceInfo", srcinfo_size) + off += _check_substream("TypeServerMap", tsmap_size) + off += _check_substream("EC", ec_size) - _check_substream("OptionalDebugHeader", dbg_hdr_size) + dbg_hdr_size = _check_substream("OptionalDebugHeader", dbg_hdr_size) self.dbg_header = _parse_dbg_header(data[off : off + dbg_hdr_size]) return self diff --git a/purepdb/pdb.py b/purepdb/pdb.py index cfd775b..a426be4 100644 --- a/purepdb/pdb.py +++ b/purepdb/pdb.py @@ -295,6 +295,11 @@ class Diagnostics: explanation, in the report rather than in the alarm channel.""" c13_truncations: list[tuple[str, c13.C13Truncation]] = field(default_factory=list) """Where a C13 line-info walk stopped short of consuming its buffer, and why.""" + dbi_overrun: str | None = None + """A DBI substream whose declared size ran past the stream, if any. It was + read as far as the stream goes and the substreams after it as empty, so + modules, section contributions, the section map or the debug-header slots + may be missing.""" @property def truncated_streams(self) -> int: @@ -425,6 +430,14 @@ def warnings(self) -> list[str]: "is in the pre-optimisation address space and does not match " "the shipped image" ) + if self.dbi_overrun is not None: + out.append( + f"the DBI stream is shorter than its header claims " + f"({self.dbi_overrun}); that substream was read as far as the " + f"stream goes and the ones after it as empty, so modules, " + f"section contributions, the section map or the debug-header " + f"slots may be missing" + ) if self.module_list_stopped_at is not None: out.append( f"the module list stopped at byte " @@ -1239,6 +1252,7 @@ def diagnose(self) -> Diagnostics: has_string_table=self.string_table() is not None, pdb_info_error=pdb_info_error, module_list_stopped_at=self.dbi.module_list_stopped_at, + dbi_overrun=self.dbi.substream_overrun, thread_local_records=thread_locals, c13_truncations=c13_truncations, ) diff --git a/tests/test_cli.py b/tests/test_cli.py index aa9871b..cc9aa99 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -445,6 +445,29 @@ def test_modules_accounts_for_a_contribution_with_no_module(tmp_path, capsys): assert err[:2] == ["", "1 modules"] +def test_diagnose_reports_a_c13_section_that_stops_early(tmp_path, capsys): + from purepdb import c13 + from tests._synth import names_stream, pdb_info_stream + + symbols = gproc32("main", 1, 0x10) + region = struct.pack("= proc.end`. What the change is + for is the coordinate space itself -- one stream offset compared against + another -- and the second half of this test, a damaged End pointing two + bytes past the site, is the one input where the two spaces disagree. + """ from tests._synth import make_record site = inline_site(inlinee=0x1000, annotations=bytes([0x0B, 0x04, 0x04, 0x03])) @@ -426,3 +434,13 @@ def test_inline_site_in_stream_without_c13_signature(): assert len(found) == 1 assert found[0].name == "helper" assert found[0].parent == "outer" + + # A damaged End two bytes past the site's own offset: in the signature's + # coordinate space (+4) the site would read as outside its procedure and + # be dropped; in the stream's, where End was written, it is inside. + damaged = proc[:8] + struct.pack("