# mandiant/flare-vm architecture

> Architecture diagram of the GitHub repository mandiant/flare-vm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mandiant/flare-vm
- Repository: https://github.com/mandiant/flare-vm

## Overview

##### Project type and purpose
- FLARE-VM is an open-source, script-driven provisioning tool whose sole purpose is to automate the build and configuration of a Windows-based reverse-engineering VM. It uses PowerShell scripts (install.ps1), a configuration XML (config.xml), Chocolatey, Boxstarter, and a set of VirtualBox-specific Python scripts to produce repeatable VM images.

##### File structure
- Top-level:
- install.ps1 – main PowerShell installer
- config.xml – default list of packages & environment settings
- LayoutModification.xml – default taskbar layout
- scripts/lint.ps1 – code quality checks
- virtualbox/… – Python scripts & YAML configs to build VirtualBox VMs (remnux, win10, win11)
- .github/workflows – CI: linter + build pipelines
- Images, README.md, LICENSE, CONTRIBUTING.md
- Patterns:
- “infrastructure as code” for Windows provisioning
- separation between host-level VM build (Python/VirtualBox) and guest-level software install (PowerShell/Boxstarter)

##### README
- Confirms:
- Pre-reqs and VM snapshot strategy
- Installer parameters and GUI flow
- Relationship between install.ps1 → Boxstarter → Chocolatey → config.xml
- VirtualBox build scripts live under virtualbox/

a. Main components
1. Host Machine
2. GitHub CI (linter + build workflows)
3. VirtualBox & Python VM-build scripts (virtualbox/*.py + configs)
4. Windows VM (guest)
5. Provisioning engine inside VM: PowerShell (install.ps1) → Boxstarter → Chocolatey → packages
6. External package repos (Chocolatey community, MyGet, remote URLs)
b. Relationships & interactions
- Host Machine triggers CI on GitHub → validates scripts
- Host runs virtualbox/vbox-*.py → builds and snapshots base VM
- User or CI invokes install.ps1 (inside guest) → calls Boxstarter
- Boxstarter commands Chocolatey to fetch, install, and configure each tool per config.xml
- Taskbar layout applied via LayoutModification.xml
- Logs written to VM_COMMON_DIR, Boxstarter, Chocolatey
c. Architectural patterns
- Infrastructure-as-Code (IaC) for VM build
- Idempotent, declarative package installation via Boxstarter/Chocolatey
- Config-driven provisioning (config.xml, YAML)
d. Key technologies
- PowerShell (install.ps1, scripts/)
- Boxstarter + Chocolatey
- Python for VirtualBox automation
- YAML configs for different VM variants
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GitHub CI Layer
    subgraph "GitHub CI"
        direction TB
        CI["CI Pipeline"]:::ci
        LintWF["Lint Workflow"]:::ci
        BuildWF["Build vbox Workflow"]:::ci
        CI --> LintWF
        CI --> BuildWF
    end

    %% Host: VirtualBox Builder
    subgraph "Host: VirtualBox Builder"
        direction TB
        VB_Flare["vbox-build-flare-vm.py"]:::script
        VB_Remnux["vbox-build-remnux.py"]:::script
        VB_Clean["vbox-clean-snapshots.py"]:::script
        VB_Export["vbox-export-snapshot.py"]:::script
        VB_Adapter["vbox-adapter-check.py"]:::script
        VB_Common["vboxcommon.py"]:::script
        VB_InstallSh["install.sh"]:::script
        YAML_Remnux["remnux.yaml"]:::config
        YAML_Win10["win10_flare-vm.yaml"]:::config
        YAML_Win10Edu["win10_flare-vm-edu.yaml"]:::config
        YAML_Win11["win11_flare-vm.yaml"]:::config
    end

    %% Windows VM Image
    VM["Windows VM Image"]:::vm

    %% Guest VM Provisioning
    subgraph "Guest VM"
        direction TB
        InstallPS["install.ps1"]:::script
        ConfigXML["config.xml"]:::config
        LayoutXML["LayoutModification.xml"]:::config
        LintPS["lint.ps1"]:::script
        subgraph "Provisioning Engine"
            direction TB
            Boxstarter["Boxstarter"]:::service
            Chocolatey["Chocolatey"]:::service
        end
        ExternalRepos["External Package Repos"]:::external
    end

    %% Documentation & Assets
    subgraph "Documentation & Metadata"
        direction TB
        README["README.md"]:::doc
        VB_README["virtualbox/README.md"]:::doc
        LICENSE["LICENSE.txt"]:::doc
        CONTRIB["CONTRIBUTING.md"]:::doc
        Images["Images/"]:::doc
    end

    %% Connections
    BuildWF -->|triggers| VB_Flare
    BuildWF --> VB_Remnux
    BuildWF --> VB_Clean
    BuildWF --> VB_Export
    BuildWF --> VB_Adapter
    BuildWF --> VB_Common
    BuildWF --> VB_InstallSh
    BuildWF --> YAML_Remnux
    BuildWF --> YAML_Win10
    BuildWF --> YAML_Win10Edu
    BuildWF --> YAML_Win11

    VB_Flare --> VM
    VB_Remnux --> VM
    VB_Clean --> VM
    VB_Export --> VM
    VB_Adapter --> VM
    VB_Common --> VM
    VB_InstallSh --> VM
    YAML_Remnux --> VM
    YAML_Win10 --> VM
    YAML_Win10Edu --> VM
    YAML_Win11 --> VM

    VM --> InstallPS
    VM --> LintPS

    ConfigXML --> InstallPS
    LayoutXML --> InstallPS

    InstallPS -->|calls| Boxstarter
    Boxstarter -->|uses| Chocolatey
    Chocolatey -->|fetches from| ExternalRepos

    %% Click Events
    click LintWF "https://github.com/mandiant/flare-vm/blob/main/.github/workflows/linter.yml"
    click BuildWF "https://github.com/mandiant/flare-vm/blob/main/.github/workflows/build-vbox.yaml"
    click VB_Flare "https://github.com/mandiant/flare-vm/blob/main/virtualbox/vbox-build-flare-vm.py"
    click VB_Remnux "https://github.com/mandiant/flare-vm/blob/main/virtualbox/vbox-build-remnux.py"
    click VB_Clean "https://github.com/mandiant/flare-vm/blob/main/virtualbox/vbox-clean-snapshots.py"
    click VB_Export "https://github.com/mandiant/flare-vm/blob/main/virtualbox/vbox-export-snapshot.py"
    click VB_Adapter "https://github.com/mandiant/flare-vm/blob/main/virtualbox/vbox-adapter-check.py"
    click VB_Common "https://github.com/mandiant/flare-vm/blob/main/virtualbox/vboxcommon.py"
    click VB_InstallSh "https://github.com/mandiant/flare-vm/blob/main/virtualbox/install.sh"
    click YAML_Remnux "https://github.com/mandiant/flare-vm/blob/main/virtualbox/configs/remnux.yaml"
    click YAML_Win10 "https://github.com/mandiant/flare-vm/blob/main/virtualbox/configs/win10_flare-vm.yaml"
    click YAML_Win10Edu "https://github.com/mandiant/flare-vm/blob/main/virtualbox/configs/win10_flare-vm-edu.yaml"
    click YAML_Win11 "https://github.com/mandiant/flare-vm/blob/main/virtualbox/configs/win11_flare-vm.yaml"
    click InstallPS "https://github.com/mandiant/flare-vm/blob/main/install.ps1"
    click ConfigXML "https://github.com/mandiant/flare-vm/blob/main/config.xml"
    click LayoutXML "https://github.com/mandiant/flare-vm/blob/main/LayoutModification.xml"
    click LintPS "https://github.com/mandiant/flare-vm/blob/main/scripts/lint.ps1"
    click README "https://github.com/mandiant/flare-vm/blob/main/README.md"
    click VB_README "https://github.com/mandiant/flare-vm/blob/main/virtualbox/README.md"
    click LICENSE "https://github.com/mandiant/flare-vm/blob/main/LICENSE.txt"
    click CONTRIB "https://github.com/mandiant/flare-vm/blob/main/CONTRIBUTING.md"
    click Images "https://github.com/mandiant/flare-vm/tree/main/Images/"

    %% Styles
    classDef script fill:#aecbfa,stroke:#333,stroke-width:1px
    classDef service fill:#b7e4c7,stroke:#333,stroke-width:1px
    classDef config fill:#fff3b0,stroke:#333,stroke-width:1px
    classDef external fill:#ffd7d7,stroke:#333,stroke-width:1px
    classDef ci fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef vm fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef doc fill:#f0f0f0,stroke:#333,stroke-width:1px
```
