Skip to content

deja666/azazel

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Azazel - Static Malware Analysis Library

A comprehensive Python library for analyzing malicious binaries through emulation, pattern matching, and integration with reverse engineering tools.

Features

  • Custom Emulation Engine: Safely execute specific functions or code paths without running the entire program

    • Support for x86, x86_64, ARM, and ARM64 architectures
    • Built on Unicorn Engine for reliable emulation
    • API hooking and stubbing capabilities
    • Execution tracing and register state inspection
  • Binary Analysis: Load and parse PE (Windows) and ELF (Linux) binaries

    • Section extraction and mapping
    • Import/export resolution
    • Symbol lookup
  • Search Utilities: Find patterns and signatures in binaries

    • String extraction (ASCII, Unicode)
    • Regular expression pattern matching
    • YARA rule scanning with built-in malware detection rules
  • Interactive CLI Shell: Command-line interface for manual analysis

    • Rich terminal output with syntax highlighting
    • Tab completion and command history
    • Integrated emulation, search, and analysis commands
  • GUI Integrations: Direct integration with reverse engineering tools

    • Ghidra Plugin: Native Java plugin with right-click emulation
    • IDA Pro Plugin: Python-based plugin for disassembly/decompiler emulation

Installation

From Source

git clone <repository-url>
cd azazel
pip install -e .

Dependencies

The library requires:

  • Python 3.10+
  • Unicorn Engine 2.0+
  • pefile (PE parsing)
  • pyelftools (ELF parsing)
  • yara-python (YARA scanning)
  • rich (CLI output formatting)
  • prompt-toolkit (Interactive shell)
  • capstone (Disassembly)

Install all dependencies:

pip install -r requirements.txt

Quick Start

Using the CLI Shell

# Start the interactive shell
azazel

# Or load a binary directly
azazel malware.exe

Using as a Library

from azazel import Emulator, BinaryLoader, StringExtractor, YaraScanner

# Load a binary
binary = BinaryLoader("malware.exe")

# Emulate a function
emu = Emulator(binary)
result = emu.emulate_function(0x401000, args=[0x100, 0x200])
print(f"Instructions executed: {result['instructions_executed']}")
print(f"Stop reason: {result['stop_reason']}")

# Extract strings
extractor = StringExtractor(min_length=6)
strings = extractor.extract_from_file("malware.exe")
for s in strings[:10]:
    print(s.value)

# Scan with YARA
scanner = YaraScanner()
scanner.load_rules_from_string("""
rule SuspiciousURL {
    strings:
        $url = /https?:\\/\\/[^\s]+/
    condition:
        $url
}
""")
matches = scanner.scan_file("malware.exe")
for match in matches:
    print(f"Matched rule: {match.rule_name}")

Architecture

azazel/
├── src/azazel/
│   ├── core/              # Emulation engine
│   │   ├── emulator.py    # Main emulator
│   │   ├── memory.py      # Memory management
│   │   ├── hooks.py       # API hooking
│   │   ├── cpu_context.py # Register state
│   │   └── arch/          # Architecture support
│   │       ├── x86.py
│   │       └── arm.py
│   ├── binary/            # Binary parsing
│   │   ├── loader.py      # Unified loader
│   │   ├── pe_parser.py   # PE format
│   │   ├── elf_parser.py  # ELF format
│   │   └── symbols.py     # Symbol resolution
│   ├── search/            # Search utilities
│   │   ├── strings.py     # String extraction
│   │   ├── regex_search.py
│   │   └── yara_scan.py
│   └── shell/             # CLI shell
│       ├── cli.py
│       ├── commands.py
│       └── completers.py
└── plugins/
    ├── ghidra/            # Ghidra Java plugin
    └── ida_pro/           # IDA Pro Python plugin

CLI Commands

Command Description
load <file> Load a binary file
info Display binary information
sections List binary sections
imports [dll] List imported functions
exports List exported functions
strings [min] [pattern] Extract strings
emulate <addr> [args...] Emulate a function
dump <addr> [size] Dump memory
regs Display register context
search <pattern> Search with regex
yara [rule_file] Scan with YARA
help Show help

Emulation Examples

Basic Function Emulation

from azazel import Emulator, BinaryLoader

binary = BinaryLoader("target.exe")
emu = Emulator(binary)

# Emulate function at 0x401000 with two arguments
result = emu.emulate_function(
    address=0x401000,
    args=[0x1000, 0x2000],
    max_instructions=100000,
    stop_at_return=True
)

# Inspect results
print(f"Executed {result['instructions_executed']} instructions")
print(f"Stopped because: {result['stop_reason']}")

# View final register state
context = result['context']
for reg, val in context['registers'].items():
    print(f"{reg} = 0x{val:X}")

Custom API Hooks

from azazel import Emulator, BinaryLoader

binary = BinaryLoader("target.exe")
emu = Emulator(binary)

# Hook VirtualAlloc to track allocations
def hook_virtual_alloc(context):
    # Read arguments from registers (x64: RCX, RDX, R8, R9)
    size = emu.read_register("RDX")
    print(f"VirtualAlloc called with size: 0x{size:X}")
    # Return fake allocation address
    emu.write_register("RAX", 0x10000000)

emu.register_api_implementation("kernel32!VirtualAlloc", hook_virtual_alloc)
result = emu.emulate_function(0x401000)

Memory Inspection

from azazel import Emulator, BinaryLoader

binary = BinaryLoader("target.exe")
emu = Emulator(binary)

# Read memory
data = emu.read_memory(0x401000, 256)
print(data.hex())

# Dump formatted memory
print(emu.dump_memory(0x401000, 256))

# Write memory (e.g., patching)
emu.write_memory(0x401000, b"\x90" * 10)  # NOP sled

Plugin Installation

Ghidra Plugin

  1. Build the plugin:
cd plugins/ghidra
export GHIDRA_INSTALL_DIR=/path/to/ghidra
gradle build
  1. Install the extension:

    • In Ghidra: File → Install Extensions → Add → Select azazel-ghidra.jar
    • Or copy to ~/.ghidra/.ghidra_<version>/Extensions/
  2. Restart Ghidra. You'll see "Azazel" menu options and right-click context menu items.

IDA Pro Plugin

  1. Copy the plugin to IDA's plugins directory:
# Windows
copy plugins\ida_pro\azazel_ida.py %APPDATA%\Hex-Rays\IDA Pro\plugins\

# Linux
cp plugins/ida_pro/azazel_ida.py ~/.idapro/plugins/

# macOS
cp plugins/ida_pro/azazel_ida.py ~/Library/Application\ Support/Hex-Rays/IDA\ Pro/plugins/
  1. Ensure Azazel is installed in your Python environment:
pip install -e .
  1. Restart IDA Pro. Right-click in disassembly or decompiler to see "Emulate with Azazel".

Development

Running Tests

pytest tests/ -v

Code Formatting

black src/ tests/
ruff check src/ tests/

Type Checking

mypy src/azazel

Safety Considerations

⚠️ Important: While emulation is safer than running malware, be aware:

  • The emulator provides isolation but is not a complete sandbox
  • Always analyze malware in a dedicated VM or isolated environment
  • Set instruction limits and timeouts to prevent infinite loops
  • Be cautious when implementing API hooks - they execute in your Python environment

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please submit issues and pull requests.

Acknowledgments

  • Unicorn Engine - Multi-architecture emulator framework
  • Capstone - Disassembly framework
  • YARA - Pattern matching for malware analysis

About

Python library for analyzing malicious binaries through emulation, pattern matching, and integration with reverse engineering tools.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors