Commence setting up parsing for the final PortableExecutable data directory (debug).

Author: mjr4077au

.github/copilot-instructions.md

@@ -146,11 +146,15 @@ When working on the PowerShell module in VS Code:
 - **Resource Management**: Use nested try/finally blocks for COM cleanup and resource management rather than flat structures with nullable checks, even if it results in deep indentation.
 - **Null Checks**: When checking if a method returns a non-null value and using it, prefer pattern matching with `is` to tightly scope the variable: `if (Method() is Type variable) { ... }` instead of `var variable = Method(); if (variable != null) { ... }`. This scopes the variable to the branch where it's needed and makes the code more robust.
 - **Inline Factory Method Usage**: When a factory method already provides context for what a value represents (e.g., `FromOrdinal()`), inline the expression directly rather than storing it in a temporary variable first. Example: prefer `entries.Add(DelayImportEntry.FromOrdinal((ushort)(thunkData & 0xFFFF)));` over creating a temporary `ushort ordinal = ...` variable.
+- **Ternary Expression Formatting**: Favor the positive/valid scenario first. Example: `size >= HeaderSize ? new Instance(...) : null` instead of `size < HeaderSize ? null : new Instance(...)`. The only exception is when throwing - check for the invalid condition first, then throw.
 - **ThrowIfNullOrWhiteSpace Usage**: When using the `ThrowIfNullOrWhiteSpace` extension method, do not pass explicit `nameof()` arguments — rely on the `[CallerMemberName]` attribute to automatically populate the name parameter.
 - **SafeHandle Validation**: When validating SafeHandle parameters, avoid standalone `ThrowIfNullOrInvalid` or `ThrowIfNullOrClosed` calls that discard return values; inline the call into the subsequent usage (e.g., chain into `DangerousAddRef` or PInvoke argument).
 - **RemoveFontResource Input**: Do not pre-validate `RemoveFontResource` input with file existence checks; it can operate on file names and not necessarily full paths.
 - **Named Pipe Security**: Preserve strict named pipe security and reject solutions that weaken ACLs (e.g., creating pipes without explicit PipeSecurity).
 
+### File Modification Guidelines
+- **One Class Per File**: Each class should have its own dedicated file. Do not put multiple classes/records in a single file.
+
 ### Testing Strategy
 `powershell.exe -ExecutionPolicy Bypass -File build.ps1`
 

src/PSADT/PSADT.Interop/CODEVIEW_SIGNATURE.cs

@@ -0,0 +1,34 @@
+namespace PSADT.Interop
+{
+    /// <summary>
+    /// Defines the various CODEVIEW format signatures used for debugging information.
+    /// </summary>
+    /// <remarks>Each value corresponds to a specific version of the CODEVIEW format, which is essential for
+    /// interpreting debugging data correctly.</remarks>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1008:Enums should have zero value", Justification = "These are signature values, not flags.")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1028:Enum Storage should be Int32", Justification = "The type is correct for the underlying Win32 API.")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Naming", "CA1707:Identifiers should not contain underscores", Justification = "These values are precisely as they're defined in the Win32 API.")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Naming", "CA1712:Do not prefix enum values with type name", Justification = "These are as they're defined within the API.")]
+    public enum CODEVIEW_SIGNATURE : uint
+    {
+        /// <summary>
+        /// Represents the signature for the CODEVIEW format version NB09.
+        /// </summary>
+        CODEVIEW_SIGNATURE_NB09 = 0x3930424E,
+
+        /// <summary>
+        /// Represents the signature for the CODEVIEW format version NB10, which is associated with PDB 2.0 files.
+        /// </summary>
+        CODEVIEW_SIGNATURE_NB10 = 0x3031424E,
+
+        /// <summary>
+        /// Represents the signature for the CODEVIEW format version NB11.
+        /// </summary>
+        CODEVIEW_SIGNATURE_NB11 = 0x3131424E,
+
+        /// <summary>
+        /// Represents the signature for the RSDS code view format, used in debugging information.
+        /// </summary>
+        CODEVIEW_SIGNATURE_RSDS = 0x53445352,
+    }
+}

src/PSADT/PSADT.Interop/FRAME.cs

@@ -0,0 +1,45 @@
+namespace PSADT.Interop
+{
+    /// <summary>
+    /// Defines the various frame types used in Windows structured exception handling and API interactions.
+    /// </summary>
+    /// <remarks>This enumeration includes constants that represent specific frame types, which are essential
+    /// for low-level programming scenarios involving exception handling, stack unwinding, and thread-specific storage
+    /// in Windows environments.</remarks>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1028:Enum Storage should be Int32", Justification = "<Pending>")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Naming", "CA1707:Identifiers should not contain underscores", Justification = "<Pending>")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Naming", "CA1712:Do not prefix enum values with type name", Justification = "<Pending>")]
+    public enum FRAME : byte
+    {
+        /// <summary>
+        /// Represents the FRAME_FPO frame type used in Windows structured exception handling.
+        /// </summary>
+        /// <remarks>This constant corresponds to the FRAME_FPO value defined in the Windows.Win32.PInvoke
+        /// namespace. It is typically used to identify a specific frame type when working with low-level exception
+        /// handling or stack unwinding operations in Windows environments.</remarks>
+        FRAME_FPO = (byte)Windows.Win32.PInvoke.FRAME_FPO,
+
+        /// <summary>
+        /// Represents the constant value for FRAME_TRAP used in Windows API calls.
+        /// </summary>
+        /// <remarks>This constant is typically used in low-level programming scenarios involving Windows
+        /// API interactions, particularly in the context of frame manipulation.</remarks>
+        FRAME_TRAP = (byte)Windows.Win32.PInvoke.FRAME_TRAP,
+
+        /// <summary>
+        /// Represents the FRAME_TSS structure used for thread-specific storage in Windows API operations.
+        /// </summary>
+        /// <remarks>This field references the FRAME_TSS structure defined in the Windows.Win32.PInvoke
+        /// namespace, which facilitates management of thread-specific data in Windows environments. Use this member
+        /// when interacting with APIs that require thread-local storage structures.</remarks>
+        FRAME_TSS = (byte)Windows.Win32.PInvoke.FRAME_TSS,
+
+        /// <summary>
+        /// Represents a constant value indicating that a frame is non-FPO (Frame Pointer Omission).
+        /// </summary>
+        /// <remarks>This constant is used in the context of Windows API calls to specify the frame type
+        /// for stack unwinding. It is important for developers working with low-level memory management and
+        /// debugging.</remarks>
+        FRAME_NONFPO = (byte)Windows.Win32.PInvoke.FRAME_NONFPO,
+    }
+}

src/PSADT/PSADT.Interop/IMAGE_DEBUG_POGO_SIGNATURE.cs

@@ -0,0 +1,52 @@
+namespace PSADT.Interop
+{
+    /// <summary>
+    /// Defines the set of signatures used to identify Profile-Guided Optimization (PGO) debug information within image
+    /// files. These signatures distinguish between various optimization techniques, such as Link-Time Code Generation
+    /// (LTCG), standard PGO, and sample-based PGO, enabling tools and compilers to interpret and process optimization
+    /// data appropriately.
+    /// </summary>
+    /// <remarks>This enumeration is intended for internal use when parsing or generating image files that
+    /// contain PGO-related debug information. Each value corresponds to a specific optimization strategy or data
+    /// format, which may affect how the debug information is handled during compilation or analysis. Refer to official
+    /// documentation or relevant image file specifications for details on the meaning and usage of each
+    /// signature.</remarks>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1008:Enums should have zero value", Justification = "These are signature values, not flags.")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1028:Enum Storage should be Int32", Justification = "The type is correct for the underlying Win32 API.")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Naming", "CA1707:Identifiers should not contain underscores", Justification = "These values are precisely as they're defined in the Win32 API.")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Naming", "CA1712:Do not prefix enum values with type name", Justification = "These are as they're defined within the API.")]
+    public enum IMAGE_DEBUG_POGO_SIGNATURE : uint
+    {
+        /// <summary>
+        /// Represents the signature for the POGO (Profile-Guided Optimization) debug information in the context of
+        /// Link-Time Code Generation (LTCG).
+        /// </summary>
+        /// <remarks>https://github.com/winsiderss/systeminformer/blob/af8f8d245a5e8c934bbbe5de9de3869974f56a4e/phnt/include/ntimage.h#L34</remarks>
+        IMAGE_DEBUG_POGO_SIGNATURE_LTCG = 0x4C544347,
+
+        /// <summary>
+        /// Represents the signature for the POGO (Profile-Guided Optimization) debug information in an image file.
+        /// </summary>
+        /// <remarks>https://github.com/winsiderss/systeminformer/blob/af8f8d245a5e8c934bbbe5de9de3869974f56a4e/phnt/include/ntimage.h#L35</remarks>
+        IMAGE_DEBUG_POGO_SIGNATURE_PGI = 0x50474900,
+
+        /// <summary>
+        /// Represents the signature for Profile-Guided Optimization (PGO) data in image debug information.
+        /// </summary>
+        /// <remarks>https://github.com/winsiderss/systeminformer/blob/af8f8d245a5e8c934bbbe5de9de3869974f56a4e/phnt/include/ntimage.h#L36</remarks>
+        IMAGE_DEBUG_POGO_SIGNATURE_PGO = 0x50474F00,
+
+        /// <summary>
+        /// Represents the signature for the POGO (Profile-Guided Optimization) debug information in an image.
+        /// </summary>
+        /// <remarks>https://github.com/winsiderss/systeminformer/blob/af8f8d245a5e8c934bbbe5de9de3869974f56a4e/phnt/include/ntimage.h#L37</remarks>
+        IMAGE_DEBUG_POGO_SIGNATURE_PGU = 0x50475500,
+
+        /// <summary>
+        /// Represents the signature for the SPGO (Sample-Based Profile-Guided Optimization) debug information in an
+        /// image.
+        /// </summary>
+        /// <remarks>https://github.com/winsiderss/systeminformer/blob/af8f8d245a5e8c934bbbe5de9de3869974f56a4e/phnt/include/ntimage.h#L38</remarks>
+        IMAGE_DEBUG_POGO_SIGNATURE_SPGO = 0x5350474F,
+    }
+}

src/PSADT/PSADT.Interop/IMAGE_DEBUG_TYPE.cs

@@ -51,10 +51,86 @@ public enum IMAGE_DEBUG_TYPE : uint
         /// </summary>
         IMAGE_DEBUG_TYPE_FIXUP = Windows.Win32.System.Diagnostics.Debug.IMAGE_DEBUG_TYPE.IMAGE_DEBUG_TYPE_FIXUP,
 
+        /// <summary>
+        /// Represents OMAP (Optimized MAP) data for mapping from optimized addresses to source addresses.
+        /// </summary>
+        /// <remarks>Contains an array of OMAP structures used when code has been optimized and addresses
+        /// have been rearranged. Each entry maps an RVA to its original RVA.</remarks>
+        IMAGE_DEBUG_TYPE_OMAP_TO_SRC = 7,
+
+        /// <summary>
+        /// Represents OMAP (Optimized MAP) data for mapping from source addresses to optimized addresses.
+        /// </summary>
+        /// <remarks>Contains an array of OMAP structures used when code has been optimized and addresses
+        /// have been rearranged. Each entry maps an original RVA to its optimized RVA.</remarks>
+        IMAGE_DEBUG_TYPE_OMAP_FROM_SRC = 8,
+
         /// <summary>
         /// Represents the Borland debug type in the Windows debugging system.
         /// </summary>
         /// <remarks>This value identifies debug information specific to Borland compilers.</remarks>
         IMAGE_DEBUG_TYPE_BORLAND = Windows.Win32.System.Diagnostics.Debug.IMAGE_DEBUG_TYPE.IMAGE_DEBUG_TYPE_BORLAND,
+
+        /// <summary>
+        /// Reserved for future use (also known as BBT - Branch Boundary Table).
+        /// </summary>
+        IMAGE_DEBUG_TYPE_BBT = 10,
+
+        /// <summary>
+        /// Contains a CLSID (Class ID) GUID.
+        /// </summary>
+        IMAGE_DEBUG_TYPE_CLSID = 11,
+
+        /// <summary>
+        /// Contains Visual C++ feature information including compiler flags and counts.
+        /// </summary>
+        /// <remarks>Contains five uint values: PreVC11, C/C++, /GS, /sdl, and guardN counts.</remarks>
+        IMAGE_DEBUG_TYPE_VC_FEATURE = 12,
+
+        /// <summary>
+        /// Contains Profile Guided Optimization (POGO) information.
+        /// </summary>
+        /// <remarks>Contains a signature followed by POGO entries with RVA, size, and name for each section.</remarks>
+        IMAGE_DEBUG_TYPE_POGO = 13,
+
+        /// <summary>
+        /// Indicates Incremental Link Time Code Generation was used.
+        /// </summary>
+        /// <remarks>This is a marker type with no associated data.</remarks>
+        IMAGE_DEBUG_TYPE_ILTCG = 14,
+
+        /// <summary>
+        /// Contains Intel Memory Protection Extensions (MPX) information.
+        /// </summary>
+        IMAGE_DEBUG_TYPE_MPX = 15,
+
+        /// <summary>
+        /// Contains reproducible build hash information.
+        /// </summary>
+        /// <remarks>Contains a hash that can be used to verify reproducible builds.</remarks>
+        IMAGE_DEBUG_TYPE_REPRO = 16,
+
+        /// <summary>
+        /// Contains embedded portable PDB debug information.
+        /// </summary>
+        /// <remarks>The data contains a compressed portable PDB embedded directly in the PE file.</remarks>
+        IMAGE_DEBUG_TYPE_EMBEDDED_PORTABLE_PDB = 17,
+
+        /// <summary>
+        /// Contains Static Profile Guided Optimization (SPGO) information.
+        /// </summary>
+        IMAGE_DEBUG_TYPE_SPGO = 18,
+
+        /// <summary>
+        /// Contains the hash of the PDB file for verification.
+        /// </summary>
+        /// <remarks>Used to verify the PDB file matches the executable.</remarks>
+        IMAGE_DEBUG_TYPE_PDBCHECKSUM = 19,
+
+        /// <summary>
+        /// Contains extended DLL characteristics flags.
+        /// </summary>
+        /// <remarks>Contains additional DLL characteristics that don't fit in the standard header field.</remarks>
+        IMAGE_DEBUG_TYPE_EX_DLLCHARACTERISTICS = 20,
     }
 }

src/PSADT/PSADT.Interop/NativeMethods.txt

@@ -35,6 +35,11 @@ FindNextFile
 FindWindow
 FOLDERID_UserProfiles
 FormatMessage
+FPO_DATA
+FRAME_FPO
+FRAME_TRAP
+FRAME_TSS
+FRAME_NONFPO
 GENERIC_MAPPING
 GetApplicationUserModelId
 GetCurrentProcess
@@ -109,7 +114,10 @@ IExecAction
 IMAGE_BASE_RELOCATION
 IMAGE_BOUND_FORWARDER_REF
 IMAGE_BOUND_IMPORT_DESCRIPTOR
+IMAGE_COFF_SYMBOLS_HEADER
 IMAGE_COR20_HEADER
+IMAGE_DEBUG_MISC
+IMAGE_DEBUG_MISC_EXENAME
 IMAGE_DEBUG_DIRECTORY
 IMAGE_DELAYLOAD_DESCRIPTOR
 IMAGE_DLL_CHARACTERISTICS
@@ -220,6 +228,7 @@ NtQueryObject
 NtQuerySystemInformation
 OBJECT_ATTRIBUTE_FLAGS
 OBJECT_NAME_INFORMATION
+OMAP
 OOBEComplete
 OpenProcess
 OpenProcessToken

src/PSADT/PSADT/PortableExecutable/CvInfoBase.cs

@@ -0,0 +1,64 @@
+using System.IO;
+using PSADT.Interop;
+
+namespace PSADT.PortableExecutable
+{
+    /// <summary>
+    /// Represents CodeView debug information parsed from an IMAGE_DEBUG_TYPE_CODEVIEW entry.
+    /// </summary>
+    /// <remarks>
+    /// CodeView data contains a 4-byte signature that identifies the format:
+    /// - "NB09" (0x3930424E): CodeView 4.10 format (VC++ 2.x), embedded debug info
+    /// - "NB10" (0x3031424E): PDB 2.0 format (VC++ 4.x-6.x), external PDB
+    /// - "NB11" (0x3131424E): CodeView 5.0/C7 format, embedded debug info
+    /// - "RSDS" (0x53445352): PDB 7.0 format (VS 2002+), external PDB with GUID
+    /// </remarks>
+    public abstract record CvInfoBase
+    {
+        /// <summary>
+        /// Parses CodeView data from the given binary reader.
+        /// </summary>
+        /// <param name="reader">The binary reader positioned at the CodeView data.</param>
+        /// <param name="size">The size of the CodeView data in bytes.</param>
+        /// <returns>A CodeViewInfo instance, or null if the format is unrecognized.</returns>
+        internal static CvInfoBase? Parse(BinaryReader reader, uint size)
+        {
+            return size < 4 ? null : (CODEVIEW_SIGNATURE)reader.ReadUInt32() switch
+            {
+                CODEVIEW_SIGNATURE.CODEVIEW_SIGNATURE_NB09 => CvInfoCv41.Parse(reader),
+                CODEVIEW_SIGNATURE.CODEVIEW_SIGNATURE_NB10 => CvInfoPdb20.Parse(reader),
+                CODEVIEW_SIGNATURE.CODEVIEW_SIGNATURE_NB11 => CvInfoCv50.Parse(reader),
+                CODEVIEW_SIGNATURE.CODEVIEW_SIGNATURE_RSDS => CvInfoPdb70.Parse(reader),
+                _ => null
+            };
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the CodeViewInfo class.
+        /// </summary>
+        /// <param name="signature">The signature identifying the CodeView format.</param>
+        /// <param name="age">The age value used for PDB matching.</param>
+        /// <param name="pdbPath">The path to the PDB file.</param>
+        private protected CvInfoBase(CODEVIEW_SIGNATURE signature, uint age, string? pdbPath = null)
+        {
+            Signature = signature;
+            Age = age;
+            PdbPath = !string.IsNullOrWhiteSpace(pdbPath) ? pdbPath : null;
+        }
+
+        /// <summary>
+        /// Gets the signature identifying the CodeView format.
+        /// </summary>
+        public CODEVIEW_SIGNATURE Signature { get; }
+
+        /// <summary>
+        /// Gets the age value used for PDB matching.
+        /// </summary>
+        public uint Age { get; }
+
+        /// <summary>
+        /// Gets the path to the PDB file.
+        /// </summary>
+        public string? PdbPath { get; }
+    }
+}

src/PSADT/PSADT/PortableExecutable/CvInfoCv41.cs

@@ -0,0 +1,42 @@
+using System.IO;
+using PSADT.Interop;
+
+namespace PSADT.PortableExecutable
+{
+    /// <summary>
+    /// Represents NB09 (CodeView 4.10) debug information.
+    /// </summary>
+    /// <remarks>
+    /// The NB09 format is a legacy format used by VC++ 2.x compilers and contains:
+    /// - 4-byte signature "NB09" (0x3930424E)
+    /// - 4-byte file position offset to debug info within the PE file
+    /// This format predates external PDB files; debug info is embedded in the executable.
+    /// </remarks>
+    public sealed record CvInfoCv41 : CvInfoBase
+    {
+        /// <summary>
+        /// Parses NB09 CodeView data from the given reader.
+        /// </summary>
+        internal static CvInfoCv41 Parse(BinaryReader reader)
+        {
+            // Read the 4-byte file position offset
+            return new(reader.ReadUInt32());
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the CvInfoCv41 class.
+        /// </summary>
+        private CvInfoCv41(uint filePosition) : base(CODEVIEW_SIGNATURE.CODEVIEW_SIGNATURE_NB09, age: 0)
+        {
+            FilePosition = filePosition;
+        }
+
+        /// <summary>
+        /// Gets the file position offset to the debug information within the PE file.
+        /// </summary>
+        /// <remarks>
+        /// This is an offset from the start of the file to the embedded CodeView debug data.
+        /// </remarks>
+        public uint FilePosition { get; }
+    }
+}