aeondave/malware-analysis

Malware Analysis

Structured malware analysis workflow: triage, reverse engineering, IOC extraction, and reporting. Supports static-first analysis with optional controlled dynamic inspection. Works across Windows (native + WSL) and Linux.

Safety Warning

Show this before starting any analysis:

Warning: malware analysis must be performed on an isolated lab machine or disposable VM. Never run samples on personal or production systems containing real credentials or user data.

Scope

Supported targets:

• Binaries: Windows PE/DLL/.NET, Linux ELF, macOS Mach-O
• Mobile: Android APK
• Documents: Office (doc/xls/ppt with macros), PDF, RTF
• Scripts: JS, VBS, VBA, HTA, PowerShell, BAT, Python, PHP, Perl, Ruby, shell
• Web payloads: HTML smuggling, SVG, MHTML, webshells, loaders

Primary mode is static analysis. Dynamic analysis only in an isolated disposable lab when the user explicitly requests it.

Environment Detection

Before analysis, detect the platform and available tools:

# Linux / WSL
uname -s && uname -m
command -v file strings objdump readelf nm gdb r2 rabin2 yara floss capa exiftool 7z python3 pip3
python3 -c "import pefile, lief, yara, capstone, unicorn" 2>/dev/null

# Windows
$PSVersionTable.PSVersion
Get-Command file,strings,objdump,dumpbin,r2,rabin2,yara,floss,capa,exiftool,7z,python,py,gdb -ErrorAction SilentlyContinue
py -c "import pefile, lief, yara, capstone" 2>$null

Record results. If a mandatory tool is missing, report degraded capability and offer to install after user authorization, or use the built-in Python fallback scripts.

Tool Tiers

Tier 1 — Core (must-have for basic triage)

file, sha256sum/Get-FileHash, strings, python3/py, pip

Tier 2 — Standard analysis

objdump/dumpbin, readelf/nm, yara, exiftool, 7z, radare2 (r2, rabin2), ripgrep (rg), xxd, binwalk

Python packages: pefile, lief, yara-python, capstone, oletools, pycryptodome

Tier 3 — Advanced / specialized

floss, capa, Ghidra headless (analyzeHeadless), Binary Ninja (headless API), jadx, apktool, dnSpy/ilspycmd (.NET), gdb + pwndbg/GEF, x64dbg (Windows GUI), WinDbg (kernel + crash dumps), volatility3, upx, die (Detect It Easy)

Tier 4 — Dynamic (lab only)

gdb + gef/pwndbg, Frida (runtime hooking), strace/ltrace, procmon, wireshark/tshark, fakenet-ng, WinDbg (TTD recording)

Installation commands

Load references/install-guide.md for per-platform install commands (apt, winget, pip, brew).

Required Workflow

For every analysis, follow these steps:

Step 1 — Intake and hashing

1. Copy the sample to a case directory; never modify the original
2. Compute MD5, SHA1, SHA256
3. Identify file type with file or Python magic
4. Record architecture, size, and initial observations

sha256sum sample.bin
file sample.bin

Get-FileHash sample.bin -Algorithm SHA256

If file is missing, use the built-in script: python scripts/triage.py sample.bin

Step 2 — String extraction

1. Extract ASCII and UTF-16 strings
2. Search for URLs, IPs, domains, registry keys, file paths, API names
3. Use floss for obfuscated/decoded strings when available

strings -a -n 6 sample.bin > strings_ascii.txt
strings -a -n 6 -el sample.bin > strings_utf16.txt
rg -i '(https?://|[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+|api\.telegram)' strings_ascii.txt

If strings is missing, run python scripts/triage.py sample.bin --strings.

Step 3 — Metadata and structure

Run the appropriate sub-workflow based on file type:

• PE/DLL/.NET: load references/pe-analysis.md
• ELF/Mach-O: load references/elf-macho-analysis.md
• APK: load references/apk-analysis.md
• Office/scripts: load references/document-script-analysis.md

Common tasks across all types:

1. Inspect imports/exports and flag suspicious APIs
2. Examine sections/segments — check entropy per section
3. Identify compiler, linker, packer, or protector
4. Extract embedded resources, overlays, certificates

Use python scripts/triage.py sample.bin --full for a comprehensive automated triage when dedicated CLI tools are unavailable.

Step 4 — Reverse engineering

Goal: understand what the sample does, not just what it contains. Escalate depth until the question is answered.

Escalation path — follow this order, go deeper only when the current level is insufficient:

1. Imports + exports + symbols — often enough to classify capability (downloader, RAT, stealer). Flag suspicious API combinations: injection (VirtualAllocEx + WriteProcessMemory + CreateRemoteThread), evasion (NtQueryInformationProcess, IsDebuggerPresent), crypto (CryptEncrypt, BCryptEncrypt), network (InternetOpenA, WSAStartup)
2. Capabilities scan — run capa if available to get ATT&CK-mapped capability summary
3. Disassembly of key functions — focus on entry point, functions that reference suspicious strings/APIs, and xrefs to network/crypto calls. Use r2, objdump, or Python capstone — the radare2 skill covers r2 command details
4. Decompilation — when disassembly alone is not enough to understand logic. Use Ghidra headless for native code, ilspycmd for .NET, jadx for APK — the ghidra skill covers Ghidra workflows
5. Control-flow tracing — follow the path from entry to C2 construction, config decoding, or payload drop. Trace data flow across functions
6. Decoder reconstruction — when crypto/encoding is identified, write a minimal deterministic Python script to reproduce the decoding on inert data

What to look for at each level:

• C2 address construction: string concatenation, XOR loops, base64 decode chains, registry/config reads
• Config blob location: resource sections, overlay, .data/.rdata, appended data past PE end
• Anti-analysis: timing checks, debugger detection, VM detection, sandbox evasion
• Persistence: registry keys, scheduled tasks, services, startup folders, WMI subscriptions
• Staging: download-execute chains, process injection, reflective loading

Tool selection by sample type:

• Native PE/ELF/Mach-O → r2 (headless scripting), Ghidra headless, or Binary Ninja headless for decompilation — see radare2, ghidra, binaryninja skills
• .NET → dnSpy/dnSpyEx for GUI decompile+debug, ilspycmd for CLI — see dnspy skill
• APK → jadx for Java decompilation, apktool for smali + resources
• Packed/obfuscated → identify packer first (DIE, capa, section names), unpack with upx -d or manual OEP finding via x64dbg — see x64dbg skill
• Firmware/embedded → binwalk for extraction — see binwalk skill — then analyze extracted ELF/ARM blobs
• Runtime hooking/bypass → Frida for API interception, SSL pinning bypass, anti-debug bypass — see frida skill
• Kernel drivers/rootkits → WinDbg for kernel debugging, SSDT analysis, crash dumps — see windbg skill
• Linux ELF debugging → gdb with pwndbg/GEF for breakpoints, syscall tracing, anti-debug bypass — see gdb skill

Run YARA rules after RE to validate findings:

yara -r rules/ sample.bin

Step 5 — Entropy and payload analysis

1. Compute per-section and sliding-window entropy
2. Classify data regions as encrypted, compressed, code, or padding
3. Identify high-entropy blobs that may be encrypted payloads

Use python scripts/entropy_scan.py sample.bin for zero-dependency entropy analysis with region classification.

Step 6 — Config and IOC extraction

1. Extract C2 URLs, domains, IPs, bot tokens, API keys
2. Recover configuration blobs (XOR, AES, RC4, base64 layers)
3. Write minimal deterministic decoder scripts when needed
4. Record provenance of every extracted value

Step 7 — Dynamic analysis (lab only, on explicit request)

Only perform when user authorizes and environment is an isolated lab:

1. GDB (Linux/WSL): set breakpoints on network/crypto APIs, trace execution, bypass ptrace anti-debug — see gdb skill
2. x64dbg (Windows): trace API calls, dump memory at runtime, unpack — see x64dbg skill
3. WinDbg: kernel debugging, driver/rootkit analysis, crash dump analysis, TTD recording — see windbg skill
4. Frida: runtime hooking across platforms, bypass protections, intercept crypto/network calls — see frida skill
5. dnSpy: .NET debugging with decompilation, set breakpoints on managed methods — see dnspy skill
6. strace/ltrace: log syscalls and library calls
7. procmon: monitor filesystem/registry/network activity
8. fakenet-ng/inetsim: intercept network traffic

# GDB with pwndbg/gef in WSL or Linux
gdb -q -ex "break send" -ex "break connect" -ex "run" ./sample.elf

# Frida — trace all network calls
frida -f ./sample -l network_trace.js

# WinDbg — record with Time Travel Debugging for reverse analysis
# File → Launch Executable (Advanced) → Record with TTD

Load references/dynamic-analysis.md for detailed dynamic workflows. Load individual tool skills for command references.

Step 8 — Family attribution

Attempt attribution only with technical evidence:

• Config layout, field names, mutex names
• Protocol structure, user-agent format
• Crypto constants, packer signatures
• Distinctive code patterns or builder markers

If attribution is uncertain, state candidates with confidence level.

Step 9 — Report

Produce structured output containing:

• File type, architecture, SHA256
• Malware family (if determined) with confidence
• C2 infrastructure (URLs, IPs, domains) with provenance
• Obfuscation/packing method
• Persistence mechanisms
• Extracted stages with hashes
• Evidence file locations
• Explicit limitations of the analysis

Autonomy Rules

• Proceed automatically through the next analytical step when it is within scope and safe
• Do not stop to ask when the next action is obvious (parse next stream, decode next blob, follow xref)
• Only interrupt when: a tool must be installed, a network action exceeds authorized scope, or progress is blocked by an external dependency
• Prefer offline analysis over remote retrieval unless retrieval is already authorized
• If one method fails, try equivalent tools or lower-level approaches before declaring a blocker

Fallback Strategy

When a preferred CLI tool is missing, use this hierarchy:

1. Python package equivalent — pefile for PE, lief for PE/ELF/Mach-O, oletools for Office, capstone for disassembly
2. Built-in scripts in scripts/ — zero-dependency Python implementations for triage, entropy, strings, IAT dump
3. Manual Python — write a minimal one-off script using struct, hashlib, re, standard library
4. Report degraded — document what could not be analyzed and why

Built-in Scripts

The scripts/ directory contains self-contained Python tools that require no external packages beyond the standard library (except where noted). The agent can use these directly when system CLI tools are unavailable.

| Script | Purpose | Dependencies | |---|---|---| | scripts/triage.py | Hash, file-type, strings, PE/ELF header parsing, section info | stdlib only | | scripts/entropy_scan.py | Per-section and sliding-window entropy with region classification | stdlib only | | scripts/iat_analyzer.py | Import table parsing with suspicious-API categorization | stdlib only | | scripts/string_scanner.py | IOC-focused string extraction (URLs, IPs, domains, keys, paths) | stdlib only | | scripts/yara_scanner.py | YARA rule runner with built-in generic rules | yara-python | | scripts/setup_env.py | Detect OS, check tools, install missing packages after confirmation | stdlib only |

Resources

scripts/

• triage.py — all-in-one triage: hashing, file identification, header parsing, string extraction. Run as first step when CLI tools are unavailable.
• entropy_scan.py — Shannon entropy per section and sliding-window heatmap with encrypted/compressed/code classification.
• iat_analyzer.py — PE import table parser with 6-category suspicious API scoring (injection, evasion, process, memory, crypto, network).
• string_scanner.py — extract and classify strings by IOC type (URL, IP, domain, registry, file path, API name, crypto constant).
• yara_scanner.py — run YARA rules against samples; includes built-in generic detection rules.
• setup_env.py — detect OS/arch, enumerate available tools, install missing ones via pip/apt/winget after user consent.

references/

• install-guide.md — per-platform installation commands for all tool tiers. Load when the agent needs to install tools.
• pe-analysis.md — detailed PE/.NET analysis procedure. Load for Windows binary analysis.
• elf-macho-analysis.md — ELF and Mach-O analysis procedure. Load for Linux/macOS binary analysis.
• document-script-analysis.md — Office, PDF, and script analysis procedure. Load for document/script malware.
• dynamic-analysis.md — GDB, x64dbg, strace, procmon workflows. Load when dynamic analysis is requested.
• yara-rules.md — generic YARA rule templates for common malware patterns.

assets/

• case-template/ — directory structure for organizing case evidence. Copy to create a new case workspace.