Skip to main content

​
Overview

Version Tracking enables you to compare two versions of a program and automatically or manually propagate analysis from a previously analyzed “source” program to a newer “destination” program. This is essential when tracking software updates, patches, or different builds.
Version Tracking helps preserve your reverse engineering work when analyzing updated versions of software by transferring function names, comments, data types, and other markup.

​
Core Concepts

​
Version Tracking Session

A Version Tracking session contains:
  • Source Program: Previously analyzed version with existing markup
  • Destination Program: New version to receive analysis
  • Matches: Corresponding code/data between programs
  • Markup Items: Individual pieces of analysis to transfer
Sessions are saved to the Ghidra Project and can be shared via Ghidra Server with exclusive checkout (merge conflicts are not supported).

​
Workflow Components

1

Create Session

Select source and destination programs, run precondition checks
2

Run Correlators

Apply correlation algorithms to find matches between programs
3

Review Matches

Examine proposed matches in the Matches Table
4

Accept Matches

Accept high-confidence matches to enable markup transfer
5

Apply Markup

Transfer analysis (names, comments, etc.) to destination program

​
Version Tracking Tool

The Version Tracking Tool consists of:

​
Primary Components

Matches Table

Primary view showing all correlation matches with scores and status

Markup Items Table

Details of individual markup items for selected matches

Source Tool

CodeBrowser for the source program

Destination Tool

CodeBrowser for the destination program with apply capabilities

​
Toolbar Actions

Launch the Version Tracking Wizard to create a new session with two programs.
Run additional correlators on an existing session to find more matches.
Automatically create and accept the most likely matches based on confidence scores.

​
Creating a Session

​
Version Tracking Wizard

1

Launch Wizard

Drag two programs onto the Version Tracking tool or click Create Session.
2

Specify Programs

Select source (analyzed) and destination (new) programs. Use swap button if reversed.
Source: myapp_v1.0 (contains your analysis)
Destination: myapp_v2.0 (new version to analyze)
3

Run Preconditions

Execute validators to check for potential problems:
  • Large differences in function counts
  • Missing analysis in source program
  • Architecture mismatches
4

Select Correlators

Choose which correlation algorithms to run initially.
5

Review Summary

Verify settings and click Finish to create the session.
If source and destination are swapped, transferred markup will go the wrong direction. Always verify the swap button is used correctly.

​
Correlation Algorithms

Correlators find matches between source and destination programs:

​
Exact Match Correlators

Matches functions with identical bytes. Very high confidence.Use: First correlator to run—provides definitive matches

​
Symbol-Based Correlators

Matches functions/data with identical symbol names.Use: Works well with non-stripped binaries

​
Structure-Based Correlators

Considers multiple factors: structure, references, and code patterns.Use: Comprehensive matching for moderate changes

​
Advanced Correlators

Handles multiple functions with same instruction patterns.
Create matches manually by selecting functions in both programs.
Recommended Workflow:
  1. Start with Exact Function Bytes
  2. Run Exact Symbol Name
  3. Apply Combined Function and Data
  4. Use Manual Match for remaining important functions

​
Working with Matches

​
Matches Table Columns

ColumnDescription
ScoreCorrelation confidence (0.0 - 1.0)
SourceAddress/name in source program
DestinationAddress/name in destination program
LengthFunction/data size
TypeMatch type (Function, Data, Label)
StatusAvailable, Accepted, Rejected, Blocked
AlgorithmCorrelator that found the match

​
Match Actions

Accept Match

Confirm the match is correct, enabling markup transfer

Reject Match

Mark match as incorrect, preventing it from being used

Clear Match

Reset match status back to Available

Apply Markup

Transfer selected markup items to destination

​
Filtering Matches

Filter matches by:
  • Score threshold: Hide low-confidence matches
  • Status: Show only accepted, available, or rejected
  • Algorithm: View matches from specific correlators
  • Match type: Filter by function, data, or label matches
// Source: VT_Tool.html:27-32
// The Matches Table is the primary view for reviewing
// and managing correlation results

​
Markup Items

Markup items represent individual pieces of analysis to transfer:

​
Markup Types

User-defined and imported function names

​
Applying Markup

1

Select Match

Click on an accepted match in the Matches Table.
2

Review Markup Items

Examine individual items in the Markup Items Table:
  • Green checkmark: Can be applied
  • Red X: Conflict exists
  • Gray: Already applied or not applicable
3

Select Items

Choose which markup items to apply (or select all).
4

Apply

Click Apply to transfer markup to destination program.
Markup Items are only available after a match has been accepted. Available matches cannot transfer markup until accepted.

​
Auto Version Tracking

Automatic Version Tracking attempts to automatically create and accept matches:

​
How It Works

  1. Runs a predetermined sequence of correlators
  2. Accepts matches above confidence threshold
  3. Applies markup for accepted matches
  4. Iterates until convergence or limits reached

​
Configuration

​
scoreThreshold
number
default:"0.95"
Minimum score to auto-accept matches
​
confidenceThreshold
number
default:"10.0"
Minimum confidence score for acceptance
​
maxIterations
number
default:"5"
Maximum correlator iterations
Auto Version Tracking works best when programs are very similar. Review results carefully, especially for heavily modified programs.

​
Manual Matching

Create matches manually when correlators don’t find them:

​
From Sub-Tools

1

Position Cursors

Place cursor on function in Source Tool and corresponding function in Destination Tool.
2

Right-Click

In either tool, right-click to open context menu.
3

Create Match

Select one of:
  • Create Manual Match: Add to matches table
  • Create and Accept Match: Add and accept immediately
  • Create and Apply Match: Add, accept, and apply markup
Manual matching is essential for:
  • Heavily refactored code
  • Renamed functions without symbolic information
  • Code moved to different locations
  • Custom correlation scenarios

​
Session Management

​
Opening Sessions

Double-click session file (start-here icon) in Project Window.

​
Version Control

Sessions can be versioned using Ghidra Server repositories:
1

Add to Version Control

Right-click session in Project Window → Add to Version Control.
2

Exclusive Checkout

Always use exclusive checkout for sessions (merge not supported).
3

Check In

Save changes and check in when complete.
Important Session Requirements:
  • Sessions require exclusive checkout (not shared checkout)
  • Source and destination programs must be in version control first
  • Session and both programs must reside in the same project
  • Only sessions in the active project can be opened (not viewed projects)

​
Address Ranges and Filtering

​
Limiting Correlation Scope

When adding correlators to a session:
Skip functions/data already matched to speed up correlation.Benefit: Greatly improves performance on large programs
Restrict correlation to specific memory regions:
  • Use entire program
  • Use current tool selection
  • Specify custom address ranges
Use case: Correlate specific modules or sections

​
Advanced Features

​
Precondition Validators

Validators check for potential issues before correlation:
  • Function Count Validator: Warns if function counts differ significantly
  • Data Type Validator: Checks for missing data type analysis
  • Reference Validator: Verifies reference analysis quality
  • Memory Validator: Compares memory layouts
# Run preconditions from wizard
# Click "Run Precondition checks" and review results

​
Diff Details

View detailed differences for specific matches:
  1. Select match in Matches Table
  2. View side-by-side comparison in Source/Destination Tools
  3. Examine byte-level differences
  4. Review decompiler output comparison

​
Undo/Redo

Version Tracking supports full undo/redo:
  • Accepting matches
  • Applying markup
  • Creating manual matches
  • Rejecting matches
Use Edit → Undo to revert recent actions during session review.

​
Best Practices

Analyze Source First

Ensure source program is fully analyzed before creating session

Run Correlators Incrementally

Start with exact matches, gradually add fuzzy correlators

Review Before Applying

Always review markup items before bulk application

Use Preconditions

Run validators to catch issues early

Save Frequently

Save session regularly during analysis

Exclude Accepted

Enable exclude option for faster subsequent correlations

​
Troubleshooting

Solutions:
  • Verify both programs are analyzed
  • Try additional correlator algorithms
  • Check for code obfuscation or heavy refactoring
  • Use manual matching for key functions
Causes:
  • Match not accepted
  • Conflicts with existing destination markup
  • Incompatible data types
Solution: Accept match first, resolve conflicts in Markup Items Table
Checks:
  • Verify exclusive checkout
  • Ensure session is in active project
  • Check that source/destination programs are available
  • Confirm project repository access
Optimizations:
  • Enable “Exclude accepted matches”
  • Limit address ranges to relevant sections
  • Run correlators incrementally
  • Close unnecessary tools/windows

​
Source Code References

# Main implementation
~/workspace/source/Ghidra/Features/VersionTracking/

# Help documentation
VersionTracking/src/main/help/help/topics/VersionTrackingPlugin/

# Scripts
VersionTracking/ghidra_scripts/

​
File Menu

  • New Session: Create new version tracking session
  • Add to Session: Run additional correlators
  • Auto Version Track: Run automatic matching
  • Open Session: Open existing session
  • Close Session: Close current session
  • Save Session: Save changes to session

​
Edit Menu

  • Undo/Redo: Revert or reapply actions
  • Tool Options: Configure tool settings
  • Reset Source and Destination Tools: Restore default tool layouts

​
Window Menu

Show/hide component windows:
  • Matches Table
  • Markup Items Table
  • Function Associations
  • And other available views

​
Next Steps

Program Diff

Compare programs side-by-side without version tracking

Ghidra Server

Share sessions with team via collaborative server

Build docs developers (and LLMs) love

Get started for freeTalk to us