Com Interface Reconstruction

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:

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:

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.

scancominterfaces.py -- Discover All COM Interfaces (Start Here)

Scan a module for all COM-related structures:

# 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.

decodewrltemplates.py -- Decode WRL Template Instantiations

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

# 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.

mapclassinterfaces.py -- Map Interfaces to Classes

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

# 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:

# 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:

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:

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

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

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

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:

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 [dataformatreference.md](../../docs/dataformatreference.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
• Source: marcosd4h/DeepExtractRuntime
• License: MIT

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