A comprehensive Python library for analyzing malicious binaries through emulation, pattern matching, and integration with reverse engineering tools.
-
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
git clone <repository-url>
cd azazel
pip install -e .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# Start the interactive shell
azazel
# Or load a binary directly
azazel malware.exefrom 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}")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
| 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 |
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}")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)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- Build the plugin:
cd plugins/ghidra
export GHIDRA_INSTALL_DIR=/path/to/ghidra
gradle build-
Install the extension:
- In Ghidra: File → Install Extensions → Add → Select
azazel-ghidra.jar - Or copy to
~/.ghidra/.ghidra_<version>/Extensions/
- In Ghidra: File → Install Extensions → Add → Select
-
Restart Ghidra. You'll see "Azazel" menu options and right-click context menu items.
- 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/- Ensure Azazel is installed in your Python environment:
pip install -e .- Restart IDA Pro. Right-click in disassembly or decompiler to see "Emulate with Azazel".
pytest tests/ -vblack src/ tests/
ruff check src/ tests/mypy src/azazel- 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
MIT License - See LICENSE file for details
Contributions are welcome! Please submit issues and pull requests.
- Unicorn Engine - Multi-architecture emulator framework
- Capstone - Disassembly framework
- YARA - Pattern matching for malware analysis