cunfyooz

THE METAMORPHIC BINARY OBFUSCATOR

Overview • Features • Usage • Architecture • Pipeline • Examples • Documentation • Contributing

cunfyooz is a metamorphic code engine designed to transform PE binaries into (nearly) functionally equivalent but structurally unique variants.

Metamorphic code changes its appearance with each generation while preserving its core functionality, making it resistant to signature-based detection and static analysis.

The cunfyooz framework now includes integration with the Claude Agent Framework, enabling intelligent binary analysis and transformation through AI agents:

• Cunfyooz Agent: Performs automated binary obfuscation and metamorphic transformations
• Analysis Agent: Evaluates transformation effectiveness and binary properties
• Multi-Agent Swarms: Parallel processing of multiple binaries
• Transformation Pipelines: Sequential processing with context passing

cunfyooz:

1. PARSES PE binary structure and extracts executable sections
2. DISASSEMBLES instructions using Capstone engine
3. ANALYZES control flow and data dependencies
4. TRANSFORMS code through multiple obfuscation passes
5. REASSEMBLES and reconstructs the modified PE binary

The cunfyooz engine applies sophisticated transformations including NOP insertion, instruction substitution, register shuffling, control flow obfuscation, and optional virtualization.

• GCC - C compiler for building the project
• Capstone - Disassembly framework
• Keystone - Assembly framework
• GNU Make - Build automation

INSTALL CAPSTONE:

git clone https://github.com/aquynh/capstone.git
cd capstone
make
sudo make install

INSTALL KEYSTONE:

git clone https://github.com/keystone-engine/keystone.git
cd keystone
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON ..
make
sudo make install

BUILD CUNFYOOZ:

make

This will compile the source code and create the cunfyooz executable in the bin directory.

1. PREPARE YOUR PE BINARY

Ensure you have a valid PE executable file (e.g., target.exe)

2. RUN CUNFYOOZ

./bin/cunfyooz target.exe

The tool will generate a transformed binary named:

cunfyoozed_target.exe

The cunfyooz framework includes AI agents for intelligent binary analysis and transformation. The unified CLI provides access to both the core transformation engine and the AI agent framework:

1. SET UP ENVIRONMENT

# Install Python dependencies
pip install -r requirements.txt

# Set Claude API key
export ANTHROPIC_API_KEY="your-api-key-here"

2. RUN UNIFIED CLI

The unified CLI provides access to all cunfyooz capabilities:

# Transform a binary using the core engine
python cunfyooz_cli.py transform my_binary.exe

# Analyze a binary with AI agents
python cunfyooz_cli.py analyze my_binary.exe

# Run complete analysis pipeline
python cunfyooz_cli.py pipeline my_binary.exe

3. ADVANCED CLI USAGE

For detailed usage examples and advanced options, see the comprehensive documentation:

# View help
python cunfyooz_cli.py --help

# Transform with custom config
python cunfyooz_cli.py transform my_binary.exe -c my_config.json

# Analyze with specific task
python cunfyooz_cli.py analyze my_binary.exe -t "identify potential vulnerabilities"

For complete usage examples and documentation, see docs/USAGE_EXAMPLES.md.

cunfyooz can be customized using a config.json file placed in the working directory:

{
  "transformations": {
    "nop_insertion": {
      "enabled": true,
      "probability": 5
    },
    "instruction_substitution": {
      "enabled": true,
      "probability": 10
    },
    "register_shuffling": {
      "enabled": true,
      "probability": 8
    },
    "enhanced_nop_insertion": {
      "enabled": true,
      "probability": 3
    },
    "control_flow_obfuscation": {
      "enabled": true,
      "probability": 5
    },
    "stack_frame_obfuscation": {
      "enabled": true,
      "probability": 2
    },
    "instruction_reordering": {
      "enabled": true,
      "probability": 5
    },
    "anti_analysis_techniques": {
      "enabled": true,
      "probability": 15
    },
    "virtualization_engine": {
      "enabled": false,
      "probability": 10
    }
  },
  "output": {
    "verbose": true,
    "log_transformations": true
  },
  "security": {
    "validate_functionality": false,  /* CHANGED FROM true TO false FOR SECURITY */
    "preserve_original_behavior": true
  }
}

CONFIGURATION PARAMETERS:

• enabled - Enable/disable specific transformations
• probability - Percentage chance (1-100) for applying transformation
• verbose - Output detailed transformation logs
• validate_functionality - Verify transformed binary maintains original behavior (DEFAULT: false for security - enables execution of binaries for comparison)

cunfyooz features a clean, layered architecture for binary transformation:

Specialized modules for different obfuscation techniques:

• NOP Insertion Engine - Strategic insertion of padding instructions
• Instruction Substitutor - Functional equivalence replacements
• Register Shuffler - Register allocation randomization
• Control Flow Obfuscator - Flow graph complexity injection
• Stack Frame Manipulator - Call frame structure obfuscation
• Instruction Reorderer - Dependency-aware instruction scheduling
• Anti-Analysis Module - Runtime detection and evasion
• Virtualization Engine - Code-to-bytecode transformation

The cunfyooz framework includes an AI agent layer built on the Claude Agent Framework:

cunfyooz employs a sophisticated 10-stage transformation pipeline:

; Original
cmp eax, ebx
jne skip
call function
skip:

; Obfuscated
cmp eax, ebx
je else_part
jmp skip
else_part:
call function
skip:

; Original
mov rax, rbx
add rax, 5

; Transformed
mov rax, rbx
nop
add rax, 5

; Original
mov rax, rbx
add rax, 5

; Transformed
mov rax, rbx
xchg rax, rax
add rax, 5

; Original
lea rax, [rbx]

; Transformed
mov rax, rbx

; Original
test rax, rax
je label

; Transformed
cmp rax, 0
je label

; Original
mov rax, 1
mov rbx, 2
add rax, rbx

; Transformed
mov rcx, 1
mov rdx, 2
add rcx, rdx

; Original
cmp eax, ebx
jne skip
call function
skip:

; Transformed with opaque predicate
cmp eax, ebx
je else_part
jmp skip
else_part:
call function
skip:

; Original
mov rax, 5
add rbx, rax

; Transformed
push rax
mov rax, 5
add rbx, rax
pop rax

Metamorphic code transforms itself while maintaining functional equivalence. Key principles:

1️⃣ SEMANTIC PRESERVATION

• Original functionality remains intact
• All execution paths preserved
• Register and memory state consistency maintained

2️⃣ STRUCTURAL VARIATION

• Each transformation produces unique binary
• Time-based random seed ensures uniqueness
• Multiple transformation techniques applied simultaneously

3️⃣ ANALYSIS RESISTANCE

• Static signatures become ineffective
• Pattern matching fails due to variation
• Control flow complexity increases analysis difficulty

SAFE TRANSFORMATION:

• Dependency analysis prevents corruption
• Critical registers (RSP, RBP) preserved
• Branch targets automatically updated
• Validation ensures correctness

RANDOMIZATION:

• Probability-based transformation selection
• Time-seeded random number generation
• Multiple valid transformations for same instruction

cunfyooz is under active development with planned enhancements:

The following critical issues have been RESOLVED:

• ✓ Jump/Call Target Corruption - Relocation tracking system now updates all control flow targets
• ✓ Instruction Size Overflow - Safe assembly with overflow protection implemented
• ✓ PE Structure Corruption - DataDirectory and section VAs properly updated

See CORRUPTION_FIXES.md for technical details.

• PE Format Only - Currently supports Windows PE binaries exclusively
• x86/x64 Architecture - Limited to Intel/AMD instruction sets
• Basic Block Preservation - Some advanced optimizations not yet implemented
• Section Expansion - Transformed binaries may grow significantly in size

• ELF binary support for Linux executables
• ARM architecture support
• Enhanced virtualization with custom VM
• Code compression to reduce size overhead
• Automated testing and validation framework
• Integration with packing techniques

Metamorphic transformations may trigger antivirus heuristics due to:

• Code structure changes
• Anti-debugging techniques
• Unusual instruction patterns

Recommendation: Test transformed binaries in isolated environments

Always validate transformed binaries:

• Test all execution paths
• Verify input/output behavior
• Check edge cases and error handling

For developers working with this codebase:

• CLAUDE.md - Comprehensive guide for AI-assisted development with Claude Code. Contains architecture details, build commands, common workflows, and implementation notes.

• CORRUPTION_FIXES.md - Technical documentation of critical binary corruption fixes. Details the relocation tracking system, instruction size handling, and PE structure updates.

• BUGFIXES.md - Detailed record of identified issues and their resolutions. Useful for understanding code quality standards and debugging patterns.

The cunfyooz codebase maintains high quality standards:

• ✓ Zero compiler warnings - Compiles cleanly with -Wall -Wextra
• ✓ Consistent code style - C and Python code follow consistent conventions
• ✓ Memory safety - Proper initialization and error handling throughout
• ✓ Security-first - Binary execution disabled by default to prevent malicious code execution
• ✓ Type safety - Explicit None checks and proper variable initialization in Python

2026-01-11 - Critical Binary Corruption Fixes:

• ✓ Fixed Jump/Call Target Corruption - Implemented comprehensive relocation tracking system to update jump/call targets after transformations
• ✓ Fixed Instruction Size Overflow - Added safe assembly helpers and buffer overflow protection
• ✓ Fixed PE DataDirectory RVA Corruption - Properly update section VAs and DataDirectory entries when .text section changes size
• See CORRUPTION_FIXES.md for detailed technical analysis and implementation details

2026-01-10 - Code Quality Improvements:

• Fixed unused parameter warnings in C code
• Corrected ELF binary file type detection
• Standardized Python import patterns
• Eliminated undefined variable bugs in agent framework
• Added comprehensive developer documentation

Contributions are welcome! Areas for contribution:

• Bug reports and fixes
• New transformation techniques
• Architecture improvements
• Documentation enhancements
• Test case development

Please review CLAUDE.md for architectural details and BUGFIXES.md for code quality standards before contributing.

cunfyooz is released into the public domain under the Unlicense.

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or 
distribute this software, either in source code form or as a compiled 
binary, for any purpose, commercial or non-commercial, and by any 
means.

In jurisdictions that recognize copyright laws, the author or authors 
of this software dedicate any and all copyright interest in the 
software to the public domain. We make this dedication for the benefit 
of the public at large and to the detriment of our heirs and 
successors. We intend this dedication to be an overt act of 
relinquishment in perpetuity of all present and future rights to this 
software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 
OTHER DEALINGS IN THE SOFTWARE.