# Com Interface Reconstruction

> Reconstruct COM and WRL interface definitions from IDA Pro decompiled Windows PE binaries by analyzing vtable slots, QueryInterface/AddRef/Release patterns, mangled names, and WRL template instantiations. Use when the user asks to reconstruct COM interfaces, find COM classes, decode WRL templates, map CLSIDs, generate IDL descriptions, identify QueryInterface patterns, analyze vtable layouts as C…

- **Type:** Skill
- **Install:** `agentstack add skill-marcosd4h-deepextractruntime-com-interface-reconstruction`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [marcosd4h](https://agentstack.voostack.com/s/marcosd4h)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [marcosd4h](https://github.com/marcosd4h)
- **Source:** https://github.com/marcosd4h/DeepExtractRuntime/tree/main/skills/com-interface-reconstruction

## Install

```sh
agentstack add skill-marcosd4h-deepextractruntime-com-interface-reconstruction
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# COM / WRL Interface Reconstruction

## Purpose

Reconstruct complete COM interface and WRL class definitions from DeepExtractIDA analysis databases. Windows binaries are heavily COM-based; this skill extracts structured COM metadata from:

- **VTable slot analysis** -- map vtable layouts to COM interface method tables
- **QueryInterface/AddRef/Release patterns** -- identify IUnknown implementations
- **Mangled name decoding** -- extract full C++ type info from MSVC mangled names
- **WRL template instantiation decoding** -- parse `Microsoft::WRL::*` template parameters to recover interface lists, RuntimeClassFlags, and class hierarchies
- **Decompiled code pattern matching** -- find QI dispatch tables, CLSID registrations, and class factory patterns

Output is structured COM metadata: interfaces with method slots, class-to-interface maps, WRL template breakdowns, and IDL-like descriptions.

**This is NOT security analysis.** The goal is faithful COM structure reconstruction.

## Data Sources

### SQLite Databases (primary)

Individual analysis DBs in `extracted_dbs/` provide per-function data:

| Field                                  | COM Relevance                                                              |
| -------------------------------------- | -------------------------------------------------------------------------- |
| `mangled_name`                         | Full C++ type info: WRL templates, interface names, class names            |
| `vtable_contexts`                      | Reconstructed class skeletons with virtual method slots                    |
| `function_name` / `function_signature` | Demangled names showing COM patterns                                       |
| `outbound_xrefs`                       | VTable call info (`is_vtable_call`, `vtable_info`), CoCreateInstance calls |
| `simple_outbound_xrefs`                | Simplified callee info for API usage detection                             |
| `decompiled_code`                      | QI dispatch logic, GUID comparisons, class factory implementations         |
| `string_literals`                      | GUID strings, interface name strings                                       |

### Finding a Module DB

Reuse the decompiled-code-extractor skill's `find_module_db.py`:

```bash
python .claude/skills/decompiled-code-extractor/scripts/find_module_db.py --list
python .claude/skills/decompiled-code-extractor/scripts/find_module_db.py appinfo.dll
```

### Quick Cross-Dimensional Search

To search across function names, signatures, strings, APIs, classes, and exports in one call:

```bash
python .claude/helpers/unified_search.py  --query "SearchTerm"
python .claude/helpers/unified_search.py  --query "SearchTerm" --json
```

## Utility Scripts

Pre-built scripts in `scripts/` handle all COM extraction. Run from the workspace root.

### scan_com_interfaces.py -- Discover All COM Interfaces (Start Here)

Scan a module for all COM-related structures:

```bash
# Full COM scan -- interfaces, QI patterns, vtable layouts
python .claude/skills/com-interface-reconstruction/scripts/scan_com_interfaces.py 

# JSON output for programmatic use
python .claude/skills/com-interface-reconstruction/scripts/scan_com_interfaces.py  --json

# Filter to functions with vtable contexts only
python .claude/skills/com-interface-reconstruction/scripts/scan_com_interfaces.py  --vtable-only
```

Output: COM interface inventory, QI/AddRef/Release implementations, vtable-derived method tables, and COM API usage summary.

### decode_wrl_templates.py -- Decode WRL Template Instantiations

Parse `Microsoft::WRL::*` template parameters from mangled names:

```bash
# Decode all WRL templates in a module
python .claude/skills/com-interface-reconstruction/scripts/decode_wrl_templates.py 

# JSON output
python .claude/skills/com-interface-reconstruction/scripts/decode_wrl_templates.py  --json

# Filter to specific WRL type (RuntimeClass, ComPtr, etc.)
python .claude/skills/com-interface-reconstruction/scripts/decode_wrl_templates.py  --type RuntimeClass
```

Output: decoded WRL class hierarchies, interface lists per RuntimeClass, RuntimeClassFlags, ComPtr usage, weak reference support.

### map_class_interfaces.py -- Map Interfaces to Classes

Build a class-to-interface mapping from QI logic, WRL metadata, and vtable analysis:

```bash
# Map all classes to their interfaces
python .claude/skills/com-interface-reconstruction/scripts/map_class_interfaces.py 

# JSON output
python .claude/skills/com-interface-reconstruction/scripts/map_class_interfaces.py  --json

# Focus on a specific class
python .claude/skills/com-interface-reconstruction/scripts/map_class_interfaces.py  --class CAppInfoService
```

Output: per-class interface lists, evidence sources (QI, WRL, vtable), base interfaces, aggregation.

### generate_idl.py -- Generate IDL-Like Descriptions

Produce IDL-like interface descriptions from reconstructed COM metadata:

```bash
# Generate IDL for all discovered interfaces
python .claude/skills/com-interface-reconstruction/scripts/generate_idl.py 

# Write to file
python .claude/skills/com-interface-reconstruction/scripts/generate_idl.py  --output interfaces.idl

# Filter to specific interface
python .claude/skills/com-interface-reconstruction/scripts/generate_idl.py  --interface IAppInfoService
```

Output: IDL-syntax interface blocks with method signatures, parameter types, HRESULT returns, and vtable slot comments.

## Workflows

```
COM Reconstruction Progress:
- [ ] Step 1: Orient -- find module DB, get module overview
- [ ] Step 2: Scan -- discover all COM interfaces and vtable layouts
- [ ] Step 3: Decode WRL -- parse WRL template instantiations
- [ ] Step 4: Map -- build class-to-interface mappings
- [ ] Step 5: Generate -- produce IDL-like descriptions
- [ ] Step 6: Refine -- cross-reference with decompiled code for details
```

**Step 1**: Orient

Find the module DB and understand scope:

```bash
python .claude/skills/decompiled-code-extractor/scripts/find_module_db.py appinfo.dll
python .claude/skills/classify-functions/scripts/triage_summary.py 
```

Check the triage for `com_rpc` category count to gauge COM density.

**Step 2**: Scan COM Interfaces

Run the main scanner:

```bash
python .claude/skills/com-interface-reconstruction/scripts/scan_com_interfaces.py 
```

Review output for:

- **IUnknown implementations** -- classes implementing QI/AddRef/Release
- **VTable-derived interfaces** -- method tables extracted from vtable contexts
- **COM API usage** -- CoCreateInstance, CoInitialize, etc.

**Step 3**: Decode WRL Templates

```bash
python .claude/skills/com-interface-reconstruction/scripts/decode_wrl_templates.py 
```

WRL templates encode rich type info in mangled names:

- `RuntimeClassImpl` -- reveals which interfaces a class implements
- `ComPtr` -- reveals interface usage at call sites
- `FtmBase` -- indicates free-threaded marshalling support
- `RuntimeClassFlags` -- 1=WinRt, 2=ClassicCom, 3=WinRtClassicComMix

**Step 4**: Map Interfaces to Classes

```bash
python .claude/skills/com-interface-reconstruction/scripts/map_class_interfaces.py 
```

Evidence sources merged:

1. **WRL templates** (highest confidence) -- interface lists from RuntimeClassImpl parameters
2. **QI dispatch code** -- GUID comparisons in QueryInterface implementations
3. **VTable contexts** -- method slot analysis
4. **Mangled name patterns** -- `@ClassName@@` patterns linking methods to classes

**Step 5**: Generate IDL

```bash
python .claude/skills/com-interface-reconstruction/scripts/generate_idl.py  --output reconstructed.idl
```

**Step 6**: Refine

Use decompiled code to fill in details:

- Read QueryInterface implementations to discover additional interfaces via GUID comparisons
- Examine class factories (`DllGetClassObject`, `IClassFactory::CreateInstance`) for CLSID mappings
- Cross-reference with imports for COM API usage patterns
- Use the [reconstruct-types](../reconstruct-types/SKILL.md) skill for struct field analysis of COM objects

## Direct Helper Module Access

For custom queries:

```python
from helpers import open_individual_analysis_db

with open_individual_analysis_db("extracted_dbs/module_hash.db") as db:
    # Find all QI implementations
    qi_funcs = db.search_functions(name_contains="QueryInterface")
    # Find WRL classes
    wrl_funcs = db.search_functions(name_contains="RuntimeClassImpl")
    # Custom vtable query
    rows = db.execute_query("""
        SELECT function_name, vtable_contexts FROM functions
        WHERE vtable_contexts IS NOT NULL AND vtable_contexts NOT LIKE '[]%'
    """)
```

**Library tagging**: `filter_by_library(load_function_index(module), library='WRL')` identifies WRL infrastructure vs application COM classes.

## COM VTable Layout Reference

Standard IUnknown vtable (all COM interfaces inherit this):

| Slot | Offset | Method           | Signature                                 |
| ---- | ------ | ---------------- | ----------------------------------------- |
| 0    | +0x00  | `QueryInterface` | `HRESULT (REFIID riid, void **ppvObject)` |
| 1    | +0x08  | `AddRef`         | `ULONG ()`                                |
| 2    | +0x10  | `Release`        | `ULONG ()`                                |
| 3+   | +0x18+ | Custom methods   | Interface-specific                        |

IDispatch extends IUnknown:

| Slot | Offset | Method             |
| ---- | ------ | ------------------ |
| 3    | +0x18  | `GetTypeInfoCount` |
| 4    | +0x20  | `GetTypeInfo`      |
| 5    | +0x28  | `GetIDsOfNames`    |
| 6    | +0x30  | `Invoke`           |

## WRL RuntimeClassFlags Reference

| Value | Meaning              | COM Characteristics                       |
| ----- | -------------------- | ----------------------------------------- |
| 1     | `WinRt`              | Windows Runtime class, IInspectable-based |
| 2     | `ClassicCom`         | Classic COM, IUnknown-based               |
| 3     | `WinRtClassicComMix` | Hybrid: WinRT + classic COM interfaces    |

## Microsoft Mangled Name Patterns for COM

| Pattern                   | Meaning                    | Example                                               |
| ------------------------- | -------------------------- | ----------------------------------------------------- |
| `??_7Class@@6B@`          | VFTable symbol             | `??_7CMyService@@6BIMyService@@@`                     |
| `??0Class@@`              | Constructor                | `??0CAppInfoService@@QEAA@XZ`                         |
| `?QueryInterface@Class@@` | QI implementation          | `?QueryInterface@CMyClass@@UEAAJAEBU_GUID@@PEAPEAX@Z` |
| `?AddRef@Class@@`         | AddRef                     | `?AddRef@CMyClass@@UEAAKXZ`                           |
| `?Release@Class@@`        | Release                    | `?Release@CMyClass@@UEAAKXZ`                          |
| `RuntimeClassImpl`   | WRL class implementation   | Encodes flags + interface list                        |
| `ComPtr`            | Smart pointer to interface | Reveals interface usage                               |
| `FillArrayWithIid`        | IID enumeration helper     | Lists supported IIDs                                  |

## Known Limitations

- **QI dispatch table parsing**: The skill does not yet parse `QueryInterface`
  dispatch tables (the `if/else if` or `switch` chains comparing against IID
  GUIDs in decompiled code) to extract the full set of supported interfaces
  per class. Currently interface discovery relies on vtable symbols, WRL
  template decoding, and mangled names. Adding structured QI dispatch table
  extraction would improve interface coverage for classes that implement
  multiple interfaces with hand-written QI logic.

## Integration with Other Skills

| Task | Recommended Skill |
|------|-------------------|
| Cross-reference with ground-truth COM extraction data | com-interface-analysis |
| Reconstruct struct layouts for COM classes | reconstruct-types |
| Trace call chains through COM vtable methods | callgraph-tracer |
| Map COM entry points as attack surface | map-attack-surface |
| Build security dossier for COM methods | security-dossier |
| Lift COM class methods to clean code | batch-lift |

## Performance

| Operation | Typical Time | Notes |
|-----------|-------------|-------|
| Scan COM interfaces | ~5-10s | Full module vtable scan |
| Decode WRL templates | ~2-3s | Mangled name parsing |
| Map class interfaces | ~3-5s | Cross-references vtables and QI |
| Generate IDL | ~1-2s | After interface scan |

## Additional Resources

- For detailed COM/WRL technical reference, see [reference.md](reference.md)
- For type reconstruction (struct fields), see [reconstruct-types](../reconstruct-types/SKILL.md)
- For function classification, see [classify-functions](../classify-functions/SKILL.md)
- For DB schema and JSON formats, see [data_format_reference.md](../../docs/data_format_reference.md)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [marcosd4h](https://github.com/marcosd4h)
- **Source:** [marcosd4h/DeepExtractRuntime](https://github.com/marcosd4h/DeepExtractRuntime)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-marcosd4h-deepextractruntime-com-interface-reconstruction
- Seller: https://agentstack.voostack.com/s/marcosd4h
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.