# phntmzn/apple-script-malware-collection architecture

> Architecture diagram of the GitHub repository phntmzn/apple-script-malware-collection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phntmzn/apple-script-malware-collection
- Repository: https://github.com/phntmzn/apple-script-malware-collection

## Overview

##### Project Type and Purpose
- This is an **open-source archive** of AppleScript-based macOS malware samples.
- Purpose: provide a curated collection (Persistence, Infostealers, Keyloggers, Downloaders, Exploiters, Hybrids, Obfuscators, Binders) for **security research**, **education**, and **reverse engineering**.

##### Main Components
1. **GitHub Repository**
- Stores all `.scpt` sample files under the `2025/…` tree, plus `README.md` and `LICENSE.md`.
- Version control, contribution workflow, issue tracking.
2. **Sample Storage & Classification**
- Logical grouping of samples by behavior category (Persistence, Stealers, Keyloggers, etc.).
- Metadata index (file name, sample type, comments).
3. **Documentation Layer**
- `README.md` describes sample types, usage disclaimer, analysis environment recommendations.
- `LICENSE.md` (MIT) and ethical/usage notice.
4. **Analysis Environment (macOS Sandbox VM)**
- A dedicated virtual machine with network isolation.
- Hosts and executes samples safely.
5. **Analysis Tools**
- File-system & syscall tracers: `fs_usage`, `opensnoop`
- Network monitors: Little Snitch, Wireshark
- Signature & gatekeeper: `codesign`, `spctl`
- Binary/text analysis: `strings`, `xxd`, `lldb`/`gdb`
6. **Security Researchers / Analysts**
- Clone or fork the repo, select samples, run in sandbox, capture telemetry, document findings.

##### Relationships & Data Flows
- **Researchers** → clone/pull **GitHub Repo** (samples & docs)
- **Sample Storage** → feeds **Analysis Environment** (scripts are executed)
- **Analysis Environment** → feeds **Analysis Tools** (monitored processes, network, system calls)
- **Analysis Tools** → output logs & reports → consumed by **Researchers**
- **Researchers** → update **Documentation** or issue tracker with findings

##### Architectural Patterns & Principles
- **Content Repository Pattern**: static storage of artifacts with version control
- **Analytical Pipeline**: ingest (samples) → process (sandbox execution) → output (logs/reports)
- **Separation of Concerns**:
- Storage & classification (repo)
- Execution runtime (VM)
- Monitoring & logging (tools)
- User layer (analysts)
- **Modularity & Extensibility**: easy to add new categories or tooling recommendations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    Researchers["Security Researchers / Analysts"]:::user

    %% Repository Layer
    GitHubRepo["GitHub Repository"]:::repoStorage
    click GitHubRepo "https://github.com/phntmzn/apple-script-malware-collection/tree/main//"
    
    %% Sample Storage & Classification
    subgraph "Sample Storage & Classification" 
        direction TB
        StorageRoot["All .scpt Samples"]:::repoStorage
        click StorageRoot "https://github.com/phntmzn/apple-script-malware-collection/tree/main//2025/"
        Persistence["Persistence"]:::repoStorage
        Infostealers["Infostealers"]:::repoStorage
        Keyloggers["Keyloggers"]:::repoStorage
        Downloaders["Downloaders"]:::repoStorage
        Exploiters["Exploiters"]:::repoStorage
        Hybrids["Hybrids"]:::repoStorage
        Obfuscators["Obfuscators"]:::repoStorage
        Binders["Binders"]:::repoStorage
        MetadataIndex["Metadata Index"]:::repoStorage
        click MetadataIndex "https://github.com/phntmzn/apple-script-malware-collection/blob/main//2025/07252025/21412412.md"
        StorageRoot --> Persistence
        StorageRoot --> Infostealers
        StorageRoot --> Keyloggers
        StorageRoot --> Downloaders
        StorageRoot --> Exploiters
        StorageRoot --> Hybrids
        StorageRoot --> Obfuscators
        StorageRoot --> Binders
        StorageRoot --> MetadataIndex
    end

    %% Documentation Layer
    subgraph "Documentation Layer"
        direction TB
        README["README.md"]:::doc
        click README "https://github.com/phntmzn/apple-script-malware-collection/blob/main//README.md"
        LICENSE["LICENSE.md"]:::doc
        click LICENSE "https://github.com/phntmzn/apple-script-malware-collection/blob/main//LICENSE.md"
    end

    %% Compute / Sandbox
    SandboxVM["macOS Sandbox VM"]:::compute

    %% Analysis Tools
    subgraph "Analysis Tools"
        direction TB
        FSUsage["fs_usage"]:::tools
        OpenSnoop["opensnoop"]:::tools
        LittleSnitch["Little Snitch"]:::tools
        Wireshark["Wireshark"]:::tools
        CodeSign["codesign"]:::tools
        SPCTL["spctl"]:::tools
        Strings["strings"]:::tools
        XXD["xxd"]:::tools
        Debuggers["lldb / gdb"]:::tools
    end

    %% Logs & Reports
    Logs["Logs & Reports"]:::tools

    %% Workflows
    Researchers -->|"clone / pull"| GitHubRepo
    GitHubRepo -->|"contains samples"| StorageRoot
    GitHubRepo -->|"contains docs"| README
    GitHubRepo -->|"contains docs"| LICENSE
    StorageRoot -->|"feeds samples"| SandboxVM
    README -->|"guides setup"| SandboxVM
    SandboxVM -->|"monitored by"| FSUsage
    SandboxVM -->|"monitored by"| OpenSnoop
    SandboxVM -->|"monitored by"| LittleSnitch
    SandboxVM -->|"monitored by"| Wireshark
    SandboxVM -->|"uses"| CodeSign
    SandboxVM -->|"uses"| SPCTL
    SandboxVM -->|"analyzed by"| Strings
    SandboxVM -->|"analyzed by"| XXD
    SandboxVM -->|"debugged by"| Debuggers
    FSUsage --> Logs
    OpenSnoop --> Logs
    LittleSnitch --> Logs
    Wireshark --> Logs
    CodeSign --> Logs
    SPCTL --> Logs
    Strings --> Logs
    XXD --> Logs
    Debuggers --> Logs
    Logs -->|"reports to"| Researchers
    Researchers -->|"update findings"| README
    Researchers -->|"update findings"| LICENSE

    %% Legend as note
    subgraph Legend
        direction TB
        A["Repository / Storage"]:::repoStorage
        B["Compute / Sandbox"]:::compute
        C["Monitoring / Tools"]:::tools
        D["User"]:::user
        E["Documentation"]:::doc
    end

    %% Styles
    classDef repoStorage fill:#cfe2ff,stroke:#0366d6,color:#0366d6;
    classDef compute fill:#d1e7dd,stroke:#116530,color:#116530;
    classDef tools fill:#fff3cd,stroke:#ffcc00,color:#665200;
    classDef user fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef doc fill:#f8d7da,stroke:#d63384,color:#d63384;
```
