# How to Integrate External Configuration Extraction Frameworks with CAPEv2: A Complete Guide

> Learn how to integrate external config extraction frameworks like RATDecoders and MalDuck with CAPEv2. Discover CAPEv2's pluggable architecture for automated malware config extraction.

- Repository: [Kevin O'Reilly/capev2](https://github.com/kevoreilly/capev2)
- Tags: how-to-guide
- Published: 2026-03-05

---

**CAPEv2 integrates external configuration extraction frameworks like RATDecoders and MalDuck by dynamically loading parser modules from designated directories during the processing phase, enabling automatic malware config extraction through a pluggable architecture defined in [`lib/cuckoo/common/load_extra_modules.py`](https://github.com/kevoreilly/capev2/blob/main/lib/cuckoo/common/load_extra_modules.py) and [`cape_utils.py`](https://github.com/kevoreilly/capev2/blob/main/cape_utils.py).**

CAPEv2 supports seamless integration with third-party malware configuration extraction frameworks to enhance its static analysis capabilities. By leveraging a modular parser loading system, security analysts can integrate **RATDecoders**, **MalDuck**, **DC3-MWCP**, or **MaCo** directly into the sandbox processing pipeline. This guide explains how to configure and extend CAPEv2 to automatically extract command-and-control (C2) configurations and other malware indicators using these external tools.

## Installation Requirements

Before enabling external parsers in CAPEv2, install the desired framework using `pip` within your CAPEv2 virtual environment. The frameworks must be accessible as Python packages to ensure the dynamic loader can import their modules correctly.

Install RATDecoders directly from the repository:

```bash
poetry run pip install git+https://github.com/kevthehermit/RATDecoders

```

For MalDuck, use the CERT-Polska repository:

```bash
poetry run pip install git+https://github.com/CERT-Polska/malduck

```

After installation, clone or copy the framework's parser modules into the CAPEv2 `modules/processing/parsers/` directory structure. Each framework requires its own subdirectory containing valid Python packages with an `extract_config(data)` entry point.

## Configuring processing.conf

Enable external frameworks in the CAPEv2 configuration file located at `conf/default/processing.conf.default` (lines 294-316). Create a dedicated section for each framework with the `enabled` flag and `modules_path` pointing to the parser directory.

Add the following configuration for RATDecoders:

```ini
[ratdecoders]
enabled = true
modules_path = modules/processing/parsers/RATDecoders/

# Optional: path to a custom YARA file that selects the samples

yara_path = modules/processing/parsers/RATDecoders/ratdecoders.yar

```

For MalDuck, the configuration follows an identical pattern, specifying the path to the MalDuck parser modules. CAPEv2 reads these settings at startup to determine which extraction frameworks to initialize during the analysis processing phase.

## How CAPEv2 Loads External Parsers

The dynamic module loading mechanism resides in [`lib/cuckoo/common/load_extra_modules.py`](https://github.com/kevoreilly/capev2/blob/main/lib/cuckoo/common/load_extra_modules.py). This utility walks the specified parser directories using `pkgutil.walk_packages` and imports every Python file as a module under the `modules.processing.parsers.<Framework>` namespace.

For RATDecoders, the loader function (lines 40-45) performs the following operations:

```python

# lib/cuckoo/common/load_extra_modules.py

def ratdecoders_load_modules(CUCKOO_ROOT: str):
    parser_dir = os.path.join(CUCKOO_ROOT,
                              "modules", "processing", "parsers", "RATDecoders")
    rat_modules = {}
    for loader, mod_name, _ in pkgutil.walk_packages(
            [parser_dir], "modules.processing.parsers.RATDecoders."):
        try:
            rat_modules[mod_name] = importlib.import_module(mod_name)
        except Exception as e:
            log.error("ratdecoder parser: %s – %s", mod_name, e)
    return rat_modules

```

The MalDuck loader (lines 118-143) follows a similar pattern but returns specialized `ExtractorModules` objects that integrate with CAPEv2's YARA matching system. Both loaders execute during startup when [`cape_utils.py`](https://github.com/kevoreilly/capev2/blob/main/cape_utils.py) (lines 70-84) checks the configuration and initializes manager objects for enabled frameworks.

## The Extraction Pipeline

Once loaded, external parsers execute during the `process_extraction` phase in [`lib/cuckoo/common/cape_utils.py`](https://github.com/kevoreilly/capev2/blob/main/lib/cuckoo/common/cape_utils.py). This function iterates over loaded parser collections and invokes each module's `extract_config(file_bytes)` method on samples matching the framework's YARA signatures.

The extraction workflow proceeds as follows:

1. **YARA Matching** – CAPEv2 applies framework-specific YARA rules to submitted samples, filtering which files pass to each extractor.
2. **Config Extraction** – Valid samples trigger calls to `extract_config(data)`, returning dictionaries of extracted key-value pairs.
3. **Report Integration** – Results merge into the analysis JSON under framework-specific keys like `ratdecoders` or `malduck`.

The core extraction logic appears in [`cape_utils.py`](https://github.com/kevoreilly/capev2/blob/main/cape_utils.py):

```python

# lib/cuckoo/common/cape_utils.py

if process_cfg.ratdecoders.enabled:
    rat_modules = load_extra_modules.ratdecoders_load_modules(CUCKOO_ROOT)
    for name, mod in rat_modules.items():
        cfg = mod.extract_config(file_bytes)
        if cfg:
            report["ratdecoders"][name] = cfg

```

## Displaying Results in the Web UI

Extracted configurations surface in the CAPEv2 web interface through the Django template [`web/templates/analysis/static.html`](https://github.com/kevoreilly/capev2/blob/main/web/templates/analysis/static.html). The template renders framework-specific JSON data when present in the analysis report.

Access extracted data using the framework key defined during processing:

```django
{% if report.ratdecoders %}
  <h4>RATDecoders extraction</h4>
  <pre>{{ report.ratdecoders|json_script:"ratdecoders-data" }}</pre>
{% endif %}

```

The web UI automatically displays configurations for any enabled framework following this pattern, requiring no additional template modifications when adding new parsers that follow the standard output format.

## Summary

- **Install frameworks** using `pip install git+https://...` before enabling them in CAPEv2.
- **Configure [`processing.conf`](https://github.com/kevoreilly/capev2/blob/main/processing.conf)** to set `enabled = true` and specify the `modules_path` for each external parser.
- **Dynamic loading** occurs in [`load_extra_modules.py`](https://github.com/kevoreilly/capev2/blob/main/load_extra_modules.py), which walks parser directories and imports modules with `pkgutil.walk_packages`.
- **Extraction execution** happens in `cape_utils.process_extraction()`, calling `extract_config(data)` on matching samples.
- **Web display** uses the analysis report keys (e.g., `report.ratdecoders`) rendered in [`web/templates/analysis/static.html`](https://github.com/kevoreilly/capev2/blob/main/web/templates/analysis/static.html).

## Frequently Asked Questions

### What is the required entry point function for external parser modules?

External configuration extraction frameworks must implement `def extract_config(data):` as their primary entry point. This function receives the binary file bytes as input and returns a dictionary containing the extracted configuration keys and values. CAPEv2's `process_extraction` function in [`lib/cuckoo/common/cape_utils.py`](https://github.com/kevoreilly/capev2/blob/main/lib/cuckoo/common/cape_utils.py) calls this method for every loaded parser module when processing matching samples.

### How does CAPEv2 determine which samples to send to external parsers?

CAPEv2 uses YARA rule matching to filter samples before extraction. Each external framework can specify a `yara_path` in [`processing.conf`](https://github.com/kevoreilly/capev2/blob/main/processing.conf) pointing to a YARA rule file. The system applies these rules to submitted samples, and only files matching the signatures are passed to the corresponding `extract_config` functions. This prevents unnecessary processing of incompatible file types.

### Can I integrate custom or proprietary configuration extractors with CAPEv2?

Yes. Any Python package implementing the `extract_config(data)` interface can integrate with CAPEv2. Create a directory under `modules/processing/parsers/`, add your modules with the required entry point, and add a configuration section to [`processing.conf`](https://github.com/kevoreilly/capev2/blob/main/processing.conf) with `enabled = true` and the appropriate `modules_path`. The dynamic loader in [`load_extra_modules.py`](https://github.com/kevoreilly/capev2/blob/main/load_extra_modules.py) will automatically discover and import your modules at startup.

### Where are extracted configurations stored in the final analysis report?

Extracted configurations appear as top-level keys in the analysis JSON report, named according to the framework identifier (e.g., `ratdecoders`, `malduck`). These keys contain nested dictionaries mapping module names to their extracted configuration data. The web UI accesses these values through the report object (e.g., `report.ratdecoders`) and renders them in the Static Analysis tab.