# mayorgonzalez/goad architecture

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

- Interactive diagram: https://gitdiagram.com/mayorgonzalez/goad
- Repository: https://github.com/mayorgonzalez/goad

## Overview

##### Project Type and Purpose
- GOAD is a Python‐based CLI application that orchestrates vulnerable Active Directory labs for pentest practice.
- It supports multiple “labs” (GOAD, GOAD‐Light, MINILAB, SCCM, NHA, etc.) and “extensions” (ELK, Exchange, Wazuh, WS01).
- It integrates with various virtualization/cloud providers (AWS, Azure, Proxmox, VirtualBox, VMware, VMware ESXi, Ludus) via Terraform or Vagrant, provisions via Ansible, and can build images with Packer.

##### High‐Level Architectural Components
a. CLI / Application Layer
- Entrypoint: goad.py & goad shell script
- Command modules (`goad/command/*`), factory, menu
- Core managers: `lab_manager.py`, `instance.py`/`instances.py`, `extension.py`
- Utilities: `config.py`, `settings.py`, `log.py`, `goadpath.py`, `utils.py`, `exceptions.py`

b. Provider Layer
- Abstract provider API (`goad/provider/provider.py`, factory)
- Terraform providers (`goad/provider/terraform/*.py`) → invokes `terraform` CLI with TF templates from `ad/*/providers/*` or `template/provider/*`
- Vagrant providers (`goad/provider/vagrant/*.py`) → invokes `vagrant` CLI with Vagrantfiles under each lab’s `providers/*`
- Ludus provider plugin

c. Provisioner Layer
- Provisioner factory (`goad/provisioner/provisioner_factory.py`)
- Ansible provisioner (`goad/provisioner/ansible/*.py`) with runners: local, remote, Docker, VM

d. Data & Templates
- Lab definitions under `ad/` (each lab: `data/config.json`, `data/inventory`, `files/…`, `providers/…`, `scripts/…`)
- Extension definitions under `extensions/*`, with their own ansible roles, providers, inventories
- Generic provider templates under `template/provider/*`
- Packer definitions under `packer/` for building base images

e. External Tools & Services
- Terraform CLI → cloud‐provider APIs or on‐prem virtualization
- Vagrant CLI → VirtualBox, VMware, ESXi
- Ansible → SSH/WinRM based provisioning
- Packer → image builds for cloud/VM platforms

##### Interactions & Data Flow
1. User runs `goad <command>`
2. CLI loads global settings, lab config, extension config
3. CLI invokes Provider Layer to generate & apply infrastructure:
- Terraform or Vagrant driver reads TF/Vagrant templates (per lab+provider) → spins up VMs on target platform
4. Once instances are up, CLI invokes Provisioner Layer:
- Ansible runner (local/remote/docker/vm) uses inventories & playbooks under `ansible/` and lab data → configures AD services, applications, vulnerabilities
5. Result: fully built, configured, isolated AD pentest lab

##### Important Patterns & Principles
- Plugin Architecture: providers and provisioners are pluggable via factory patterns
- Separation of Concerns:
- CLI & orchestration (Python modules)
- Infra provisioning (Terraform/Vagrant)
- Configuration management (Ansible)
- Data definitions (lab JSON, inventories, templates)
- Extensibility: new labs (`ad/`), providers (`template/provider/`), or extensions (`extensions/`) can be added without modifying core

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::external

    %% CLI / Application Layer
    subgraph "CLI / Application Layer"
        direction TB
        subgraph "Entrypoint"
            direction TB
            Entrypoint1["goad.py"]:::cli
            Entrypoint2["goad.sh"]:::cli
        end
        subgraph "Commands"
            direction TB
            Cmd1["cmd.py"]:::cli
            Cmd2["cmd_factory.py"]:::cli
            Cmd3["linux.py"]:::cli
            Cmd4["windows.py"]:::cli
            Cmd5["wsl.py"]:::cli
        end
        subgraph "Core Managers"
            direction TB
            Core1["lab_manager.py"]:::cli
            Core2["instance.py"]:::cli
            Core3["instances.py"]:::cli
            Core4["extension.py"]:::cli
            Core5["menu.py"]:::cli
            Core6["infos.py"]:::cli
            Core7["jumpbox.py"]:::cli
            Core8["local_jumpbox.py"]:::cli
        end
        subgraph "Utilities"
            direction TB
            Util1["config.py"]:::cli
            Util2["settings.py"]:::cli
            Util3["log.py"]:::cli
            Util4["goadpath.py"]:::cli
            Util5["utils.py"]:::cli
            Util6["exceptions.py"]:::cli
            Util7["globalsettings.ini"]:::data
        end
    end

    %% Provider Layer
    subgraph "Provider Layer"
        direction TB
        subgraph "Abstract API & Factory"
            ProviderA["provider.py"]:::provider
            ProviderB["provider_factory.py"]:::provider
        end
        subgraph "Terraform Drivers"
            direction TB
            TF1["aws.py"]:::provider
            TF2["azure.py"]:::provider
            TF3["proxmox.py"]:::provider
            TF4["terraform.py"]:::provider
        end
        subgraph "Vagrant Drivers"
            direction TB
            V1["vagrant.py"]:::provider
            V2["virtualbox.py"]:::provider
            V3["vmware.py"]:::provider
            V4["vmware_esxi.py"]:::provider
        end
        subgraph "Ludus Plugin"
            Ludus["ludus.py"]:::provider
        end
    end

    %% Provisioner Layer
    subgraph "Provisioner Layer"
        direction TB
        subgraph "Factory & Core"
            ProvA["provisioner_factory.py"]:::provisioner
            ProvB["provisioner.py"]:::provisioner
        end
        subgraph "Ansible Runners"
            direction TB
            Ans1["ansible.py"]:::provisioner
            Ans2["docker.py"]:::provisioner
            Ans3["local.py"]:::provisioner
            Ans4["remote.py"]:::provisioner
            Ans5["runner.py"]:::provisioner
            Ans6["vm.py"]:::provisioner
        end
    end

    %% Data & Templates
    subgraph "Data & Templates"
        direction TB
        LabDefs["Lab Definitions (ad/)"]:::data
        ExtDefs["Extension Definitions (extensions/)"]:::data
        ProvTemps["Provider Templates (template/provider/)"]:::data
        PackerDefs["Packer Definitions (packer/)"]:::data
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        ET1["Terraform CLI"]:::external
        ET2["Vagrant CLI"]:::external
        ET3["Ansible CLI"]:::external
        ET4["Packer CLI"]:::external
    end

    %% VM Instances
    subgraph "VM Instances"
        direction TB
        VMs["Virtual Machines"]:::vm
    end

    %% Connections
    User -->|runs goad| Entrypoint1
    User -->|runs goad| Entrypoint2

    Entrypoint1 -->|loads modules| Cmd1
    Entrypoint1 --> Cmd2
    Entrypoint1 --> Cmd3
    Entrypoint1 --> Cmd4
    Entrypoint1 --> Cmd5
    Entrypoint1 --> Core1
    Entrypoint1 --> Util1

    Entrypoint1 -->|"reads config"| Util7
    Entrypoint1 -->|"reads lab data"| LabDefs
    Entrypoint1 -->|"reads extension data"| ExtDefs

    Entrypoint1 -->|"generate & apply infra"| ProviderA
    ProviderA --> ProviderB
    ProviderB --> TF1
    ProviderB --> TF2
    ProviderB --> TF3
    ProviderB --> TF4
    ProviderB --> V1
    ProviderB --> V2
    ProviderB --> V3
    ProviderB --> V4
    ProviderB --> Ludus

    TF1 --> ET1
    TF2 --> ET1
    TF3 --> ET1
    TF4 --> ET1
    V1 --> ET2
    V2 --> ET2
    V3 --> ET2
    V4 --> ET2
    Ludus --> ET1

    ET1 --> VMs
    ET2 --> VMs

    Entrypoint1 -->|"configure"| ProvA
    ProvA --> ProvB
    ProvB --> Ans1
    ProvB --> Ans2
    ProvB --> Ans3
    ProvB --> Ans4
    ProvB --> Ans5
    ProvB --> Ans6

    Ans1 --> ET3
    ET3 --> VMs

    Entrypoint1 ---|extension hook| Core4
    Core4 --> ExtDefs

    ET4 -->|build images| VMs

    %% Click Events
    click Entrypoint1 "https://github.com/mayorgonzalez/goad/blob/main/goad.py"
    click Entrypoint2 "https://github.com/mayorgonzalez/goad/blob/main/goad.sh"
    click Cmd1 "https://github.com/mayorgonzalez/goad/blob/main/goad/command/cmd.py"
    click Cmd2 "https://github.com/mayorgonzalez/goad/blob/main/goad/command/cmd_factory.py"
    click Cmd3 "https://github.com/mayorgonzalez/goad/blob/main/goad/command/linux.py"
    click Cmd4 "https://github.com/mayorgonzalez/goad/blob/main/goad/command/windows.py"
    click Cmd5 "https://github.com/mayorgonzalez/goad/blob/main/goad/command/wsl.py"
    click Core1 "https://github.com/mayorgonzalez/goad/blob/main/goad/lab_manager.py"
    click Core2 "https://github.com/mayorgonzalez/goad/blob/main/goad/instance.py"
    click Core3 "https://github.com/mayorgonzalez/goad/blob/main/goad/instances.py"
    click Core4 "https://github.com/mayorgonzalez/goad/blob/main/goad/extension.py"
    click Core5 "https://github.com/mayorgonzalez/goad/blob/main/goad/menu.py"
    click Core6 "https://github.com/mayorgonzalez/goad/blob/main/goad/infos.py"
    click Core7 "https://github.com/mayorgonzalez/goad/blob/main/goad/jumpbox.py"
    click Core8 "https://github.com/mayorgonzalez/goad/blob/main/goad/local_jumpbox.py"
    click Util1 "https://github.com/mayorgonzalez/goad/blob/main/goad/config.py"
    click Util2 "https://github.com/mayorgonzalez/goad/blob/main/goad/settings.py"
    click Util3 "https://github.com/mayorgonzalez/goad/blob/main/goad/log.py"
    click Util4 "https://github.com/mayorgonzalez/goad/blob/main/goad/goadpath.py"
    click Util5 "https://github.com/mayorgonzalez/goad/blob/main/goad/utils.py"
    click Util6 "https://github.com/mayorgonzalez/goad/blob/main/goad/exceptions.py"
    click ProviderA "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/provider.py"
    click ProviderB "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/provider_factory.py"
    click TF1 "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/terraform/aws.py"
    click TF2 "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/terraform/azure.py"
    click TF3 "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/terraform/proxmox.py"
    click TF4 "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/terraform/terraform.py"
    click V1 "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/vagrant/vagrant.py"
    click V2 "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/vagrant/virtualbox.py"
    click V3 "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/vagrant/vmware.py"
    click V4 "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/vagrant/vmware_esxi.py"
    click Ludus "https://github.com/mayorgonzalez/goad/blob/main/goad/provider/ludus/ludus.py"
    click ProvA "https://github.com/mayorgonzalez/goad/blob/main/goad/provisioner/provisioner_factory.py"
    click ProvB "https://github.com/mayorgonzalez/goad/blob/main/goad/provisioner/provisioner.py"
    click Ans1 "https://github.com/mayorgonzalez/goad/blob/main/goad/provisioner/ansible/ansible.py"
    click Ans2 "https://github.com/mayorgonzalez/goad/blob/main/goad/provisioner/ansible/docker.py"
    click Ans3 "https://github.com/mayorgonzalez/goad/blob/main/goad/provisioner/ansible/local.py"
    click Ans4 "https://github.com/mayorgonzalez/goad/blob/main/goad/provisioner/ansible/remote.py"
    click Ans5 "https://github.com/mayorgonzalez/goad/blob/main/goad/provisioner/ansible/runner.py"
    click Ans6 "https://github.com/mayorgonzalez/goad/blob/main/goad/provisioner/ansible/vm.py"
    click LabDefs "https://github.com/mayorgonzalez/goad/tree/main/ad/"
    click ExtDefs "https://github.com/mayorgonzalez/goad/tree/main/extensions/"
    click ProvTemps "https://github.com/mayorgonzalez/goad/tree/main/template/provider/"
    click PackerDefs "https://github.com/mayorgonzalez/goad/tree/main/packer/"

    %% Styles
    classDef cli fill:#ccebff,stroke:#004080;
    classDef provider fill:#ccffcc,stroke:#006600;
    classDef provisioner fill:#ffe0b3,stroke:#b36b00;
    classDef data fill:#ffffb3,stroke:#808000;
    classDef external fill:#d9d9d9,stroke:#666666;
    classDef vm fill:#ffcccc,stroke:#800000;
```
