# punkholic/malware-lab architecture

> Architecture diagram of the GitHub repository punkholic/malware-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/punkholic/malware-lab
- Repository: https://github.com/punkholic/malware-lab

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External Actors / I/O
    %% =========================
    U["User / Operator"]:::actor

    subgraph "Host Environment"
        FS[(Filesystem)]:::storage

        subgraph "Input Artifacts"
            IN_USER["User-provided file (arbitrary path)"]:::input
            IN_SAMPLES_DIR["samples/ (fixtures)"]:::input
            IN_SAMPLE_BIN["samples/sample"]:::input
            IN_SAMPLE_C["sample.c"]:::input
        end

        subgraph "Outputs"
            OUT_STD["Stdout (console text)"]:::output
            OUT_REPORT["Analysis report (file/JSON/unknown)"]:::output
        end
    end

    %% =========================
    %% Python Tool Boundary
    %% =========================
    subgraph "Python Tool / Project Root (single-process)"
        DOC["README.md (usage / notes)"]:::doc

        subgraph "Interface / Invocation Layer"
            CLI_DIS["CLI Entry Point: disassembler.py"]:::cli
            CLI_DET["CLI Entry Point: file_detector.py"]:::cli
            ARGS["Args parsing (file path, options)"]:::internal
        end

        subgraph "Core Logic Layer"
            subgraph "file_detector.py (Format identification)"
                DET_READ["Header reader / magic matcher"]:::internal
                DET_CLASS["Format classifier (ELF/PE/etc.)"]:::internal
                DET_META["Metadata extractor (arch/endian/bitness)"]:::internal
            end

            subgraph "disassembler.py (Decode / disassemble engine)"
                DIS_DISPATCH["Select backend / rules (by format+arch)"]:::internal
                DIS_DECODE["Instruction decoder (linear sweep / CFG)"]:::internal
                DIS_FMT["Formatter (syntax / rendering)"]:::internal
                DIS_RENDER["Output renderer (stdout/file)"]:::internal
            end

            CONST["constant.py (shared constants/tables/enums)"]:::constants
        end

        subgraph "Data Objects (conceptual)"
            D_BYTES["ByteStream / FileBytes"]:::data
            D_FMT["FileFormat (enum)"]:::data
            D_ARCH["Arch/Endian/Bitness"]:::data
            D_RES["DisassemblyResult"]:::data
        end
    end

    %% =========================
    %% Primary Flow (vertical)
    %% =========================
    U -->|"invokes_tool"| CLI_DIS
    U -->|"invokes_tool"| CLI_DET

    CLI_DIS -->|"parses_args"| ARGS
    CLI_DET -->|"parses_args"| ARGS

    ARGS -->|"reads_input_path"| FS
    FS -->|"loads_bytes"| D_BYTES

    D_BYTES -->|"read_file_bytes"| DET_READ
    DET_READ -->|"match_magic/headers"| DET_CLASS
    DET_CLASS -->|"extract_metadata"| DET_META

    DET_META -->|"produce"| D_FMT
    DET_META -->|"produce"| D_ARCH

    D_FMT -->|"select_disassembly_strategy"| DIS_DISPATCH
    D_ARCH -->|"select_disassembly_strategy"| DIS_DISPATCH
    D_BYTES -->|"decode_from_bytes"| DIS_DECODE

    DIS_DISPATCH -->|"configure_decoder"| DIS_DECODE
    DIS_DECODE -->|"emit_instructions"| DIS_FMT
    DIS_FMT -->|"render_text/structure"| DIS_RENDER
    DIS_RENDER -->|"produce"| D_RES

    D_RES -->|"print_output"| OUT_STD
    D_RES -->|"write_report"| OUT_REPORT

    %% =========================
    %% Inputs (samples) feed filesystem
    %% =========================
    IN_USER -->|"stored_on"| FS
    IN_SAMPLES_DIR -->|"contains"| IN_SAMPLE_BIN
    IN_SAMPLE_BIN -->|"stored_on"| FS
    IN_SAMPLE_C -->|"stored_on"| FS

    %% =========================
    %% Shared Dependencies
    %% =========================
    DET_READ -->|"uses_magic_constants"| CONST
    DET_CLASS -->|"uses_format_definitions"| CONST
    DET_META -->|"uses_arch_enums"| CONST

    DIS_DISPATCH -->|"uses_tables/enums"| CONST
    DIS_DECODE -->|"uses_opcode_tables"| CONST
    DIS_FMT -->|"uses_format_constants"| CONST

    %% =========================
    %% Notes / Extensibility
    %% =========================
    EXT_DET["Extension point: add new formats in detector"]:::note
    EXT_DIS["Extension point: add new ISAs/decoders in disassembler"]:::note
    EXT_CONST["Extension point: expand constants/tables/enums"]:::note

    DET_CLASS -->|"extensible"| EXT_DET
    DIS_DISPATCH -->|"extensible"| EXT_DIS
    CONST -->|"extensible"| EXT_CONST

    %% =========================
    %% Click Events (mapped components)
    %% =========================
    click CLI_DIS "https://github.com/punkholic/malware-lab/blob/main/disassembler.py"
    click CLI_DET "https://github.com/punkholic/malware-lab/blob/main/file_detector.py"
    click CONST "https://github.com/punkholic/malware-lab/blob/main/constant.py"
    click IN_SAMPLE_C "https://github.com/punkholic/malware-lab/blob/main/sample.c"
    click IN_SAMPLES_DIR "https://github.com/punkholic/malware-lab/tree/main/samples/"
    click IN_SAMPLE_BIN "https://github.com/punkholic/malware-lab/tree/main/samples/sample"
    click DOC "https://github.com/punkholic/malware-lab/blob/main/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#FFE08A,stroke:#8A6D00,stroke-width:2px,color:#1f1f1f
    classDef cli fill:#8EC5FF,stroke:#1E5AA8,stroke-width:2px,color:#0b1b2b
    classDef internal fill:#D6EBFF,stroke:#2E6DA4,stroke-width:1.5px,color:#0b1b2b
    classDef constants fill:#CDB4FF,stroke:#5A3DAA,stroke-width:2px,color:#1b1033
    classDef storage fill:#B7F0D4,stroke:#1E7D4D,stroke-width:2px,color:#0b2b1a
    classDef input fill:#E8FFF3,stroke:#1E7D4D,stroke-width:1.5px,color:#0b2b1a
    classDef output fill:#E3F7E9,stroke:#1E7D4D,stroke-width:1.5px,color:#0b2b1a
    classDef data fill:#FFF3BF,stroke:#B38700,stroke-width:1.5px,color:#2b2100
    classDef doc fill:#F2F2F2,stroke:#666666,stroke-width:1.5px,color:#222222
    classDef note fill:#FFD6D6,stroke:#A33A3A,stroke-width:1.5px,color:#3a0f0f
```
