Skip to content

aniket2348823/vigilagent / .agents/skills/analyzing-macro-malware-in-office-documents

analyzing-macro-malware-in-office-documents

Flagged

Analyzes malicious VBA macros embedded in Microsoft Office documents (Word, Excel, PowerPoint) to identify download cradles, payload execution, persistence mechanisms, and anti-analysis techniques. Uses olevba, oledump, and VBA deobfuscation to extract the attack chain. Activates for requests involving Office macro analysis, VBA malware investigation, maldoc analysis, or document-based threat examination.

FileKindSize
LICENSEother11.0 KB
SKILL.mdskill md11.8 KB
references/api-reference.mdmarkdown2.9 KB
scripts/agent.pyscript8.6 KB

references/api-reference.md

View on GitHub
# API Reference: Office Macro Malware Analysis Tools

## olevba - VBA Macro Extraction (oletools)

### CLI Syntax
```bash
olevba document.docm                   # Full analysis
olevba --decode --deobf document.docm  # Decode + deobfuscate
olevba --code document.docm            # Extract VBA source only
olevba --json document.docm            # JSON output
olevba --reveal document.docm          # Reveal hidden content
```

### Output Sections
| Section | Content |
|---------|---------|
| `AutoExec` | Auto-execution triggers (AutoOpen, Document_Open) |
| `Suspicious` | Dangerous functions (Shell, WScript, CreateObject) |
| `IOC` | Extracted indicators (URLs, IPs, file paths) |
| `Hex String` | Decoded hex-encoded strings |

### Python API
```python
from oletools.olevba import VBA_Parser
vba = VBA_Parser("document.docm")
if vba.detect_vba_macros():
    for (fn, stream, vba_fn, code) in vba.extract_macros():
        print(code)
    for (kw_type, keyword, desc) in vba.analyze_macros():
        print(f"{kw_type}: {keyword}")
vba.close()
```

## oleid - Document Capability Identification

### CLI Syntax
```bash
oleid document.docm
```

### Indicators
| Indicator | Risk Values |
|-----------|-------------|
| `VBA Macros` | True/False |
| `XLM Macros` | True/False |
| `External Relationships` | True/False |
| `ObjectPool` | True/False |
| `Flash` | True/False |

## oledump.py - OLE Stream Analysis

### CLI Syntax
```bash
oledump.py document.docm                    # List streams
oledump.py -s 8 -v document.docm           # Extract stream 8
oledump.py -p plugin_vba_dco document.docm  # VBA decompile
oledump.py -p plugin_msg.py document.msg    # MSG file parsing
```

### Stream Markers
| Marker | Meaning |
|--------|---------|
| `M` | Contains VBA macros |
| `m` | Contains macro attributes |
| `O` | Contains OLE objects |

## XLMDeobfuscator - Excel 4.0 Macros

### CLI Syntax
```bash
xlmdeobfuscator -f document.xlsm
xlmdeobfuscator -f document.xlsm --output-format json
```

### Dangerous XLM Functions
| Function | Purpose |
|----------|---------|
| `EXEC()` | Execute shell command |
| `CALL()` | Call DLL function |
| `REGISTER()` | Register DLL function |
| `URLDownloadToFileA` | Download file from URL |

## VBA Auto-Execution Triggers

| Trigger | Application |
|---------|-------------|
| `Auto_Open` / `AutoOpen` | Word |
| `Document_Open` | Word |
| `Workbook_Open` | Excel |
| `Auto_Close` | Word |
| `AutoExec` | Word |

## VBA Suspicious Functions

| Function | Risk |
|----------|------|
| `Shell()` | Command execution |
| `WScript.Shell` | Windows scripting |
| `CreateObject()` | COM object instantiation |
| `URLDownloadToFile` | File download |
| `MSXML2.XMLHTTP` | HTTP requests |
| `ADODB.Stream` | Binary file writing |
| `CallByName` | Indirect method invocation |
| `Environ()` | Environment variable access |

## ViperMonkey - VBA Emulation

### Syntax
```bash
vmonkey document.docm
vmonkey --iocs document.docm   # Extract IOCs only
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall