{"id":23359,"library":"binary-refinery","title":"binary-refinery","description":"A toolkit to transform and refine (mostly) binary data. Current version 0.10.11, frequent releases. Provides a pipeline framework for unpacking, decoding, and transforming binary payloads, with built-in units for cryptography, compression, encoding, and more.","status":"active","version":"0.10.11","language":"python","source_language":"en","source_url":"https://github.com/binref/refinery/","tags":["binary","forensics","malware","reverse-engineering","triage"],"install":[{"cmd":"pip install binary-refinery","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Disassembly support for x86, x64, ARM, etc.","package":"capstone","optional":true},{"reason":"YARA pattern matching","package":"yara-python","optional":true}],"imports":[{"note":"The package installs as 'binary-refinery' but the module is 'refinery'. Common mistake.","wrong":"import binary_refinery","symbol":"refinery","correct":"import refinery"},{"note":"Top-level import of units works; deeper paths may not be importable directly.","wrong":"from refinery.units import ...","symbol":"refinery.units","correct":"from refinery import units"}],"quickstart":{"code":"import os\nimport json\nfrom refinery import units\n\n# Process a binary payload: base64 decode, decompress, and display hex\npayload = b'JVBERi0xLjQ...'  # truncated for example\nresult = payload | units.b64() | units.zlib() | units.hexview()\nprint(result)\n\n# Use a variable for conditional branching (requires 'refinery.lib')\nfrom refinery.lib import argformats\nprint(argformats),  # just to demonstrate import is available","lang":"python","description":"Basic pipeline: pipe binary data through refinery units using the | operator."},"warnings":[{"fix":"Update unit names: e.g., base64 -> b64, hex -> hex, etc. Check migration guide.","message":"In version 0.9.x, many unit names changed (e.g., 'base64' became 'b64'). Scripts from 0.8.x will break.","severity":"breaking","affected_versions":"<0.9.0"},{"fix":"Use 'data | unit.Class()' not 'data | unit.Class'.","message":"The pipeline operator | does not behave like shell pipes: units must be instantiated (with parentheses) even if no arguments needed.","severity":"gotcha","affected_versions":"all"},{"fix":"Use 'from refinery import units; units.aes()' instead of 'from refinery.units.crypto import aes'.","message":"Importing 'refinery' works, but many submodules (e.g., 'refinery.units.crypto') are not importable directly; always use 'from refinery import units' and access via 'units.xxx'.","severity":"gotcha","affected_versions":"all"},{"fix":"Replace 'malwares(...)' with specific units for memory extraction.","message":"The 'malwares' unit has been deprecated in favor of generic units like 'xtrmem' and 'xtrfile'.","severity":"deprecated","affected_versions":">=0.9.5"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"pip install binary-refinery; then use 'import refinery'.","cause":"Wrong import name; the Python package installs as 'binary-refinery' but the module is 'refinery'.","error":"ModuleNotFoundError: No module named 'binary_refinery'"},{"fix":"from refinery import units; units.b64()","cause":"Units are not available as attributes on the top-level module; must import 'units' submodule.","error":"AttributeError: module 'refinery' has no attribute 'b64'"},{"fix":"data | units.b64()  # with parentheses","cause":"Forgetting to instantiate a unit class (missing parentheses).","error":"TypeError: 'NoneType' object is not callable"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}