RAPTOR

Reverse Analysis Platform for Threat Operations & Response

A professional-grade malware reverse engineering platform built for SOC analysts, incident responders, and malware researchers. Drop any suspicious binary and get a full automated static analysis in seconds.

---

🧬 What is RAPTOR?

RAPTOR is a self-contained malware reverse engineering platform that automates the most time-consuming parts of static binary analysis. Built on independent analysis modules, it gives SOC analysts an instant actionable verdict — risk score, MITRE ATT&CK TTPs, IOC export, family config decryption, and a full interactive dashboard — without touching a debugger or disassembler.

No cloud. No subscriptions. No sample uploads to third parties. Everything runs locally on your machine.

---

⚡ Features

🔬 Analysis Pipeline — 17 Stages

Module	What It Does
Magic Detector	Identifies file type from magic bytes — never trusts extensions
Entropy Scanner	Shannon entropy + high-entropy region map — pinpoints packed/encrypted sections
PE Parser	Full PE structure, 60+ suspicious API import flags, imphash, ssdeep fuzzy hash
Rich Header Parser	Extracts hidden compiler/linker fingerprint — compiler version, build tool, rich_hash pivot
PE Overlay Detector	Finds data appended after last PE section — dropper/SFX payload detection
ELF Parser	Full ELF binary analysis for Linux and IoT malware
.NET Analyzer	dnfile-based heap extraction — user strings, type names, suspicious methods, IOCs
Packer ID	Byte-signature detection for UPX, Themida, VMProtect, MPRESS, 20+ packers
Auto Unpacker	Detects UPX and auto-runs upx -d — re-analyzes unpacked binary automatically
Language Detector	Identifies compiler/language — .NET, Go, Rust, Nim, AutoIT, VB6, Python, and more
XOR Engine	Brute-forces all XOR variants — single-byte, multi-byte, rolling, known-plaintext, known malware key table
RC4 Engine	KSA pattern detection + short key brute-force
AES Hunter	S-box pattern detection, key candidate extraction, CBC/ECB decryption
Cipher Engine	ChaCha20, Salsa20, DES, 3DES, Blowfish
Blob Pipeline	Multi-layer decode — extracts blobs, tries all ciphers, recurses, YARA-scans decoded payloads
Key Recovery	Hex/base64/UTF-16 key extraction, RC4 KSA reverse, AES S-box detection, PBKDF2 derivation
String Hunter	ASCII + Unicode extraction including XOR-recovered and .NET heap strings
String Categorizer	Classifies every string — network, filesystem, crypto, commands, persistence, credentials, C2 indicators, mutexes
IOC Extractor	IPs, domains, URLs, registry keys, mutexes, file paths, crypto wallets, named pipes
Script Deobfuscator	PowerShell, VBScript, JavaScript, Batch — multi-pass deobfuscation + IOC extraction
Anti-Analysis Detector	Anti-debug, anti-VM, anti-sandbox, timing checks, evasion technique detection
Family Config Extractor	Decrypts full malware configs — AsyncRAT, njRAT, Remcos, AgentTesla, Cobalt Strike, and more
YARA Engine	25+ bundled rules covering ransomware, RATs, stealers, C2 frameworks
Risk Engine	Unified risk score 0–100, MITRE ATT&CK mapping (60+ TTPs)
VirusTotal	Hash pre-check at startup (fast), full lookup at completion

🎯 Intelligence Layer

• Risk Score 0–100 — unified score from all detection signals
• MITRE ATT&CK Mapping — automatic TTP tagging from detected behaviors (60+ mappings)
• IOC Export — CSV, STIX2, and full JSON for SIEM/MISP ingestion
• Family Config Decryption — AsyncRAT AES-256-CBC + PBKDF2, Remcos RC4, Cobalt Strike beacon XOR, and more
• Scan History — persistent analysis log across sessions

🖥 SOC Web Dashboard

• Drag & drop file upload — any format
• Real-time progress streaming via Server-Sent Events
• Triage mode (?triage=1) — skips blob pipeline for a fast 5–15 second result
• 14 interactive result tabs: Overview, VirusTotal, YARA, API Imports, IOCs, MITRE ATT&CK, Anti-Analysis, Language, .NET, Config, Decrypt, Entropy, Strings, Risk Breakdown
• CyberChef-style Decoder Workbench for manual decryption
• Dark terminal aesthetic built for extended analysis sessions

---

🚀 Quick Start

Requirements

• Python 3.10+
• Windows, Linux, or macOS

Install

# Clone the repo
git clone https://github.com/YOUR_USERNAME/raptor.git
cd raptor

# Install dependencies
pip install -r requirements.txt

# Windows only — replace python-magic with:
pip install python-magic-bin

Optional: UPX auto-unpacking

# Ubuntu/Debian
sudo apt install upx-ucl

# macOS
brew install upx

# Windows
choco install upx

Optional: VirusTotal integration

# Linux/macOS
export VT_API_KEY=your_key_here

# Windows
set VT_API_KEY=your_key_here

Run

# Launch the web UI
python app.py

# Open your browser
http://localhost:5000

CLI Mode (no browser needed)

# Analyze a single file
python main.py --file sample.exe

# Batch analyze a folder
python main.py --dir ./samples/

# Output JSON to stdout
python main.py --file sample.exe --json

---

🧪 Testing with Synthetic Samples

Don't have a sample? Generate safe synthetic test files that exercise every module:

python tests/create_test_samples.py

# Then run against them
python main.py --dir samples/test/

This creates synthetic files including XOR-encoded payloads, high-entropy blobs, layered encoding, and a fake PE with embedded IOCs — zero actual malware.

---

📁 Project Structure

raptor/
├── app.py                            ← Flask web server + main analysis pipeline
├── main.py                           ← CLI entry point
├── requirements.txt
│
├── core/                             ← Analysis engine modules
│   ├── aes_hunter.py                 ← AES S-box detection + key extraction
│   ├── binary_scanner.py             ← DWORD IP scan, resource string extraction
│   ├── blob_pipeline.py              ← Multi-layer blob decode pipeline (v7.0+)
│   ├── cipher_engine.py              ← ChaCha20/Salsa20/DES/Blowfish + format detection
│   ├── decoder_engine.py             ← AES-CBC/ECB/CTR/GCM, RC4, base64, zlib
│   ├── dotnet_parser.py              ← dnfile-based .NET assembly analysis
│   ├── elf_parser.py                 ← ELF binary parsing (Linux/IoT)
│   ├── entropy_scanner.py            ← Shannon entropy + high-entropy region finder
│   ├── family_extractor.py           ← Malware family config extractors
│   ├── ioc_extractor.py              ← IOC aggregation and deduplication
│   ├── key_recovery.py               ← Key candidate extraction + PBKDF2 derivation
│   ├── language_detector.py          ← Compiler/language fingerprinting
│   ├── magic_detector.py             ← File type identification
│   ├── pe_parser.py                  ← PE header, imports, sections, hashes
│   ├── ps_deobfuscator.py            ← PowerShell/VBS/JS/BAT deobfuscation
│   ├── rc4_engine.py                 ← RC4 KSA detection + brute-force
│   ├── risk_engine.py                ← Risk scoring + MITRE ATT&CK mapping
│   ├── script_analyzer.py            ← Script-specific IOC and pattern analysis
│   ├── string_categorizer.py         ← String classification into IOC buckets (v9.0)
│   ├── string_hunter.py              ← ASCII/Unicode string extraction
│   ├── unpacker.py                   ← UPX auto-unpack + PE overlay + Rich header (v9.0)
│   ├── virustotal.py                 ← VT hash lookup
│   └── xor_engine.py                 ← XOR brute-force + known malware key table
│
├── detectors/                        ← Specialized detection modules
│   ├── anti_analysis_detector.py     ← Anti-debug/VM/sandbox detection
│   ├── packer_id.py                  ← Packer signature identification
│   └── yara_engine.py               ← YARA rule engine (25+ bundled rules)
│
├── output/
│   └── reporter.py                   ← JSON/CSV/STIX report generation
│
├── web/
│   └── index.html                    ← Full SOC dashboard (single-file SPA)
│
├── tests/
│   └── create_test_samples.py        ← Synthetic test sample generator
│
└── samples/
    └── test/                         ← Generated test samples go here

---

🎯 YARA Rules Included

RAPTOR ships with 25+ production YARA rules covering:

Category	Families
Ransomware	WannaCry, Ryuk, Conti, LockBit, Generic
RATs	njRAT, AsyncRAT, DarkComet, QuasarRAT
Stealers	RedLine, Vidar, Generic Browser Stealer
Loaders	Emotet, GuLoader
C2 Frameworks	Cobalt Strike Beacon, Metasploit/Meterpreter
Credential Tools	Mimikatz
Web Shells	PHP Generic, PowerShell Backdoor
Packers	UPX, Base64 Dropper
Keyloggers	Generic Hook-Based

Drop your own .yar files into the yara_rules/ directory — they're automatically loaded.

---

🔐 Malware Family Config Extraction

RAPTOR decrypts full malware configurations — not just detection, but actual C2 addresses, ports, encryption keys, mutex names, and install paths:

Family	Extraction Method	What You Get
AsyncRAT / DCRat	AES-256-CBC + PBKDF2-SHA1 (50,000 iter)	C2 host, port, mutex, AES key, salt, install path, anti flag, version, group
njRAT (Bladabindi)	Plaintext / Base64	C2, port, campaign ID, mutex, install name
AgentTesla	String pattern analysis	SMTP credentials, FTP credentials, C2 panel URL
Remcos	RC4-encrypted config block	C2, port, mutex, keylogger path, screenshot interval
Cobalt Strike	Beacon config (XOR 0x69 + base64)	C2, malleable profile, sleep time, jitter, named pipe
NanoCore	Plaintext config + plugin list	C2, port, build GUID, plugin names
QuasarRAT	AES-encrypted config	C2, port, certificate, mutex, install dir
Formbook	String pattern analysis	C2 domains, decoy URLs

---

📊 Risk Scoring

RAPTOR uses a weighted multi-signal scoring engine:

Signal	Max Points
YARA CRITICAL match	+40
YARA HIGH match	+25
Suspicious API (HIGH)	+12 each
Threat indicators	+5–25
Crypto wallet detected	+20
Anti-analysis techniques	+2–12
High entropy (packed)	+10
Extension mismatch	+10
Packer detected	+8

Score	Verdict
75–100	🔴 MALICIOUS
50–74	🟠 LIKELY MALICIOUS
25–49	🟡 SUSPICIOUS
0–24	🟢 LOW RISK

---

📤 IOC Export Formats

Format	Use Case
CSV	SIEM ingestion, spreadsheet analysis
STIX2	Threat intel sharing (MISP, ISACs, government feeds)
JSON	Full raw report, API integrations

---

🔒 Working Safely with Real Malware

Never run malware samples on a production machine.

Recommended workflow:

1. Disable Windows Defender for your samples folder (Exclusions)
   OR work inside an isolated VM (VirtualBox / VMware)

2. Download samples from trusted repos only:
   - MalwareBazaar (bazaar.abuse.ch) — password: "infected"
   - theZoo (github.com/ytisf/theZoo) — password: "infected"

3. Extract with 7-Zip using the password
   7z e sample.zip -pinfected -o./extracted/

4. Drop the extracted binary into RAPTOR
   → All analysis is static — nothing executes

5. Share only the report output, never the binary

---

🗺 Version History

v9.0 — Current

• New: core/unpacker.py — UPX auto-unpack, PE overlay detection, Rich header parsing
• New: core/string_categorizer.py — classifies strings into network / filesystem / crypto / commands / persistence / credentials / C2 / mutex buckets
• New: Known malware XOR key table — AsyncRAT, NanoCore, QuasarRAT, Remcos, njRAT, Lokibot, Emotet and more tried before brute-force
• New: Parallel engine execution — entropy, XOR, RC4, AES, YARA, binary scanner run concurrently
• New: VirusTotal hash-first check — VT queried at 6% progress before any heavy analysis
• New: Triage mode (?triage=1) — skips blob pipeline for 5–15 second fast results
• New: YARA scanning of decoded blob pipeline payloads
• New: ssdeep fuzzy hash + imphash added to all PE reports
• Fixed: AsyncRAT config decryption — PBKDF2 password, IV source, and AES padding all corrected
• Fixed: Blob pipeline hang — generate_derived_keys combinatorial explosion (PBKDF2×10000 on hundreds of strings)
• Fixed: Blob pipeline threading — replaced broken multiprocessing.Pool with wall-clock budgeted threads

v7.0

• Multi-layer blob decode pipeline (core/blob_pipeline.py)
• core/cipher_engine.py — ChaCha20, Salsa20, DES, Blowfish, custom cipher support
• core/key_recovery.py — comprehensive key extraction and PBKDF2 derivation
• core/ps_deobfuscator.py — PowerShell/VBS/JS/BAT deobfuscation
• Flask web UI with SSE live progress streaming
• CyberChef-style Decoder Workbench
• VirusTotal integration
• Script deobfuscation hooks

Pre-v7.0

• Core 8-module CLI pipeline
• Web UI, risk scoring, MITRE ATT&CK mapping, IOC export
• RC4 + AES decryption engines
• Family config extractors (initial set)
• Rich console output + scan history

---

🗺 Roadmap

• Core analysis pipeline (PE, entropy, strings, XOR, IOCs, YARA)
• Web UI + SOC dashboard
• RC4 + AES + multi-cipher decryption engines
• VirusTotal integration
• Multi-layer blob pipeline
• Family config extraction + decryption (AsyncRAT, Remcos, njRAT, AgentTesla, CobaltStrike...)
• .NET assembly analysis
• ELF / Linux malware support
• Auto UPX unpacking
• Script deobfuscation (PS1, VBS, JS, BAT)
• Dynamic sandbox integration (Cuckoo / Cape)
• Document analyzer (PDF, Office macros)
• Team dashboard + case management
• Docker deployment

---

🤝 Contributing

Pull requests welcome. If you have YARA rules, detection signatures, or new analysis modules — open a PR.

1. Fork the repo
2. Create a feature branch (git checkout -b feature/new-module)
3. Commit your changes
4. Open a pull request

---

⚠ Disclaimer

RAPTOR is built exclusively for defensive security purposes — malware analysis, incident response, threat hunting, and security research. Do not use it to assist in the creation, deployment, or obfuscation of malicious software. The authors accept no liability for misuse.

---

📄 License

MIT License — free to use, modify, and distribute with attribution.

---

🙏 Built With

• pefile — PE parsing
• yara-python — YARA rule engine
• capstone — disassembly engine
• dnfile — .NET assembly parsing
• pycryptodome — cryptography engine
• Flask — web server
• Rich — terminal output

---

RAPTOR · Reverse Analysis Platform for Threat Operations & Response

Built for defenders. Runs locally.