How punkholic/malware-lab works
Project type and purpose (from file tree + README)
This looks like a small Python-based binary/file analysis tool, likely a CLI-style utility or library that:
• Detects a file type/format (file_detector.py)
• Disassembles something about the detected file (or a supported format) (disassembler.py)
• Uses shared constants/definitions (constant.py)
• Includes sample inputs (sample.c, samples/)
What to treat as “the system”
At a minimum, model these as first-class components:
• User / Operator
• CLI / Runner / Entry point (even if there’s no main.py visible—assume one of the scripts is executed directly)
• File Detector module (file_detector.py)
• Disassembler module (disassembler.py)
• Constants / Definitions module (constant.py)
• Input artifacts (samples/*, sample.c, and “arbitrary user-provided file”)
• Outputs (stdout text, report file, JSON, etc.—unknown; represent as “Disassembly output / Analysis report”)
Even without reading the code, the most plausible pipeline is:
User provides an input file path
2. File Detector reads bytes/headers and classifies format (e.g., ELF/PE/Mach-O/raw/unknown)
3. Disassembler chooses a decoding strategy based on detected format/arch and produces disassembly
Output is emitted (console or file)
• “read file bytes”
• “detect format / architecture”
• “select disassembly backend / rules”
• “emit disassembly text”
That:
• file_detector.py and disassembler.py both likely depend on constant.py for magic values, opcode tables, enums, offsets, etc.
Architectural patterns / design principles to highlight
Given the module split, the project naturally suggests these principles:
• Separation of concerns:
• Detection is separate from disassembly
• Constants/configuration are centralized
• Pipeline architecture:
• A linear flow from input → classify → process → output
• New file formats in file_detector.py
• New instruction sets / architectures in disassembler.py
• Additional constants/tables in constant.py
“Don’t overthink it”: split into as many components as possible (for this repo)
file_detector.py subcomponents (conceptual)
• Header reader / magic-byte matcher
• Format classifier (ELF/PE/etc.)
• Metadata extractor (arch, entry point, sections) if present
disassembler.py subcomponents (conceptual)
• Instruction decoder
• Formatter (AT&T vs Intel, etc.)
• Control-flow or linear sweep driver
• Output renderer (stdout/file)
constant.py
• Magic numbers
• Opcode tables
• Enum definitions