# orange-cyberdefense/goad architecture

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

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

## Overview

GOAD is a command-line orchestrator for building vulnerable Active Directory practice labs. A user selects a lab, provider, provisioner, network range, and extensions; the manager creates or loads an instance, renders provider configuration, deploys infrastructure, and runs Ansible playbooks to reach a provisioned lab. Lifecycle commands then start, stop, inspect, reset, or destroy it. The tree supports multiple lab families and provider integrations; detailed lab definitions and some provider implementations were not sampled.

Main entry points: [`goad/lab_manager.py`](https://github.com/orange-cyberdefense/goad/blob/main/goad/lab_manager.py) (Lab manager), [`goad/instance.py`](https://github.com/orange-cyberdefense/goad/blob/main/goad/instance.py) (Lab instance), [`goad/provider/provider_factory.py`](https://github.com/orange-cyberdefense/goad/blob/main/goad/provider/provider_factory.py) (Provider factory), [`goad/command/cmd.py`](https://github.com/orange-cyberdefense/goad/blob/main/goad/command/cmd.py) (Command runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI orchestration"]
  node_goad_cli["GOAD CLI<br/>[goad.py]"]
  node_lab_manager["Lab manager<br/>[lab_manager.py]"]
end

subgraph group_lifecycle["Lab lifecycle"]
  node_labs["Lab catalog<br/>[labs.py]"]
  node_instances["Instance registry<br/>[instances.py]"]
  node_lab_instance["Lab instance<br/>[instance.py]"]
  node_extensions["Lab extensions<br/>[extension.py]"]
end

subgraph group_providers["Infrastructure providers"]
  node_provider_factory["Provider factory"]
  node_vagrant_provider["Vagrant providers<br/>[vagrant.py]"]
  node_terraform_provider["Terraform providers<br/>[terraform.py]"]
  node_ludus_provider["Ludus provider<br/>[ludus.py]"]
  node_command_runtime["Command runtime<br/>[cmd.py]"]
end

subgraph group_provisioning["Configuration provisioning"]
  node_provisioner_factory["Provisioner factory"]
  node_ansible["Ansible orchestration<br/>[ansible.py]"]
  node_provisioner_modes["Provisioner modes<br/>[runner.py]"]
  node_jumpbox["Jumpbox access<br/>[jumpbox.py]"]
end

node_user(("Pentester"))
node_lab_targets[("Lab VMs")]
node_cloud_platforms{{"Cloud platforms"}}
node_ansible_engine{{"Ansible engine"}}

node_user -->|"issues commands"| node_goad_cli
node_goad_cli -->|"dispatches tasks"| node_lab_manager
node_lab_manager -->|"loads labs"| node_labs
node_lab_manager -->|"manages instances"| node_instances
node_lab_manager -->|"creates instance"| node_lab_instance
node_lab_manager -->|"selects extensions"| node_extensions
node_lab_instance -->|"selects provider"| node_provider_factory
node_lab_instance -->|"selects provisioner"| node_provisioner_factory
node_provider_factory -->|"creates Vagrant"| node_vagrant_provider
node_provider_factory -->|"creates Terraform"| node_terraform_provider
node_provider_factory -->|"creates Ludus"| node_ludus_provider
node_vagrant_provider -->|"runs Vagrant"| node_command_runtime
node_terraform_provider -->|"runs Terraform"| node_command_runtime
node_ludus_provider -->|"runs Ludus"| node_command_runtime
node_terraform_provider -.->|"manages resources"| node_cloud_platforms
node_command_runtime -->|"controls VMs"| node_lab_targets
node_provisioner_factory -->|"creates mode"| node_provisioner_modes
node_provisioner_modes -->|"runs provisioning"| node_ansible
node_ansible -->|"executes playbooks"| node_ansible_engine
node_ansible -->|"configures VMs"| node_lab_targets
node_lab_instance -->|"prepares access"| node_jumpbox
node_jumpbox -->|"connects remotely"| node_lab_targets

click node_goad_cli "https://github.com/orange-cyberdefense/goad/blob/main/goad.py"
click node_lab_manager "https://github.com/orange-cyberdefense/goad/blob/main/goad/lab_manager.py"
click node_labs "https://github.com/orange-cyberdefense/goad/blob/main/goad/labs.py"
click node_instances "https://github.com/orange-cyberdefense/goad/blob/main/goad/instances.py"
click node_lab_instance "https://github.com/orange-cyberdefense/goad/blob/main/goad/instance.py"
click node_extensions "https://github.com/orange-cyberdefense/goad/blob/main/goad/extension.py"
click node_provider_factory "https://github.com/orange-cyberdefense/goad/blob/main/goad/provider/provider_factory.py"
click node_vagrant_provider "https://github.com/orange-cyberdefense/goad/blob/main/goad/provider/vagrant/vagrant.py"
click node_terraform_provider "https://github.com/orange-cyberdefense/goad/blob/main/goad/provider/terraform/terraform.py"
click node_ludus_provider "https://github.com/orange-cyberdefense/goad/blob/main/goad/provider/ludus/ludus.py"
click node_command_runtime "https://github.com/orange-cyberdefense/goad/blob/main/goad/command/cmd.py"
click node_provisioner_factory "https://github.com/orange-cyberdefense/goad/blob/main/goad/provisioner/provisioner_factory.py"
click node_ansible "https://github.com/orange-cyberdefense/goad/blob/main/goad/provisioner/ansible/ansible.py"
click node_provisioner_modes "https://github.com/orange-cyberdefense/goad/blob/main/goad/provisioner/ansible/runner.py"
click node_jumpbox "https://github.com/orange-cyberdefense/goad/blob/main/goad/jumpbox.py"

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_goad_cli,node_lab_manager toneBlue
class node_labs,node_instances,node_lab_instance,node_extensions,node_lab_targets toneAmber
class node_provider_factory,node_vagrant_provider,node_terraform_provider,node_ludus_provider,node_command_runtime toneMint
class node_provisioner_factory,node_ansible,node_provisioner_modes,node_jumpbox toneRose
class node_user,node_cloud_platforms,node_ansible_engine toneIndigo
```

## Components

### CLI orchestration

- [GOAD CLI](https://github.com/orange-cyberdefense/goad/blob/main/goad.py): `goad.py`
- [Lab manager](https://github.com/orange-cyberdefense/goad/blob/main/goad/lab_manager.py): `goad/lab_manager.py`

### Lab lifecycle

- [Lab catalog](https://github.com/orange-cyberdefense/goad/blob/main/goad/labs.py): `goad/labs.py`
- [Instance registry](https://github.com/orange-cyberdefense/goad/blob/main/goad/instances.py): `goad/instances.py`
- [Lab instance](https://github.com/orange-cyberdefense/goad/blob/main/goad/instance.py): `goad/instance.py`
- [Lab extensions](https://github.com/orange-cyberdefense/goad/blob/main/goad/extension.py): `goad/extension.py`

### Infrastructure providers

- [Provider factory](https://github.com/orange-cyberdefense/goad/blob/main/goad/provider/provider_factory.py): `goad/provider/provider_factory.py`
- [Vagrant providers](https://github.com/orange-cyberdefense/goad/blob/main/goad/provider/vagrant/vagrant.py): `goad/provider/vagrant/vagrant.py`
- [Terraform providers](https://github.com/orange-cyberdefense/goad/blob/main/goad/provider/terraform/terraform.py): `goad/provider/terraform/terraform.py`
- [Ludus provider](https://github.com/orange-cyberdefense/goad/blob/main/goad/provider/ludus/ludus.py): `goad/provider/ludus/ludus.py`
- [Command runtime](https://github.com/orange-cyberdefense/goad/blob/main/goad/command/cmd.py): `goad/command/cmd.py`

### Configuration provisioning

- [Provisioner factory](https://github.com/orange-cyberdefense/goad/blob/main/goad/provisioner/provisioner_factory.py): `goad/provisioner/provisioner_factory.py`
- [Ansible orchestration](https://github.com/orange-cyberdefense/goad/blob/main/goad/provisioner/ansible/ansible.py): `goad/provisioner/ansible/ansible.py`
- [Provisioner modes](https://github.com/orange-cyberdefense/goad/blob/main/goad/provisioner/ansible/runner.py): `goad/provisioner/ansible/runner.py`
- [Jumpbox access](https://github.com/orange-cyberdefense/goad/blob/main/goad/jumpbox.py): `goad/jumpbox.py`

### Other components

- **Pentester**
- **Lab VMs**
- **Cloud platforms**
- **Ansible engine**

## Connections

- Pentester → GOAD CLI: issues commands
- GOAD CLI → Lab manager: dispatches tasks
- Lab manager → Lab catalog: loads labs
- Lab manager → Instance registry: manages instances
- Lab manager → Lab instance: creates instance
- Lab manager → Lab extensions: selects extensions
- Lab instance → Provider factory: selects provider
- Lab instance → Provisioner factory: selects provisioner
- Provider factory → Vagrant providers: creates Vagrant
- Provider factory → Terraform providers: creates Terraform
- Provider factory → Ludus provider: creates Ludus
- Vagrant providers → Command runtime: runs Vagrant
- Terraform providers → Command runtime: runs Terraform
- Ludus provider → Command runtime: runs Ludus
- Terraform providers → Cloud platforms: manages resources
- Command runtime → Lab VMs: controls VMs
- Provisioner factory → Provisioner modes: creates mode
- Provisioner modes → Ansible orchestration: runs provisioning
- Ansible orchestration → Ansible engine: executes playbooks
- Ansible orchestration → Lab VMs: configures VMs
- Lab instance → Jumpbox access: prepares access
- Jumpbox access → Lab VMs: connects remotely
