PE DIFFER - COMPREHENSIVE USAGE GUIDE
Roger's Malware Analysis Toolkit
================================================================================

OVERVIEW
--------
The PE Differ toolkit provides comprehensive comparison capabilities for PE
files (EXE, DLL, SYS). It compares all major PE structures and generates
detailed reports of any differences.

FILES INCLUDED
--------------
- CPEDiffer.cls       : Main differ class
- CDiffEntry.cls      : Individual difference record class  
- frmPEDiffer.frm     : GUI interface for visual comparison
- modPEDifferExamples : Usage examples and common patterns

BASIC USAGE
-----------
1. Create CPEEditor instances for both files
2. Create a CPEDiffer instance
3. Call Compare() method
4. Retrieve results via GetTextReport() or FillListView()

Example:
    Dim pe1 As New CPEEditor
    Dim pe2 As New CPEEditor
    Dim differ As New CPEDiffer
    
    pe1.LoadFile "file1.exe"
    pe2.LoadFile "file2.exe"
    
    If differ.Compare(pe1, pe2) Then
        Debug.Print differ.GetTextReport
    End If

COMPARED ELEMENTS
-----------------
The differ compares all of these PE components:

File Info:
  - File path
  - Machine type (x86/x64/ARM/etc)
  - Architecture (32-bit/64-bit)
  - .NET assembly status
  - .NET version (if applicable)
  - Compiled timestamp
  - Import hash (imphash)

Optional Header:
  - EntryPoint, ImageBase
  - Stack/Heap reserve and commit sizes
  - Magic number, linker version
  - Code/data sizes
  - Section/file alignment
  - OS/Image/Subsystem versions
  - Checksum, subsystem type
  - DLL characteristics
  - Security flags (DEP, ASLR, Force Integrity)
  - All 16 data directory entries (RVA and size)

Sections:
  - Section count
  - Section names
  - Virtual size/address
  - Raw data size/pointer
  - Characteristics
  - Relocation/line number data

Imports:
  - Import DLL additions/removals
  - Function additions/removals per DLL
  - Import table structure changes

Exports:
  - Export count
  - Function additions/removals
  - Function address changes
  - Ordinal changes

Resources:
  - Resource additions/removals
  - Resource path hierarchy

Relocations:
  - Relocation table count
  - Table RVA and size changes
  - Entry count per table

Debug Info:
  - Debug directory presence
  - Timestamp
  - Debug type
  - Data size and address
  - PDB path

KEY METHODS
-----------

CPEDiffer.Compare(pe1, pe2) As Boolean
    Performs the comparison. Returns True on success.
    
CPEDiffer.HasChanges As Boolean
    Returns True if any differences were found.
    
CPEDiffer.DiffCount As Long
    Returns the total number of differences found.
    
CPEDiffer.GetTextReport() As String
    Returns a formatted text report of all differences.
    Organized by category with clear before => after notation.
    
CPEDiffer.FillListView(lv)
    Populates a ListView control with differences.
    Expected columns: Field | Value1 | Value2 | Category
    
CPEDiffer.GetDifferences() As Collection
    Returns all CDiffEntry objects for programmatic access.
    
CPEDiffer.GetDifferencesByCategory(cat) As Collection
    Returns only differences in a specific category.
    Categories: dcFileInfo, dcOptionalHeader, dcSections,
                dcImports, dcExports, dcResources, 
                dcRelocations, dcDebugInfo

CATEGORY FILTERING
------------------
Use the DiffCategory enum to filter results:

    dcFileInfo = 0
    dcOptionalHeader = 1  
    dcSections = 2
    dcImports = 3
    dcExports = 4
    dcResources = 5
    dcRelocations = 6
    dcDebugInfo = 7
    dcRichHeader = 8

Example:
    Dim importDiffs As Collection
    Set importDiffs = differ.GetDifferencesByCategory(dcImports)

GUI USAGE
---------
Launch the visual differ:
    frmPEDiffer.Show

Features:
- Browse for two PE files
- Automatic comparison
- Category filtering dropdown
- Color-coded results by category
- Export report to text file

COMMON USE CASES
----------------

1. Packer Detection
   Compare original vs packed to see:
   - EntryPoint changes
   - Section characteristic modifications
   - Import table stripping
   - New sections added

2. Malware Variant Analysis
   Compare similar malware samples:
   - Quick imphash check first
   - Detailed import/export comparison
   - Resource differences
   - Section layout changes

3. Patch Verification
   Compare before/after patching:
   - Code section changes
   - Import additions
   - Version resource updates
   - Debug info modifications

4. Build Comparison
   Compare different builds:
   - Timestamp verification
   - Linker version changes
   - Section size differences
   - Resource updates

5. File Monitoring
   Baseline a file and detect modifications:
   - Load baseline state
   - Periodically compare current state
   - Alert on critical changes (EntryPoint, checksum, etc)

REPORT FORMAT
-------------
The text report is organized as:

    ============================================================
    PE DIFF REPORT
    ============================================================
    File 1: C:\path\to\file1.exe
    File 2: C:\path\to\file2.exe
    ============================================================
    
    [Category Name]
    ------------------------------------------------------------
    Field Name                          : Old Value        => New Value
    ...
    
    ============================================================
    Total differences: N

ADVANCED USAGE
--------------

Batch Processing:
    Loop through multiple file pairs
    Aggregate statistics
    Generate summary reports

Automated Analysis:
    Integrate with file watchers
    Trigger on file modifications
    Alert on suspicious changes

Forensic Workflows:
    Document file state at different times
    Track incremental modifications
    Evidence collection for reports

Integration with Other Tools:
    Combine with disassemblers (IDA, x64dbg)
    Feed differences to analysis scripts
    Export to databases or JSON

PERFORMANCE NOTES
-----------------
- Large files (>50MB) may take several seconds to compare
- Resource comparison is I/O intensive for large resource sections
- Import/export comparison is fast (dictionary-based lookups)
- Consider comparing imphash first as a quick pre-filter

TROUBLESHOOTING
---------------

Issue: "Both PE files must be loaded"
Fix: Ensure LoadFile() succeeds on both CPEEditor instances before comparing

Issue: No differences shown but files are different
Fix: Check that all relevant sections are being loaded properly.
     Some packed/obfuscated files may have unusual structures.

Issue: Out of memory on large files
Fix: The differ loads entire PE structures into memory.
     For massive files (>500MB), consider comparing specific sections only.

Issue: Unicode in resource names causing issues
Fix: Resource path handling uses VB6 strings. Non-ASCII characters
     may need special handling depending on code page.

EXTENDING THE DIFFER
--------------------
To add new comparison categories:

1. Add to DiffCategory enum
2. Create new Compare* method following existing patterns
3. Call from Compare() main method
4. Add category name to GetCategoryName() function
5. Update GUI filter if needed

Example:
    Private Sub CompareRichHeader()
        'Your comparison logic here
        AddDiffIfChanged "Field", val1, val2, dcRichHeader
    End Sub

INTEGRATION WITH YOUR WORKFLOW
-------------------------------
The differ is designed to integrate with your existing PE analysis tools:

- Use with ucFilterTree for hierarchical diff browsing
- Combine with IDA rebaseTo() for cross-reference analysis  
- Feed results to x64dbg automation scripts
- Export to your documentation pipeline

BEST PRACTICES
--------------
1. Always check imphash first for quick similarity assessment
2. Use category filtering to focus on relevant changes
3. Export reports for documentation and evidence
4. Automate common comparison workflows
5. Combine with version control for build tracking

ROGER'S PRO TIPS
----------------
- For packed malware, compare before/after unpacking to understand packer behavior
- Look for import table additions when analyzing capability expansion
- Section characteristic changes often indicate code injection
- Resource modifications can hide embedded payloads or configs
- Use with memory dumps to compare disk vs memory versions

================================================================================
Questions? Check modPEDifferExamples.bas for more usage patterns.
================================================================================
