Skip to content

Changelog and Migration

Jump to bottom
xwings edited this page Jul 6, 2025 · 2 revisions

Changelog and Migration Guide

Comprehensive changelog and migration instructions for Qiling Framework versions.

Release History

Version 1.4.x Series (Current Stable)

1.4.6 (Latest Stable)

Release Date: 2024-03-15 Status: Current Stable Release

🚀 New Features:

  • Enhanced Windows 11 support with updated API implementations
  • New RISC-V 64-bit architecture support for firmware analysis
  • Advanced memory forensics toolkit with heap analysis
  • Improved IoT firmware emulation for ARM Cortex-M series
  • Enterprise logging system with structured output formats

🔧 Improvements:

  • Performance optimization: 40% faster emulation on x86_64
  • Reduced memory footprint by 25% for large binaries
  • Enhanced debugger integration with GDB protocol support
  • Improved cross-platform compatibility (Windows/Linux/macOS)
  • Better error messages with context and suggestions

🐛 Bug Fixes:

  • Fixed memory corruption in multi-threaded Windows emulation
  • Resolved ARM thumb mode instruction handling edge cases
  • Fixed Unicode handling in Windows API implementations
  • Corrected MIPS syscall table inconsistencies
  • Fixed memory leaks in long-running analysis sessions

🔒 Security:

  • Hardened rootfs isolation mechanisms
  • Fixed potential information disclosure in error messages
  • Enhanced sandboxing for untrusted binary analysis
  • Improved input validation for API parameters

⚡ Performance:

  • Optimized instruction cache for frequently executed code
  • Improved memory mapping efficiency for large address spaces
  • Enhanced hook mechanism with lower overhead
  • Better thread synchronization for parallel analysis

1.4.5

Release Date: 2024-01-20

🚀 New Features:

  • QNX Neutrino OS support for automotive firmware analysis
  • Enhanced macOS Monterey and Ventura compatibility
  • New fuzzing integration with AFL++ and Honggfuzz
  • Advanced anti-analysis detection and bypass techniques

🔧 Improvements:

  • Restructured project architecture for better modularity
  • Enhanced documentation with interactive examples
  • Improved CLI tools with better user experience
  • Better integration with popular reverse engineering tools

🐛 Bug Fixes:

  • Fixed UEFI emulation compatibility issues
  • Resolved Python 3.11 compatibility problems
  • Fixed shellcode analysis edge cases
  • Corrected ARM64 exception handling

1.4.4

Release Date: 2023-11-10

🚀 New Features:

  • Enhanced Android emulation with API level 33 support
  • New snapshot and restore functionality for complex analysis
  • Advanced code coverage tracking with HTML reports
  • Improved Windows driver emulation capabilities

🔧 Improvements:

  • Better integration with Ghidra and IDA Pro
  • Enhanced logging system with configurable verbosity
  • Improved memory management for large-scale analysis
  • Better error recovery mechanisms

Version 1.3.x Series (Legacy Stable)

1.3.7 (Final 1.3.x Release)

Release Date: 2023-08-15 Status: Legacy Support (Security fixes only)

🔧 Final Improvements:

  • Last major update to Windows 10 API implementations
  • Final ARM Cortex-A series optimizations
  • Legacy MIPS architecture final compatibility updates

🔒 Security:

  • Final security patches for 1.3.x series
  • Hardened legacy API implementations

⚠️ End of Life Notice: The 1.3.x series reached end of life on December 31, 2023. Users should migrate to 1.4.x series for continued support and security updates.

Migration Guides

Migrating from 1.3.x to 1.4.x

This is a major version migration with significant architectural improvements and some breaking changes.

Breaking Changes

1. API Restructuring:

# 1.3.x (Old)
from qiling.os.windows.api import *
from qiling.os.linux.syscall import *

# 1.4.x (New)
from qiling.os.windows import api
from qiling.os.linux import syscall

2. Hook System Changes:

# 1.3.x (Old)
def my_hook(ql, address, size):
    pass

ql.hook_code(my_hook, begin=0x1000, end=0x2000)

# 1.4.x (New)
def my_hook(ql):
    pass

# Use new address-specific hooks
ql.hook_address(my_hook, 0x1000)
# Or use range hooks with new syntax
ql.hook_code(my_hook, address_range=(0x1000, 0x2000))

3. Memory Management Updates:

# 1.3.x (Old)
ql.mem.map(0x1000, 0x1000, info="custom")

# 1.4.x (New)
ql.mem.map(0x1000, 0x1000, perms=UC_PROT_READ | UC_PROT_WRITE, info="custom")

4. Logging System Changes:

# 1.3.x (Old)
from qiling.const import QL_VERBOSE
ql = Qiling([binary], rootfs, verbose=QL_VERBOSE.DEBUG)

# 1.4.x (New)
import logging
logging.basicConfig(level=logging.DEBUG)
ql = Qiling([binary], rootfs, verbose=True)

Migration Steps

Step 1: Update Installation

# Uninstall old version
pip uninstall qiling

# Install new version
pip install qiling>=1.4.0

# Verify installation
python -c "import qiling; print(qiling.__version__)"

Step 2: Update Import Statements

# Update all import statements to new structure
# Use automated migration script if available
python migrate_imports.py your_script.py

Step 3: Update Hook Functions

# Old hook signatures
def old_hook(ql, address, size):
    print(f"Hook at 0x{address:x}")

# New hook signatures
def new_hook(ql):
    print(f"Hook at 0x{ql.arch.regs.rip:x}")  # Use register access

Step 4: Update Memory Operations

# Review all memory mapping operations
# Add explicit permission flags where needed
ql.mem.map(address, size, perms=UC_PROT_READ | UC_PROT_WRITE)

Step 5: Update Configuration

# 1.3.x Configuration
config = {
    'verbose': True,
    'debug': True,
    'timeout': 1000
}

# 1.4.x Configuration
config = QilingConfig(
    verbose=True,
    enable_debugger=True,
    timeout=1000,
    log_level=logging.DEBUG
)

Compatibility Layer

For gradual migration, 1.4.x includes a compatibility layer:

# Enable compatibility mode for 1.3.x code
from qiling.compat import enable_v13_compatibility
enable_v13_compatibility()

# Your 1.3.x code will work with warnings
# Migrate gradually to new APIs

Testing Migration

Automated Testing:

# Run migration validation script
python tools/validate_migration.py your_project/

# Run comprehensive tests
pytest tests/ --migration-test

Manual Verification:

# Test basic functionality
def test_migration():
    ql = Qiling(['tests/samples/hello'], 'tests/rootfs/')
    
    # Test hook system
    def test_hook(ql):
        print("Hook working")
    
    ql.hook_address(test_hook, 0x1000)
    ql.run()
    
    print("Migration successful!")

test_migration()

Migrating from 1.2.x to 1.3.x

Key Changes:

  • Introduction of unified architecture handling
  • Improved Windows API emulation
  • Enhanced cross-platform support

Migration Steps:

  1. Update Python version requirement (3.7+ → 3.8+)
  2. Update hook callback signatures
  3. Migrate custom OS implementations
  4. Update test suites

Performance Migration Guide

Optimizing for 1.4.x

Memory Usage Optimization:

# 1.4.x introduces memory-efficient modes
ql = Qiling([binary], rootfs, 
           memory_mode=QL_MEMORY_MODE.EFFICIENT,
           cache_instructions=True)

Hook Performance:

# Use targeted hooks instead of global hooks
# Old: Global code hook
ql.hook_code(global_hook)

# New: Specific address hooks
ql.hook_address(specific_hook, target_address)

Analysis Performance:

# Use streaming analysis for large binaries
from qiling.analysis import StreamingAnalyzer

analyzer = StreamingAnalyzer(ql)
for chunk in analyzer.analyze_stream():
    process_chunk(chunk)

Version Compatibility Matrix

Qiling Version Python Version Unicorn Version Capstone Version Keystone Version
1.4.6 3.8-3.12 2.0.1+ 5.0.1+ 0.9.2+
1.4.5 3.8-3.11 2.0.0+ 5.0.0+ 0.9.2+
1.4.4 3.8-3.11 2.0.0+ 4.0.2+ 0.9.2+
1.3.7 3.7-3.10 1.0.3+ 4.0.2+ 0.9.1+
1.3.6 3.7-3.10 1.0.3+ 4.0.2+ 0.9.1+

Deprecation Notices

Deprecated in 1.4.x

APIs Scheduled for Removal in 1.5.x:

# Deprecated: Legacy hook system
ql.hook_code_callback()  # Use ql.hook_code() instead

# Deprecated: Old memory API
ql.mem.map_region()      # Use ql.mem.map() instead

# Deprecated: Legacy constants
QL_VERBOSE               # Use logging module instead

Migration Timeline:

  • 1.4.6: Deprecation warnings introduced
  • 1.5.0: Legacy APIs removed
  • 1.5.2: Full backward compatibility removed

Deprecated in 1.3.x (Removed in 1.4.x)

Removed APIs:

# These APIs were removed in 1.4.x
ql.patch()               # Use ql.mem.write() instead
ql.set_timeout()         # Use timeout parameter in run() instead
ql.enable_lib_patch()    # Automatic library patching enabled by default

Platform-Specific Migration Notes

Windows Migration

Windows API Changes:

# 1.3.x
from qiling.os.windows.dlls import *

# 1.4.x
from qiling.os.windows.dlls.kernel32 import kernel32_api
from qiling.os.windows.dlls.ntdll import ntdll_api

Registry Emulation:

# Enhanced registry emulation in 1.4.x
ql.os.registry.create_key("HKLM\\Software\\MyApp")
ql.os.registry.set_value("HKLM\\Software\\MyApp", "Version", "1.0")

Linux Migration

Syscall Handling:

# Improved syscall table in 1.4.x
ql.os.set_syscall("read", custom_read_handler)
ql.os.set_syscall("write", custom_write_handler)

macOS Migration

New macOS Support:

# Enhanced macOS emulation in 1.4.x
ql = Qiling([binary], "rootfs/macos_x8664/")
ql.os.macho.load_dylib("Foundation.framework")

Troubleshooting Migration Issues

Common Issues and Solutions

Issue 1: Import Errors

# Error: ImportError: cannot import name 'QL_VERBOSE'
# Solution: Update to new logging system
import logging
logging.basicConfig(level=logging.DEBUG)

Issue 2: Hook Callback Errors

# Error: TypeError: hook() takes 2 positional arguments but 3 were given
# Solution: Update hook signature
def old_hook(ql, address, size):  # Old signature
    pass

def new_hook(ql):  # New signature
    address = ql.arch.regs.rip  # Get address from registers

Issue 3: Memory Mapping Errors

# Error: QilingMemoryError: Invalid memory mapping
# Solution: Add explicit permissions
from unicorn import UC_PROT_READ, UC_PROT_WRITE
ql.mem.map(address, size, perms=UC_PROT_READ | UC_PROT_WRITE)

Issue 4: Performance Degradation

# Solution: Enable performance optimizations
ql = Qiling([binary], rootfs,
           optimize=True,
           cache_instructions=True)

Migration Support Tools

Automated Migration Script:

# Download migration tool
wget https://github.com/qilingframework/qiling/tools/migrate.py

# Run migration on your codebase
python migrate.py --from=1.3 --to=1.4 your_project/

Compatibility Checker:

# Check compatibility before migration
python tools/check_compatibility.py your_script.py

Future Roadmap

Upcoming in 1.5.x

Planned Features:

  • Native Apple Silicon (M1/M2) optimization
  • Enhanced WebAssembly (WASM) emulation support
  • Cloud-native analysis platform integration
  • Advanced machine learning-based analysis
  • Real-time collaborative analysis features

Breaking Changes Planned:

  • Complete removal of deprecated 1.3.x APIs
  • New unified configuration system
  • Restructured plugin architecture

Long-term Vision (2.0.x)

Major Architectural Changes:

  • Microservice-based architecture
  • Native distributed analysis support
  • Enhanced security sandbox
  • Next-generation hook system
  • Advanced visualization platform

Getting Help with Migration

Support Channels

  1. GitHub Discussions: Migration questions and community help
  2. Telegram Chat: Real-time migration assistance
  3. Migration Guide: Detailed step-by-step instructions
  4. Professional Support: Enterprise migration assistance available

Migration Checklist

Pre-Migration:

  • Backup existing codebase
  • Review compatibility matrix
  • Test in development environment
  • Read deprecation notices

During Migration:

  • Update dependencies
  • Migrate import statements
  • Update hook functions
  • Test core functionality
  • Update configuration

Post-Migration:

  • Run comprehensive tests
  • Verify performance metrics
  • Update documentation
  • Train team on new features

Need Help? Join our community channels or contact the development team for personalized migration assistance. We're committed to making your migration as smooth as possible!

Clone this wiki locally