feat: Enable sibling discovery and offset handling in cross-function analysis

This commit significantly enhances the robustness of structure reconstruction by improving how the analyzer traverses the call graph, specifically handling pointer arithmetic and identifying related "sibling" functions.

- include/structor/cross_function_analyzer.hpp, src/cross_function_analyzer.cpp:
  - Implemented sibling discovery: when tracing backward to a caller, the analyzer now also traces forward to find other callees receiving the same variable. This ensures that analyzing `init_obj(ptr)` also discovers `process_obj(ptr)` via their common caller.
  - Updated `CallerFinder` to extract pointer offsets (deltas) from call arguments (e.g., `func((char*)ptr + 0x10)`).
  - Modified `trace_backward` to normalize field access offsets based on these deltas, allowing correct reconstruction of substructures.

- include/structor/type_propagator.hpp:
  - Added forward propagation logic to ensure synthesized types are applied to sibling functions.
  - Enhanced `find_base_var` to robustly identify base variables through complex expressions (casts, refs, pointer arithmetic).

- src/z3/layout_constraints.cpp, src/z3/field_candidates.cpp:
  - Added `add_type_preference_constraints` to favor typed fields over raw bytes when overlapping candidates exist.
  - Implemented `fill_gaps_with_padding` to insert explicit padding fields in the final structure.
  - Added comprehensive logging to the Z3 constraint building and solving phases for better debugging.

- include/structor/access_collector.hpp:
  - Added `is_zero_initialization` to detect and flag writes that set fields to zero/NULL.

- integration_tests/:
  - Added comprehensive test suite (Python scripts and C source) verifying propagation across linked-list operations and substructure passing.

Impact:
Users will see more complete structure definitions when analyzing code where pointers are passed between multiple functions. The tool can now correctly infer full structures even when functions only access specific substructures (offsets), and types are propagated more reliably across the entire usage graph.

Author: 19h

.github/workflows/build.yml

@@ -17,31 +17,69 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # IDA stable builds
           - os: macos-latest
             name: macos-x86_64
             cmake_arch: x86_64
+            ida_branch: ""
+            ida_suffix: ""
           - os: macos-latest
             name: macos-arm64
             cmake_arch: arm64
+            ida_branch: ""
+            ida_suffix: ""
           - os: ubuntu-latest
             name: linux-x86_64
+            ida_branch: ""
+            ida_suffix: ""
           - os: windows-latest
             name: windows-x86_64
             cmake_arch: x64
+            ida_branch: ""
+            ida_suffix: ""
+          # IDA 9.3 beta builds
+          - os: macos-latest
+            name: macos-x86_64
+            cmake_arch: x86_64
+            ida_branch: releases/9.3.0-beta
+            ida_suffix: "-ida93beta"
+          - os: macos-latest
+            name: macos-arm64
+            cmake_arch: arm64
+            ida_branch: releases/9.3.0-beta
+            ida_suffix: "-ida93beta"
+          - os: ubuntu-latest
+            name: linux-x86_64
+            ida_branch: releases/9.3.0-beta
+            ida_suffix: "-ida93beta"
+          - os: windows-latest
+            name: windows-x86_64
+            cmake_arch: x64
+            ida_branch: releases/9.3.0-beta
+            ida_suffix: "-ida93beta"
 
     runs-on: ${{ matrix.os }}
-    name: Build ${{ matrix.name }}
+    name: Build ${{ matrix.name }}${{ matrix.ida_suffix }}
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           submodules: recursive
 
-      - name: Checkout IDA SDK
+      - name: Checkout IDA SDK (stable)
+        if: matrix.ida_branch == ''
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ env.IDA_SDK_REPO }}
+          path: ida-sdk
+
+      - name: Checkout IDA SDK (beta)
+        if: matrix.ida_branch != ''
         uses: actions/checkout@v4
         with:
           repository: ${{ env.IDA_SDK_REPO }}
+          ref: ${{ matrix.ida_branch }}
           path: ida-sdk
 
       - name: Setup MSVC (Windows)
@@ -56,6 +94,75 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y build-essential cmake
 
+      - name: Cache Z3
+        id: cache-z3
+        uses: actions/cache@v4
+        with:
+          path: ${{ github.workspace }}/z3-install
+          key: z3-4.15.4-${{ matrix.name }}
+
+      - name: Download Z3 (macOS)
+        if: runner.os == 'macOS' && steps.cache-z3.outputs.cache-hit != 'true'
+        run: |
+          Z3_VERSION="4.15.4"
+          if [ "${{ matrix.cmake_arch }}" = "arm64" ]; then
+            Z3_ARCHIVE="z3-${Z3_VERSION}-arm64-osx-13.7.6.zip"
+          else
+            Z3_ARCHIVE="z3-${Z3_VERSION}-x64-osx-13.7.6.zip"
+          fi
+          Z3_URL="https://github.com/Z3Prover/z3/releases/download/z3-${Z3_VERSION}/${Z3_ARCHIVE}"
+
+          curl -L -o z3.zip "$Z3_URL"
+          unzip z3.zip
+          mv z3-${Z3_VERSION}-* z3-install
+
+          echo "Z3 installed to: $(pwd)/z3-install"
+          ls -la z3-install/
+
+      - name: Download Z3 (Linux)
+        if: runner.os == 'Linux' && steps.cache-z3.outputs.cache-hit != 'true'
+        run: |
+          Z3_VERSION="4.15.4"
+          Z3_ARCHIVE="z3-${Z3_VERSION}-x64-glibc-2.39.zip"
+          Z3_URL="https://github.com/Z3Prover/z3/releases/download/z3-${Z3_VERSION}/${Z3_ARCHIVE}"
+
+          curl -L -o z3.zip "$Z3_URL"
+          unzip z3.zip
+          mv z3-${Z3_VERSION}-* z3-install
+
+          echo "Z3 installed to: $(pwd)/z3-install"
+          ls -la z3-install/
+
+      - name: Download Z3 (Windows)
+        if: runner.os == 'Windows' && steps.cache-z3.outputs.cache-hit != 'true'
+        shell: pwsh
+        run: |
+          $z3Version = "4.15.4"
+          $z3Archive = "z3-$z3Version-x64-win.zip"
+          $z3Url = "https://github.com/Z3Prover/z3/releases/download/z3-$z3Version/$z3Archive"
+
+          Invoke-WebRequest -Uri $z3Url -OutFile z3.zip
+          Expand-Archive -Path z3.zip -DestinationPath . -Force
+          $extractedDir = Get-ChildItem -Directory -Filter "z3-$z3Version-*" | Select-Object -First 1
+          Rename-Item $extractedDir.Name "z3-install"
+
+          Write-Host "Z3 installed to: ${{ github.workspace }}/z3-install"
+          Write-Host "Directory structure:"
+          Get-ChildItem z3-install/ -Recurse | Where-Object { $_.Extension -in ".dll", ".lib", ".h" } | ForEach-Object { $_.FullName }
+
+      - name: Set Z3 environment (Unix)
+        if: runner.os != 'Windows'
+        run: |
+          echo "Z3_ROOT=${{ github.workspace }}/z3-install" >> $GITHUB_ENV
+          echo "CMAKE_PREFIX_PATH=${{ github.workspace }}/z3-install" >> $GITHUB_ENV
+
+      - name: Set Z3 environment (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          echo "Z3_ROOT=${{ github.workspace }}/z3-install" >> $env:GITHUB_ENV
+          echo "CMAKE_PREFIX_PATH=${{ github.workspace }}/z3-install" >> $env:GITHUB_ENV
+
       - name: Configure CMake (macOS)
         if: runner.os == 'macOS'
         run: |
@@ -64,7 +171,10 @@ jobs:
           cmake .. \
             -DCMAKE_BUILD_TYPE=Release \
             -DCMAKE_OSX_ARCHITECTURES=${{ matrix.cmake_arch }} \
-            -DIDA_SDK_DIR=${{ github.workspace }}/ida-sdk/src
+            -DIDA_SDK_DIR=${{ github.workspace }}/ida-sdk/src \
+            -DZ3_USE_CUSTOM=ON \
+            -DZ3_CUSTOM_INCLUDE_DIR=${{ github.workspace }}/z3-install/include \
+            -DZ3_CUSTOM_LIBRARY=${{ github.workspace }}/z3-install/bin/libz3.dylib
 
       - name: Configure CMake (Linux)
         if: runner.os == 'Linux'
@@ -73,14 +183,22 @@ jobs:
           cd build
           cmake .. \
             -DCMAKE_BUILD_TYPE=Release \
-            -DIDA_SDK_DIR=${{ github.workspace }}/ida-sdk/src
+            -DIDA_SDK_DIR=${{ github.workspace }}/ida-sdk/src \
+            -DZ3_USE_CUSTOM=ON \
+            -DZ3_CUSTOM_INCLUDE_DIR=${{ github.workspace }}/z3-install/include \
+            -DZ3_CUSTOM_LIBRARY=${{ github.workspace }}/z3-install/bin/libz3.so
 
       - name: Configure CMake (Windows)
         if: runner.os == 'Windows'
+        shell: pwsh
         run: |
           mkdir build -Force
           cd build
-          cmake .. -G "Visual Studio 17 2022" -A ${{ matrix.cmake_arch }} -DIDA_SDK_DIR=${{ github.workspace }}/ida-sdk/src
+          # Find the import library - could be in bin/ or lib/
+          $z3Root = "${{ github.workspace }}/z3-install"
+          $implib = if (Test-Path "$z3Root/lib/libz3.lib") { "$z3Root/lib/libz3.lib" } else { "$z3Root/bin/libz3.lib" }
+          Write-Host "Using Z3 import library: $implib"
+          cmake .. -G "Visual Studio 17 2022" -A ${{ matrix.cmake_arch }} "-DIDA_SDK_DIR=${{ github.workspace }}/ida-sdk/src" -DZ3_USE_CUSTOM=ON "-DZ3_CUSTOM_INCLUDE_DIR=$z3Root/include" "-DZ3_CUSTOM_LIBRARY=$z3Root/bin/libz3.dll" "-DZ3_CUSTOM_IMPLIB=$implib"
 
       - name: Build (Unix)
         if: runner.os != 'Windows'
@@ -99,10 +217,10 @@ jobs:
         id: find_plugin_unix
         run: |
           if [ "${{ runner.os }}" = "macOS" ]; then
-            PLUGIN_FILE=$(find build -name "structor64.dylib" -type f | head -1)
+            PLUGIN_FILE=$(find build -name "structor.dylib" -type f | head -1)
             EXT="dylib"
           else
-            PLUGIN_FILE=$(find build -name "structor64.so" -type f | head -1)
+            PLUGIN_FILE=$(find build -name "structor.so" -type f | head -1)
             EXT="so"
           fi
 
@@ -121,7 +239,7 @@ jobs:
         id: find_plugin_windows
         shell: pwsh
         run: |
-          $plugin = Get-ChildItem -Path build -Recurse -Filter "structor64.dll" | Select-Object -First 1
+          $plugin = Get-ChildItem -Path build -Recurse -Filter "structor.dll" | Select-Object -First 1
           if ($null -eq $plugin) {
             Write-Error "Could not find built plugin"
             Get-ChildItem -Path build -Recurse -Filter "structor*"
@@ -131,23 +249,35 @@ jobs:
           echo "extension=dll" >> $env:GITHUB_OUTPUT
           Write-Host "Found plugin: $($plugin.FullName)"
 
-      - name: Prepare artifact (Unix)
-        if: runner.os != 'Windows'
+      - name: Prepare artifact (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          mkdir -p artifacts
+          cp "${{ steps.find_plugin_unix.outputs.plugin_file }}" "artifacts/structor${{ matrix.ida_suffix }}_${{ matrix.name }}.${{ steps.find_plugin_unix.outputs.extension }}"
+          # Copy Z3 library
+          cp "${{ github.workspace }}/z3-install/bin/libz3.dylib" "artifacts/libz3_${{ matrix.name }}.dylib"
+
+      - name: Prepare artifact (Linux)
+        if: runner.os == 'Linux'
         run: |
           mkdir -p artifacts
-          cp "${{ steps.find_plugin_unix.outputs.plugin_file }}" "artifacts/structor64_${{ matrix.name }}.${{ steps.find_plugin_unix.outputs.extension }}"
+          cp "${{ steps.find_plugin_unix.outputs.plugin_file }}" "artifacts/structor${{ matrix.ida_suffix }}_${{ matrix.name }}.${{ steps.find_plugin_unix.outputs.extension }}"
+          # Copy Z3 library
+          cp "${{ github.workspace }}/z3-install/bin/libz3.so" "artifacts/libz3_${{ matrix.name }}.so"
 
       - name: Prepare artifact (Windows)
         if: runner.os == 'Windows'
         shell: pwsh
         run: |
           New-Item -ItemType Directory -Force -Path artifacts
-          Copy-Item "${{ steps.find_plugin_windows.outputs.plugin_file }}" "artifacts/structor64_${{ matrix.name }}.${{ steps.find_plugin_windows.outputs.extension }}"
+          Copy-Item "${{ steps.find_plugin_windows.outputs.plugin_file }}" "artifacts/structor${{ matrix.ida_suffix }}_${{ matrix.name }}.${{ steps.find_plugin_windows.outputs.extension }}"
+          # Copy Z3 library
+          Copy-Item "${{ github.workspace }}/z3-install/bin/libz3.dll" "artifacts/libz3_${{ matrix.name }}.dll"
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
-          name: structor-${{ matrix.name }}
+          name: structor${{ matrix.ida_suffix }}-${{ matrix.name }}
           path: artifacts/
           retention-days: 30
 
@@ -167,6 +297,7 @@ jobs:
       - name: Prepare release files
         run: |
           mkdir -p release
+          # Copy all plugin and Z3 library files
           find artifacts -type f \( -name "*.dylib" -o -name "*.so" -o -name "*.dll" \) -exec cp {} release/ \;
           ls -la release/
 

.gitignore

@@ -94,3 +94,5 @@ tests/string_obfuscation/test_strings
 
 .cache
 .claude
+
+__pycache__

CMakeLists.txt

@@ -10,13 +10,62 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 # Z3 Theorem Prover Integration
 # ============================================================================
 
-# Try to find system Z3 first (much faster than building from source)
-find_package(Z3 CONFIG QUIET)
-
-if(Z3_FOUND)
-    message(STATUS "Found system Z3: ${Z3_VERSION}")
+# Allow specifying custom Z3 location
+option(Z3_USE_CUSTOM "Use custom Z3 library instead of system" OFF)
+set(Z3_CUSTOM_INCLUDE_DIR "" CACHE PATH "Custom Z3 include directory")
+set(Z3_CUSTOM_LIBRARY "" CACHE FILEPATH "Custom Z3 library path")
+set(Z3_CUSTOM_IMPLIB "" CACHE FILEPATH "Custom Z3 import library path (Windows only)")
+
+if(Z3_USE_CUSTOM AND Z3_CUSTOM_INCLUDE_DIR AND Z3_CUSTOM_LIBRARY)
+    message(STATUS "Using custom Z3: ${Z3_CUSTOM_LIBRARY}")
     set(Z3_USE_SYSTEM TRUE)
+    set(Z3_CUSTOM TRUE)
+
+    # Create imported target for custom Z3
+    add_library(z3_custom SHARED IMPORTED)
+    if(WIN32)
+        # On Windows, we need the import library (.lib) for linking
+        if(Z3_CUSTOM_IMPLIB)
+            set_target_properties(z3_custom PROPERTIES
+                IMPORTED_LOCATION "${Z3_CUSTOM_LIBRARY}"
+                IMPORTED_IMPLIB "${Z3_CUSTOM_IMPLIB}"
+                INTERFACE_INCLUDE_DIRECTORIES "${Z3_CUSTOM_INCLUDE_DIR}"
+            )
+        else()
+            # Try to find .lib next to .dll or in lib/ directory
+            get_filename_component(Z3_LIB_DIR "${Z3_CUSTOM_LIBRARY}" DIRECTORY)
+            get_filename_component(Z3_LIB_DIR_PARENT "${Z3_LIB_DIR}" DIRECTORY)
+            find_file(Z3_IMPLIB_FOUND
+                NAMES libz3.lib z3.lib
+                PATHS "${Z3_LIB_DIR}" "${Z3_LIB_DIR_PARENT}/lib"
+                NO_DEFAULT_PATH
+            )
+            if(Z3_IMPLIB_FOUND)
+                message(STATUS "Found Z3 import library: ${Z3_IMPLIB_FOUND}")
+                set_target_properties(z3_custom PROPERTIES
+                    IMPORTED_LOCATION "${Z3_CUSTOM_LIBRARY}"
+                    IMPORTED_IMPLIB "${Z3_IMPLIB_FOUND}"
+                    INTERFACE_INCLUDE_DIRECTORIES "${Z3_CUSTOM_INCLUDE_DIR}"
+                )
+            else()
+                message(FATAL_ERROR "Z3_CUSTOM_IMPLIB not set and could not find import library (.lib) for Z3")
+            endif()
+        endif()
+    else()
+        set_target_properties(z3_custom PROPERTIES
+            IMPORTED_LOCATION "${Z3_CUSTOM_LIBRARY}"
+            INTERFACE_INCLUDE_DIRECTORIES "${Z3_CUSTOM_INCLUDE_DIR}"
+        )
+    endif()
 else()
+    # Try to find system Z3 first (much faster than building from source)
+    find_package(Z3 CONFIG QUIET)
+
+    if(Z3_FOUND)
+        message(STATUS "Found system Z3: ${Z3_VERSION}")
+        set(Z3_USE_SYSTEM TRUE)
+        set(Z3_CUSTOM FALSE)
+    else()
     message(STATUS "System Z3 not found, building from source (this takes 15+ minutes)...")
     include(FetchContent)
 
@@ -38,8 +87,10 @@ else()
     set(Z3_BUILD_PYTHON_BINDINGS OFF CACHE BOOL "" FORCE)
     set(Z3_BUILD_DOTNET_BINDINGS OFF CACHE BOOL "" FORCE)
 
-    FetchContent_MakeAvailable(z3)
-    set(Z3_USE_SYSTEM FALSE)
+        FetchContent_MakeAvailable(z3)
+        set(Z3_USE_SYSTEM FALSE)
+        set(Z3_CUSTOM FALSE)
+    endif()
 endif()
 
 # Verify exceptions are enabled (required for Z3 C++ API)
@@ -240,7 +291,9 @@ if(HEXRAYS_LIB)
 endif()
 
 # Link Z3 to structor
-if(Z3_USE_SYSTEM)
+if(Z3_CUSTOM)
+    target_link_libraries(structor${IDA_SUFFIX} PRIVATE z3_custom)
+elseif(Z3_USE_SYSTEM)
     target_link_libraries(structor${IDA_SUFFIX} PRIVATE z3::libz3)
     # System Z3 includes are handled by the imported target
 else()
@@ -254,7 +307,7 @@ endif()
 
 # Set plugin output name and properties
 set_target_properties(structor${IDA_SUFFIX} PROPERTIES
-    OUTPUT_NAME "structor${IDA_SUFFIX}"
+    OUTPUT_NAME "structor"
     SUFFIX ${PLUGIN_EXT}
     PREFIX ""
 )