MacroScope is an open-source, offline-first framework for detecting and analyzing malicious document files.
It supports Microsoft Office, PDF, and RTF formats, helping analysts and students quickly identify hidden threats like macros, embedded payloads, and exploit signatures.
MacroScope is for educational and research purposes only. Use it only on files you have permission to analyse. The authors are not responsible for misuse, damage, or any consequences arising from the use of this software. Always run MacroScope in a safe, isolated environment when working with suspicious files.
- 🕵️ Detects malicious macros, JavaScript, and embedded objects
- 📂 Supports
.doc,.docx,.xls,.xlsx,.ppt,.pptx,.pdf,.rtf - 🔍 Extracts and deobfuscates VBA macros & PDF JavaScript
- 🚨 Suspiciousness scoring with clear risk indicators
- 💻 100% local execution – no cloud upload needed
- 🛡️ Runs in isolated processes to protect your system
- 📌 OneNote & HTML Smuggling Support – Expand file format coverage
- 📌 Dynamic Analysis Sandbox Mode – Optional safe execution to capture runtime behavior
- 📌 Threat Intel Integration – Check file hashes against known malware databases
- 📌 GUI Frontend – Drag-and-drop document analysis for non-technical users
- 📌 Rule-based Scoring Engine – Customizable detection rules
- 📌 Timeline View – Visualize macro or script execution flow
- 📌 Multi-Language Support – Internationalized reports
- 📨 Email Security – Triage suspicious attachments before opening them
- 🧪 Malware Research – Quickly surface potential payloads for deeper analysis
- 🏫 Education & Training – Teach students about document-based threats
- 🛠️ Incident Response – Rapidly investigate documents during phishing incidents
- 📊 Threat Hunting – Identify recurring malicious document patterns
- Python 3.9+
pippackage manager
# 1️⃣ Clone the repository
git clone https://github.com/pottsie283/MacroScope
cd macroscope
# 2️⃣ Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 3️⃣ Install dependencies
pip install -r requirements.txt
# 4️⃣ Run MacroScope
python -m scripts.cli --help