# mohammadi-ali/metamorphasm architecture

> Architecture diagram of the GitHub repository mohammadi-ali/metamorphasm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohammadi-ali/metamorphasm
- Repository: https://github.com/mohammadi-ali/metamorphasm

## Overview

This repository is an offline research benchmark pipeline, not an application service. Its architecture centers on one shared dataset-generation subsystem and several model-specific experiment subsystems that all consume the same benchmark artifacts.

1. **Top-level purpose**
   - The repo evaluates whether LLMs can generate obfuscated assembly code.
   - The core output is the **MetamorphASM Dataset (MAD)** plus experiments across multiple model families.

2. **Dataset creation subsystem**
   - `MetamorphASM_dataset_creation/` is the data-engineering boundary of the project.
   - It contains scripts for transforming assembly into obfuscated variants, including:
     - `dead_code_Insertion.py`
     - `register_substitution.py`
     - `control_flow.py`
     - `shuffle.py`
     - `Obfuscation.py`
     - `Assembly_separation.py`
     - `Code_Linearization.py`
     - `make_dataset.py`
   - This layer is responsible for taking source assembly material and producing benchmark-ready examples.

3. **Benchmark outputs**
   - The dataset folder includes CSVs under `Data(200 Samples)/` for the three main obfuscation types:
     - `dead_code_dataset.csv`
     - `register_substitution_dataset.csv`
     - `control_flow_change_dataset.csv`
   - There is also a `mini_dataset.zip` and several path/config artifacts, indicating prepared subsets and intermediate outputs.

4. **Obfuscation task decomposition**
   - The benchmark is organized around three transformation targets:
     - dead code insertion
     - register substitution
     - control-flow change
   - These are the main semantic boundaries that the evaluation code and prompts are built around.

5. **Prompt and few-shot resources**
   - `few_shots/` stores shared few-shot CSV examples used for prompting.
   - Some model-specific folders also include their own few-shot files, suggesting prompt templates are adapted per model family and per task.

6. **Model experiment layer: notebook-driven workflows**
   - `CodeT5/` and `GPT3.5_4/` are notebook-centric experiment folders.
   - These contain Jupyter notebooks that appear to run generation, transformation, and analysis experiments interactively rather than through a single CLI pipeline.

7. **Model experiment layer: script-driven workflows**
   - `Starcoder2-7b/`, `Codegemma_Codellama/`, and `Llama_3.1/` use Python scripts for task execution.
   - These folders likely wrap prompting, model invocation, and result collection in a more automated batch style than the notebook-based folders.

8. **Per-model isolation**
   - Each model family has its own execution boundary and dependencies:
     - `Starcoder2-7b/` includes `DeadCode.py`, `Transpose.py`, `substitution.py`, and `score.py`
     - `Codegemma_Codellama/` includes `core.py`, `process_tasks.py`, `task_prompts.py`, and `setup.py`
     - `Llama_3.1/` includes `Llama_Experiment.py`
   - This indicates the repo is structured as multiple adapters over a shared benchmark, not one shared runtime.

9. **Scoring and evaluation**
   - `Starcoder2-7b/score.py` suggests automated scoring/assessment of generated outputs.
   - The README also mentions information-theoretic metrics and manual human review, so evaluation is split between automated metrics and qualitative validation.

10. **Model/runtime dependencies**
   - `requirements.txt` appears in multiple experiment folders, indicating separate environment requirements per model stack.
   - `Codegemma_Codellama/setup.py` and `deadcode_package.sh` suggest packaging and local execution support for that model family.

11. **Data flow across the repo**
   - The intended flow is:
     - raw assembly data → dataset creation scripts → obfuscated benchmark CSVs → prompt/few-shot inputs → model-specific experiment scripts/notebooks → generated outputs → scoring/manual review.
   - The central reusable asset is the dataset; the model folders are consumers of that asset.

12. **What to draw in an architecture diagram**
   - Draw one shared **Dataset Generation** block feeding multiple **Model Experiment** blocks.
   - Show the **few_shots** resources as an input to the prompting layer.
   - Show **Evaluation/Scoring** as a downstream stage that consumes model outputs.
   - Keep model folders separate, because each one has its own runner and dependency boundary.

13. **Scope note**
   - Despite the README mentioning more model families, the visible repo content mainly exposes experiment paths for GPT, CodeT5, Starcoder2, CodeGemma/CodeLlama, and LLaMA 3.1, plus the dataset-construction pipeline.

Main entry points: [`MetamorphASM_dataset_creation/Data(200 Samples)`](https://github.com/mohammadi-ali/metamorphasm/tree/HEAD/MetamorphASM_dataset_creation/Data(200%20Samples)) (Benchmark CSVs), [`few_shots`](https://github.com/mohammadi-ali/metamorphasm/tree/main/few_shots) (Few-shot pool), [`MetamorphASM_dataset_creation/Obfuscation.py`](https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/Obfuscation.py) (Obfuscation ops), [`MetamorphASM_dataset_creation/make_dataset.py`](https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/make_dataset.py) (Dataset pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Dataset generation"]
  node_n2["Dataset pipeline<br/>data pipeline<br/>[make_dataset.py]"]
  node_n3["Obfuscation ops<br/>transform layer<br/>[Obfuscation.py]"]
  node_n4["Assembly prep<br/>preprocessing"]
  node_n5["Dead code<br/>transformation"]
  node_n6["Register swap<br/>transformation"]
  node_n7["Control flow<br/>transformation<br/>[control_flow.py]"]
  node_n8[("Benchmark CSVs<br/>dataset outputs")]
end

subgraph group_g2["Shared inputs"]
  node_n9["Few-shot pool<br/>prompt data"]
  node_n10["Llama shots<br/>prompt data"]
end

subgraph group_g3["Notebook experiments"]
  node_n11["CodeT5 notebooks<br/>interactive experiments"]
  node_n12["GPT-4 notebooks<br/>interactive experiments"]
  node_n18["GPT-3.5/GPT-4 notes<br/>documentation<br/>[README.md]"]
end

subgraph group_g4["Script experiments"]
  node_n13["StarCoder runner<br/>script adapter<br/>[DeadCode.py]"]
  node_n14["StarCoder scoring<br/>evaluation<br/>[score.py]"]
  node_n15["CodeGemma adapter<br/>script adapter<br/>[core.py]"]
  node_n16["Task prompts<br/>prompt builder<br/>[task_prompts.py]"]
  node_n17["LLaMA experiment<br/>script adapter"]
end

node_n1["Repository<br/>overview<br/>[README.md]"]

node_n1 -->|"hosts"| node_n2
node_n2 -->|"prepares"| node_n4
node_n4 -->|"feeds"| node_n3
node_n3 -->|"includes"| node_n5
node_n3 -->|"includes"| node_n6
node_n3 -->|"includes"| node_n7
node_n2 -->|"produces"| node_n8
node_n8 -->|"supports"| node_n9
node_n9 -->|"consumed by"| node_n11
node_n9 -->|"consumed by"| node_n12
node_n9 -->|"consumed by"| node_n13
node_n9 -->|"consumed by"| node_n15
node_n9 -->|"consumed by"| node_n17
node_n8 -->|"evaluates"| node_n11
node_n8 -->|"evaluates"| node_n13
node_n8 -->|"evaluates"| node_n15
node_n8 -->|"evaluates"| node_n17
node_n13 -->|"scores"| node_n14
node_n15 -->|"builds"| node_n16
node_n12 -->|"documents"| node_n18

click node_n1 "https://github.com/mohammadi-ali/metamorphasm/blob/main/README.md"
click node_n2 "https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/make_dataset.py"
click node_n3 "https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/Obfuscation.py"
click node_n5 "https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/dead_code_Insertion.py"
click node_n6 "https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/register_substitution.py"
click node_n7 "https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/control_flow.py"
click node_n8 "https://github.com/mohammadi-ali/metamorphasm/tree/main/MetamorphASM_dataset_creation/Data(200 Samples)"
click node_n9 "https://github.com/mohammadi-ali/metamorphasm/tree/main/few_shots"
click node_n10 "https://github.com/mohammadi-ali/metamorphasm/blob/main/Llama_3.1/Few_shot_dead_code.csv"
click node_n11 "https://github.com/mohammadi-ali/metamorphasm/tree/main/CodeT5"
click node_n12 "https://github.com/mohammadi-ali/metamorphasm/blob/main/GPT3.5_4/Metamorphis_GPT3_5_and_GPT4.ipynb"
click node_n13 "https://github.com/mohammadi-ali/metamorphasm/blob/main/starcoder2-7b/DeadCode.py"
click node_n14 "https://github.com/mohammadi-ali/metamorphasm/blob/main/starcoder2-7b/score.py"
click node_n15 "https://github.com/mohammadi-ali/metamorphasm/blob/main/Codegemma_Codellama/core.py"
click node_n16 "https://github.com/mohammadi-ali/metamorphasm/blob/main/Codegemma_Codellama/task_prompts.py"
click node_n17 "https://github.com/mohammadi-ali/metamorphasm/blob/main/Llama_3.1/Llama_Experiment.py"
click node_n18 "https://github.com/mohammadi-ali/metamorphasm/blob/main/GPT3.5_4/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n2,node_n3,node_n4,node_n5,node_n6,node_n7,node_n8 toneBlue
class node_n9,node_n10 toneAmber
class node_n11,node_n12,node_n18 toneMint
class node_n13,node_n14,node_n15,node_n16,node_n17 toneRose
class node_n1 toneNeutral
```

## Components

### Dataset generation

Transforms raw assembly material into benchmark-ready obfuscated datasets.

- [Dataset pipeline](https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/make_dataset.py): data pipeline · Shared assembly-to-benchmark generation flow. · `MetamorphASM_dataset_creation/make_dataset.py`
- [Obfuscation ops](https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/Obfuscation.py): transform layer · Core obfuscation transformations for the benchmark tasks. · `MetamorphASM_dataset_creation/Obfuscation.py`
- **Assembly prep**: preprocessing · Assembly splitting and linearization before obfuscation.
- [Dead code](https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/dead_code_Insertion.py): transformation · Dead-code insertion task implementation. · `MetamorphASM_dataset_creation/dead_code_Insertion.py`
- [Register swap](https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/register_substitution.py): transformation · Register substitution task implementation. · `MetamorphASM_dataset_creation/register_substitution.py`
- [Control flow](https://github.com/mohammadi-ali/metamorphasm/blob/main/MetamorphASM_dataset_creation/control_flow.py): transformation · Control-flow change task implementation. · `MetamorphASM_dataset_creation/control_flow.py`
- [Benchmark CSVs](https://github.com/mohammadi-ali/metamorphasm/tree/HEAD/MetamorphASM_dataset_creation/Data(200%20Samples)): dataset outputs · Prepared datasets for the three main obfuscation targets. · `MetamorphASM_dataset_creation/Data(200 Samples)`

### Shared inputs

Reusable prompt and few-shot resources consumed by multiple experiments.

- [Few-shot pool](https://github.com/mohammadi-ali/metamorphasm/tree/main/few_shots): prompt data · Shared few-shot examples used across model families. · `few_shots`
- [Llama shots](https://github.com/mohammadi-ali/metamorphasm/blob/main/Llama_3.1/Few_shot_dead_code.csv): prompt data · Model-specific few-shot files for LLaMA experiments. · `Llama_3.1/Few_shot_dead_code.csv`

### Notebook experiments

Interactive model workflows run through Jupyter notebooks.

- [CodeT5 notebooks](https://github.com/mohammadi-ali/metamorphasm/tree/main/CodeT5): interactive experiments · Notebook-based experiments for CodeT5 generation and analysis. · `CodeT5`
- [GPT-4 notebooks](https://github.com/mohammadi-ali/metamorphasm/blob/main/GPT3.5_4/Metamorphis_GPT3_5_and_GPT4.ipynb): interactive experiments · Notebook-driven MetamorphASM experiments for GPT-3.5/GPT-4. · `GPT3.5_4/Metamorphis_GPT3_5_and_GPT4.ipynb`
- [GPT-3.5/GPT-4 notes](https://github.com/mohammadi-ali/metamorphasm/blob/main/GPT3.5_4/README.md): documentation · Experiment README and setup notes for the GPT workflow. · `GPT3.5_4/README.md`

### Script experiments

Automated model adapters, runners, and scoring scripts.

- [StarCoder runner](https://github.com/mohammadi-ali/metamorphasm/blob/main/starcoder2-7b/DeadCode.py): script adapter · Scripted task execution for StarCoder2-7b. · `starcoder2-7b/DeadCode.py`
- [StarCoder scoring](https://github.com/mohammadi-ali/metamorphasm/blob/main/starcoder2-7b/score.py): evaluation · Automated scoring for generated outputs. · `starcoder2-7b/score.py`
- [CodeGemma adapter](https://github.com/mohammadi-ali/metamorphasm/blob/main/Codegemma_Codellama/core.py): script adapter · Batch prompting and task processing for CodeGemma/CodeLlama. · `Codegemma_Codellama/core.py`
- [Task prompts](https://github.com/mohammadi-ali/metamorphasm/blob/main/Codegemma_Codellama/task_prompts.py): prompt builder · Task-specific prompt definitions for the CodeGemma/CodeLlama workflow. · `Codegemma_Codellama/task_prompts.py`
- [LLaMA experiment](https://github.com/mohammadi-ali/metamorphasm/blob/main/Llama_3.1/Llama_Experiment.py): script adapter · Scripted experiment runner for LLaMA 3.1. · `Llama_3.1/Llama_Experiment.py`

### Other components

- [Repository](https://github.com/mohammadi-ali/metamorphasm/blob/main/README.md): overview · MetamorphASM benchmark and model evaluation workspace. · `README.md`

## Connections

- Repository → Dataset pipeline: hosts · Repository centers on the shared dataset-generation subsystem.
- Dataset pipeline → Assembly prep: prepares · Raw assembly is separated and linearized before transformation.
- Assembly prep → Obfuscation ops: feeds · Preprocessed assembly enters the obfuscation layer.
- Obfuscation ops → Dead code: includes · Dead-code insertion is one of the core benchmark transformations.
- Obfuscation ops → Register swap: includes · Register substitution is one of the core benchmark transformations.
- Obfuscation ops → Control flow: includes · Control-flow change is one of the core benchmark transformations.
- Dataset pipeline → Benchmark CSVs: produces · Dataset scripts emit benchmark-ready CSV artifacts.
- Benchmark CSVs → Few-shot pool: supports · Shared few-shot examples are used to prompt experiments.
- Few-shot pool → CodeT5 notebooks: consumed by · CodeT5 notebooks reuse shared prompt resources.
- Few-shot pool → GPT-4 notebooks: consumed by · GPT-3.5/GPT-4 notebooks reuse shared prompt resources.
- Few-shot pool → StarCoder runner: consumed by · StarCoder scripts use shared few-shot examples.
- Few-shot pool → CodeGemma adapter: consumed by · CodeGemma/CodeLlama adapters use shared few-shot examples.
- Few-shot pool → LLaMA experiment: consumed by · LLaMA experiments use shared few-shot examples.
- Benchmark CSVs → CodeT5 notebooks: evaluates · Notebook experiments consume the benchmark CSVs.
- Benchmark CSVs → StarCoder runner: evaluates · Scripted model adapters consume the benchmark CSVs.
- Benchmark CSVs → CodeGemma adapter: evaluates · Scripted model adapters consume the benchmark CSVs.
- Benchmark CSVs → LLaMA experiment: evaluates · Scripted model adapters consume the benchmark CSVs.
- StarCoder runner → StarCoder scoring: scores · Generated outputs are assessed by the StarCoder scoring stage.
- CodeGemma adapter → Task prompts: builds · Prompt templates are assembled inside the CodeGemma workflow.
- GPT-4 notebooks → GPT-3.5/GPT-4 notes: documents · README captures the GPT experiment setup and usage.
