Registry / data / maco-extractor

maco-extractor

JSON →
library1.3.1pypypi✓ verified 85d ago

Maco Extractor is a Python package providing the essential framework for creating and running malware configuration extractors. It aims to standardize the output (using the Maco Model) and provide a consistent way to identify and execute parsers. The library is actively maintained, with frequent releases addressing compatibility, bug fixes, and new features.

pip install maco-extractor
INSTALL
IMPORT
SIG · MACO-EXTRACTOR
M
maco-extractor
datapythonv1.3.1
Install
3.6s avg
Import
602ms
Disk
58MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.6s · import 0.482s · 60MB
58MB installed
● package 58MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ExtractorModel
from maco.model import ExtractorModel
Extractor
from maco.extractor import Extractor
run_extractor
from maco.collector import run_extractor

This quickstart demonstrates how to define a custom Maco extractor, process a sample file with it, and retrieve the extracted `ExtractorModel` results.

import os from maco.model import ExtractorModel from maco.extractor import Extractor from maco.collector import run_extractor # Define a simple Maco Extractor class MySimpleExtractor(Extractor): # Yara rules can be defined here as a bytes object # rules = b'rule my_rule { strings: $a = "test_data" condition: $a }' def run(self, sample: bytes, **kwargs) -> ExtractorModel: # Example: if a specific string is found, set a property in the model if b"hello maco" in sample: model = ExtractorModel(family="GreetingMalware") model.add_tag("found_greeting") model.add_string(value="hello maco", context="sample_content") return model # All extractors must return an ExtractorModel, even if no config is found return ExtractorModel(family="Unknown") # Create a dummy file for the extractor to process sample_content = b"This is some test_data with hello maco inside." sample_path = "test_sample.bin" with open(sample_path, "wb") as f: f.write(sample_content) try: # Run the extractor against the sample file # 'extractors' expects a list of Extractor classes results = run_extractor(extractors=[MySimpleExtractor], sample_path=sample_path) # Print the results print(f"Extractor results for {sample_path}:") for result in results: print(f" Family: {result.family}") print(f" Tags: {result.tags}") print(f" Strings: {[s.value for s in result.strings]}") except Exception as e: print(f"An error occurred: {e}") finally: # Clean up the dummy file if os.path.exists(sample_path): os.remove(sample_path)
maco-extractor --version
Debug
Known issues
breakingThe `import_extractors` utility had backwards compatibility issues prior to `v1.2.23`. If you are using custom extractor loading mechanisms or older versions, ensure compatibility.
fix
Upgrade to `maco-extractor` v1.2.23 or newer to resolve `import_extractors` compatibility issues.
affects: <1.2.23
gotchaWhen running extractors on Python 3.8/3.9 with versions prior to `v1.2.25`, there might have been issues related to mutable default arguments in `model.py` that were fixed using `default_factory`. This could lead to unexpected behavior if not handled correctly in older versions.
fix
Ensure you are using `maco-extractor` v1.2.25 or newer for full Python 3.8/3.9 compatibility with the `ExtractorModel`.
affects: <1.2.25
gotchaAn `UnboundLocalError` could occur in `run_extractor` when YARA was explicitly disabled in versions prior to `v1.2.22`. This can cause crashes during runtime if YARA rule processing is not intended or configured.
fix
Upgrade to `maco-extractor` v1.2.22 or newer to prevent `UnboundLocalError` when YARA is disabled.
affects: <1.2.22
gotchaThe project introduced a separate `maco-model` package in `v1.2.18` containing only the model definition. If you only need the data model, install `maco-model`. If you intend to write and run extractors, install `maco-extractor` which includes the full framework.
fix
Choose the correct package for your needs: `pip install maco-model` for just the data model, or `pip install maco-extractor` for the full framework including extractor runtime.
affects: >=1.2.18
gotchaWhen writing YARA rules for extractors, the YARA rule names must be prefixed with the extractor class name to ensure proper association and triggering. Failing to do so may result in rules not being recognized or applied correctly.
fix
Prefix all YARA rule names within an extractor with the corresponding extractor class name (e.g., `rule MyExtractor_my_rule { ... }`).
affects: All versions
gotchaAs of `v1.2.24`, `maco-extractor` now explicitly shows `yara-x` warnings from rules within extractors. While this provides more diagnostic information, it can lead to increased output if your YARA rules have warnings. Review your YARA rules to eliminate unnecessary warnings.
fix
Be aware of potential increased verbosity. Address warnings in your `yara-x` rules to maintain clean output.
affects: >=1.2.24
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'maco'
The `maco-extractor` package, or its main `maco` module, is not installed or not accessible in the current Python environment.
fix
Install the library using pip: `pip install maco-extractor`
AttributeError: module 'maco' has no attribute 'Extractor'
This typically occurs when a user has installed the `maco-model` package (which only provides the data model) but is attempting to access components like `Extractor` or `Collector` that are part of the full `maco-extractor` framework.
fix
If you need the full framework, uninstall `maco-model` if it's installed, then install the complete `maco-extractor` package: `pip uninstall maco-model && pip install maco-extractor`
maco: command not found
The `maco` command-line interface (CLI) tool, which is installed with `maco-extractor`, is not in your system's PATH, or the Python environment where it was installed is not currently active.
fix
Activate the Python environment where `maco-extractor` is installed, or run the CLI tool explicitly using `python -m maco.cli`.
Upgrade
Version history
1.3.1latest on PyPI · released Jun 10, 2026
Audit
Dependencies
yara-xrequiredCore component for defining and processing YARA rules within extractors.
Agent activity
9 hits · last 30 days
node
6
Amazon
1
Resources
maco-extractor — pip install maco-extractor · libregistry