{"id":6712,"library":"maco-extractor","title":"Maco Extractor","description":"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.","status":"active","version":"1.2.25","language":"en","source_language":"en","source_url":"https://github.com/CybercentreCanada/Maco","tags":["malware analysis","threat intelligence","extractor","YARA"],"install":[{"cmd":"pip install maco-extractor","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core component for defining and processing YARA rules within extractors.","package":"yara-x"}],"imports":[{"symbol":"ExtractorModel","correct":"from maco.model import ExtractorModel"},{"symbol":"Extractor","correct":"from maco.extractor import Extractor"},{"symbol":"run_extractor","correct":"from maco.collector import run_extractor"}],"quickstart":{"code":"import os\nfrom maco.model import ExtractorModel\nfrom maco.extractor import Extractor\nfrom maco.collector import run_extractor\n\n# Define a simple Maco Extractor\nclass MySimpleExtractor(Extractor):\n    # Yara rules can be defined here as a bytes object\n    # rules = b'rule my_rule { strings: $a = \"test_data\" condition: $a }'\n    \n    def run(self, sample: bytes, **kwargs) -> ExtractorModel:\n        # Example: if a specific string is found, set a property in the model\n        if b\"hello maco\" in sample:\n            model = ExtractorModel(family=\"GreetingMalware\")\n            model.add_tag(\"found_greeting\")\n            model.add_string(value=\"hello maco\", context=\"sample_content\")\n            return model\n        # All extractors must return an ExtractorModel, even if no config is found\n        return ExtractorModel(family=\"Unknown\")\n\n# Create a dummy file for the extractor to process\nsample_content = b\"This is some test_data with hello maco inside.\"\nsample_path = \"test_sample.bin\"\nwith open(sample_path, \"wb\") as f:\n    f.write(sample_content)\n\ntry:\n    # Run the extractor against the sample file\n    # 'extractors' expects a list of Extractor classes\n    results = run_extractor(extractors=[MySimpleExtractor], sample_path=sample_path)\n\n    # Print the results\n    print(f\"Extractor results for {sample_path}:\")\n    for result in results:\n        print(f\"  Family: {result.family}\")\n        print(f\"  Tags: {result.tags}\")\n        print(f\"  Strings: {[s.value for s in result.strings]}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(sample_path):\n        os.remove(sample_path)","lang":"python","description":"This quickstart demonstrates how to define a custom Maco extractor, process a sample file with it, and retrieve the extracted `ExtractorModel` results."},"warnings":[{"fix":"Upgrade to `maco-extractor` v1.2.23 or newer to resolve `import_extractors` compatibility issues.","message":"The `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.","severity":"breaking","affected_versions":"<1.2.23"},{"fix":"Ensure you are using `maco-extractor` v1.2.25 or newer for full Python 3.8/3.9 compatibility with the `ExtractorModel`.","message":"When 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.","severity":"gotcha","affected_versions":"<1.2.25"},{"fix":"Upgrade to `maco-extractor` v1.2.22 or newer to prevent `UnboundLocalError` when YARA is disabled.","message":"An `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.","severity":"gotcha","affected_versions":"<1.2.22"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.2.18"},{"fix":"Prefix all YARA rule names within an extractor with the corresponding extractor class name (e.g., `rule MyExtractor_my_rule { ... }`).","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of potential increased verbosity. Address warnings in your `yara-x` rules to maintain clean output.","message":"As 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.","severity":"gotcha","affected_versions":">=1.2.24"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}