How mayorgonzalez/goad works
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