feat(debug-files): extract embedded Portable PDBs from managed PEs

[BYK]

What

sentry debug-files upload now automatically extracts a Portable PDB embedded inside a managed .NET PE assembly (debug directory entry type 17, deflate-compressed) and uploads it as a separate <name>.pdb debug file — faithful to legacy sentry-cli's extract_embedded_ppdb.

Consumes the new WASM API from @sentry/symbolic@13.7.0 (bumped from 13.5.0):
ObjectFile.asPe() → PeFile.embeddedPpdb() (shipped in getsentry/symbolic#1004).

Why the extraction lives at the prepare stage

A managed PE's debug info lives entirely in its embedded Portable PDB, so the PE object itself typically reports no debug features and is dropped by the feature filter. Extraction therefore happens in prepareDifs (not in buildDifList over already-prepared files), independent of whether the PE passed the filters — mirroring legacy, which extracts from any PE with a debug id.

The standalone extracted PPDB bytes are then run through the same per-object filters as any other file, so it:

• honors --type portablepdb (a PE excluded by the pe-format filter is still read when portablepdb is wanted),
• honors feature and --id filters,
• is size-gated against the server's advertised max file size,
• dedupes normally (debug id + content hash),
• and works for PEs found inside scanned .zip archives.

Extraction/decompression errors are swallowed (logged at debug level) so a malformed embed never aborts the scan.

Tests

• test/lib/dif/embedded-ppdb.test.ts — unit tests for extractEmbeddedPpdb (positive/negative, standalone-PPDB round-trip) against small committed .NET PE fixtures.
• test/commands/debug-files/upload.test.ts — command-level: dry-run queues the .pdb, --type portablepdb extracts it, --type elf ignores it, PE-without-embed yields nothing, and the PPDB is threaded through to uploadDebugFiles.

Fixtures (embedded-ppdb.dll, pe-no-ppdb.dll) are the small Sentry sample console binaries from symbolic-testutils.

Verified locally: typecheck, lint, test (350 debug-files/dif/scan tests), check:deps, check:fragments all green.

Notes

• Part of the CLI ↔ symbolic WASM consumption series; sibling PR (IL2CPP line mappings, --il2cpp-mapping) to follow.
• Soft-follows the shared-walker refactor (refactor(debug-files): scan paths via shared walkFiles walker #1150) but touches different functions (prepare stage), so it's independent.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-1163/
Built to branch gh-pages at 2026-07-02 09:30 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Codecov Results 📊

✅ Patch coverage is 85.00%. Project has 5142 uncovered lines.
✅ Project coverage is 81.49%. Comparing base (base) to head (head).

Files with missing lines (2)

File	Patch %	Lines
src/lib/dif/scan.ts	83.33%	⚠️ 8 Missing and 3 partials
src/lib/dif/index.ts	91.67%	⚠️ 1 Missing

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    81.49%    81.49%        —%
==========================================
  Files          399       399         —
  Lines        27744     27787       +43
  Branches     18025     18049       +24
==========================================
+ Hits         22609     22645       +36
- Misses        5135      5142        +7
- Partials      1859      1861        +2

---

Generated by Codecov Action

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 07eed3d. Configure here.}

[cursor]

Oversized PE skips embedded PPDB

Medium Severity

In prepareFileDif, when a PE’s on-disk size exceeds maxFileSize, the scan returns before reading the file, so embeddedPpdbDif never runs. The PR treats the decompressed Portable PDB as the upload payload and size-gates that blob separately; a large assembly with a small embedded PDB is dropped even though the extracted .pdb would be within the limit.

 

^{Reviewed by Cursor Bugbot for commit 07eed3d. Configure here.}

[BYK]

Intentional tradeoff, declining. The scanner deliberately never buffers a file that exceeds maxFileSize (see the size gate here and in the ZIP path) — this reader loads whole files into memory rather than memory-mapping them like the legacy Rust CLI, so that invariant is what bounds peak memory across a scan.

Reading an over-cap PE purely to extract a smaller embedded PPDB would break that invariant for every over-cap PE encountered (including large native PEs that carry no PPDB), which is exactly what the gate exists to prevent. In practice maxFileSize is the server-advertised cap (typically ≥1–2 GiB), and a managed .NET assembly that large does not occur, so the embedded PPDB of an over-cap PE is a case we accept skipping. The extracted PPDB is still independently size-gated on the normal (in-cap PE) path.

If a low-cap self-hosted configuration ever makes this matter, the right follow-up is a separate, bounded read budget for PPDB-only extraction — tracked as a follow-up rather than bundled here.