From 85d2e34bc4c67dc8042aa6d9fc49310b30db2cd4 Mon Sep 17 00:00:00 2001 From: mkultraWasHere Date: Wed, 8 Apr 2026 00:06:07 -0400 Subject: [PATCH 01/10] build(deps): pin community.general and geerlingguy.mysql These two ansible dependencies were previously unpinned, meaning every fresh `ansible-galaxy install` could pick up a different upstream version on different days. That makes builds non-reproducible across the same git commit and lets a breaking upstream release silently break the lab. Bound to the current major series (community.general 9.x-10.x, mysql 4.x). Renovate (already configured for ansible-galaxy deps) will open PRs for patch bumps automatically. Co-Authored-By: Claude --- ansible/galaxy.yml | 2 +- ansible/requirements.yml | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/ansible/galaxy.yml b/ansible/galaxy.yml index 984a8d1a..f7a42650 100644 --- a/ansible/galaxy.yml +++ b/ansible/galaxy.yml @@ -19,7 +19,7 @@ tags: dependencies: amazon.aws: ">=9.0.0" ansible.windows: ">=2.5.0" - community.general: "*" + community.general: ">=9.0.0,<11.0.0" community.windows: ">=2.3.0" chocolatey.chocolatey: ">=1.5.3" repository: https://github.com/dreadnode/ansible-collection-goad diff --git a/ansible/requirements.yml b/ansible/requirements.yml index fecf0f6f..5da3d607 100644 --- a/ansible/requirements.yml +++ b/ansible/requirements.yml @@ -3,6 +3,7 @@ collections: - name: ansible.windows version: ">=2.5.0" - name: community.general + version: ">=9.0.0,<11.0.0" - name: community.windows version: ">=2.3.0" - name: chocolatey.chocolatey @@ -14,3 +15,4 @@ collections: roles: - name: geerlingguy.mysql + version: ">=4.0.0,<5.0.0" From 9f1337630f22018eeaaaaec6ac1c8be8b712e047 Mon Sep 17 00:00:00 2001 From: mkultraWasHere Date: Wed, 8 Apr 2026 00:06:21 -0400 Subject: [PATCH 02/10] chore: add OSS hygiene files (SECURITY, CoC, CITATION, templates) Adds the standard set of files external contributors expect on a public repo, in preparation for an OSS release: - SECURITY.md: scopes the project's deliberately-vulnerable lab content out of the security report channel and routes tooling vulnerabilities through GitHub private vulnerability advisories. - CODE_OF_CONDUCT.md: Contributor Covenant 2.1 with an added clause clarifying that offensive-security tradecraft discussion is on-topic. - CITATION.cff: lets researchers cite DreadGOAD in papers and reports; references the upstream OCD/GOAD project so citations propagate. - .github/ISSUE_TEMPLATE/{config,bug_report,feature_request}.yml: structured issue forms with provider/lab dropdowns and a "this is tooling, not an intentional lab vuln" gate. - .github/PULL_REQUEST_TEMPLATE.md: provider/lab/OS prompts and a checklist that distinguishes intentional lab credentials from real secrets. Co-Authored-By: Claude --- .github/ISSUE_TEMPLATE/bug_report.yml | 123 ++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 70 ++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 77 +++++++++++ CITATION.cff | 44 +++++++ CODE_OF_CONDUCT.md | 144 +++++++++++++++++++++ SECURITY.md | 81 ++++++++++++ 7 files changed, 550 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CITATION.cff create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..eb82d347 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,123 @@ +name: Bug report +description: Report a problem with the DreadGOAD CLI, Ansible roles, Terraform modules, or another part of the tooling. +title: "[bug]: " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug report. + + Before you continue, please confirm: + + - The issue is in the **DreadGOAD tooling** (CLI, Ansible, Terraform/Terragrunt, Packer, Warpgate, variant generator). Weak passwords and other intentional vulnerabilities inside the deployed labs are by design — please do not file those as bugs. + - If you believe you have found a **security vulnerability in the tooling itself**, do not open a public issue. Use [private vulnerability reporting](https://github.com/dreadnode/DreadGOAD/security/advisories/new) instead. See [SECURITY.md](https://github.com/dreadnode/DreadGOAD/blob/main/SECURITY.md). + + - type: checkboxes + id: preflight + attributes: + label: Pre-flight checks + options: + - label: I have searched existing issues and this is not a duplicate. + required: true + - label: I have run `dreadgoad doctor` (or the equivalent) and read its output. + required: false + - label: This is a bug in the DreadGOAD tooling, not an intentional lab vulnerability. + required: true + + - type: input + id: version + attributes: + label: DreadGOAD version + description: "Output of `dreadgoad --version`, or the commit SHA of `main` you are on." + placeholder: "e.g. 1.2.3 (commit: abc1234, built: 2026-04-07) -or- main @ abc1234" + validations: + required: true + + - type: dropdown + id: provider + attributes: + label: Provider + description: Which infrastructure provider were you using? + options: + - VirtualBox + - VMware + - Proxmox + - AWS + - Azure + - Ludus + - Not provider-specific + - Other (please describe in the bug report) + validations: + required: true + + - type: dropdown + id: lab + attributes: + label: Lab + description: Which lab were you deploying when you hit the issue? + options: + - GOAD + - GOAD-Light + - GOAD-Mini + - MINILAB + - SCCM + - NHA + - DRACARYS + - A generated variant + - Not lab-specific + - Other (please describe in the bug report) + validations: + required: true + + - type: input + id: os + attributes: + label: Operator OS + description: The OS where you are running the DreadGOAD CLI / Ansible (not the lab VMs). + placeholder: "e.g. macOS 14.5 (arm64), Ubuntu 22.04, Windows 11 + WSL2" + validations: + required: true + + - type: textarea + id: description + attributes: + label: What happened? + description: A clear description of the bug, including what you expected to happen and what actually happened. + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: | + The exact commands you ran. Please include the full command line, any relevant config snippets (`dreadgoad.yaml`, `globalsettings.ini`), and the working directory. + placeholder: | + 1. `git clone https://github.com/dreadnode/DreadGOAD.git` + 2. `cd cli && go build -o dreadgoad .` + 3. `./dreadgoad provision --lab GOAD-Light --provider virtualbox` + 4. ... + render: shell + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant logs + description: | + Paste the relevant CLI output, Ansible log lines, or Terraform error. + + Tip: rerun with `--debug` for more detail. Logs are also written to `~/.ansible/logs/goad/`. + render: shell + validations: + required: false + + - type: textarea + id: extra + attributes: + label: Anything else? + description: Screenshots, related issues, recent changes you made, ideas about the cause, etc. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..f08a1ea7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability in the DreadGOAD tooling + url: https://github.com/dreadnode/DreadGOAD/security/advisories/new + about: "Report security issues in the CLI, Ansible collection, Terraform / Terragrunt modules, or other tooling privately. Do NOT use a public issue. Note: weak passwords and other intentional vulnerabilities inside the deployed labs are by design and should not be reported." + - name: Upstream GOAD documentation + url: https://orange-cyberdefense.github.io/GOAD/ + about: "Background on the original GOAD project that DreadGOAD is forked from." + - name: DreadGOAD documentation + url: https://github.com/dreadnode/DreadGOAD/tree/main/docs + about: "Provider guides, lab descriptions, validation guide, and the full vulnerability catalog." diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..97be7ca2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,70 @@ +name: Feature request +description: Suggest a new feature, improvement, or change to DreadGOAD. +title: "[feature]: " +labels: ["enhancement", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement to DreadGOAD. + + Before you continue, please check the [existing issues](https://github.com/dreadnode/DreadGOAD/issues?q=is%3Aissue) to see whether something similar has already been proposed. + + - type: checkboxes + id: preflight + attributes: + label: Pre-flight checks + options: + - label: I have searched existing issues and discussions for a similar request. + required: true + + - type: dropdown + id: area + attributes: + label: Area + description: Which part of the project does this affect? + options: + - CLI (`dreadgoad`) + - Ansible collection / roles + - Terraform / Terragrunt modules + - Packer / Warpgate templates + - A specific lab (GOAD, GOAD-Light, MINILAB, SCCM, NHA, DRACARYS, ...) + - A specific extension (ELK, Exchange, Wazuh, Guacamole, ...) + - Variant generator + - Documentation + - CI / release tooling + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: Describe the use case and the pain point you are running into. "I'm always frustrated when..." + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: How would you like this to work? Be as concrete as you can — example commands, config snippets, or UI sketches all help. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches you considered and why you rejected them. + validations: + required: false + + - type: textarea + id: extra + attributes: + label: Additional context + description: Links, references, related issues, or anything else useful. + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..384bddbf --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,77 @@ + + +## Summary + + + +## Type of change + + + +- [ ] Bug fix (non-breaking change that fixes an issue) +- [ ] New feature (non-breaking change that adds functionality) +- [ ] Breaking change (fix or feature that would change existing behavior) +- [ ] New lab, lab variant, or extension +- [ ] New / updated provider support +- [ ] Refactor / internal cleanup (no functional change) +- [ ] Documentation +- [ ] CI / build / release tooling +- [ ] Dependency update + +## Area + + + +- [ ] CLI (`cli/`) +- [ ] Ansible collection (`ansible/`) +- [ ] Terraform / Terragrunt (`infra/`, `modules/`) +- [ ] Packer / Warpgate (`packer/`, `warpgate-templates/`) +- [ ] Lab definitions (`ad/`) +- [ ] Extensions (`extensions/`) +- [ ] Variant generator / tools (`tools/`) +- [ ] Documentation (`docs/`, `README.md`, etc.) +- [ ] CI workflows (`.github/`) + +## Related issues + + + +## How was this tested? + + + +- Provider(s) tested: +- Lab(s) tested: +- Operator OS: + +## Screenshots / logs (optional) + + + +## Checklist + +- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md). +- [ ] My changes follow the existing code style of the area I touched. +- [ ] I have added or updated tests where it makes sense (Go tests under `cli/`, Ansible syntax checks, etc.). +- [ ] I have updated documentation (README, `docs/`, role README, command help text) where relevant. +- [ ] I have checked that I am not committing real secrets, personal credentials, or internal hostnames. (Intentional lab credentials inside `ad/`, `ansible/`, and `extensions/` are expected and fine.) +- [ ] If this PR changes user-facing CLI behavior, I have updated the relevant `--help` text and any docs that reference it. +- [ ] If this PR introduces a breaking change, I have called it out in the **Summary** above. diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 00000000..964664ed --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,44 @@ +cff-version: 1.2.0 +message: "If you use DreadGOAD in academic work, training material, a blog post, a conference talk, or a published security report, please cite it using the metadata below." +title: "DreadGOAD: Vulnerable Active Directory lab environments for security research and training" +abstract: >- + DreadGOAD is a heavily modified fork of the Game of Active Directory (GOAD) + project that deploys intentionally vulnerable Active Directory lab + environments across multiple infrastructure providers (VirtualBox, VMware, + Proxmox, AWS, Azure, and Ludus). It provides a Go CLI for provisioning, + health checking, and validation; an Ansible collection of 80+ roles for + domain configuration and vulnerability injection; Terraform / Terragrunt + modules and Warpgate AMI templates for cloud deployment; and a variant + generator that produces graph-isomorphic lab copies with randomized entity + names while preserving all attack paths. The labs include 50+ deliberately + configured vulnerabilities such as Kerberoasting, AS-REP roasting, ACL abuse + chains, ADCS misconfigurations (ESC1–8), MSSQL attack paths, and constrained + / unconstrained delegation abuse. +type: software +authors: + - name: "Dreadnode" + website: "https://dreadnode.io" +repository-code: "https://github.com/dreadnode/DreadGOAD" +url: "https://github.com/dreadnode/DreadGOAD" +license: GPL-3.0-or-later +keywords: + - active-directory + - security-research + - penetration-testing + - red-team + - detection-engineering + - security-training + - kerberoasting + - adcs + - vulnerable-lab + - ansible + - terraform +references: + - type: software + title: "GOAD (Game of Active Directory)" + authors: + - name: "Orange Cyberdefense" + - name: "Mayfly" + repository-code: "https://github.com/Orange-Cyberdefense/GOAD" + url: "https://github.com/Orange-Cyberdefense/GOAD" + notes: "DreadGOAD is a fork of the upstream GOAD project. If you cite DreadGOAD, please also cite the original GOAD project." diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..2a196eca --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,144 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances + of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Scope of security content + +DreadGOAD is an offensive-security training project. Discussion of attack +techniques, vulnerable configurations, exploitation tooling, and red-team +tradecraft is on-topic and welcome in issues, pull requests, and discussions +about the project. This Code of Conduct governs how we treat **each other**, not +the technical subject matter. Disagreement about a technique's effectiveness or +realism is fine; personal attacks, harassment, or doxxing are not. + +Do not use this project, its issues, or its discussions to coordinate attacks +against systems you do not own or have explicit written permission to test. + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards +of acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, and will communicate reasons for +moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the project maintainers via GitHub's private vulnerability +reporting at +, or by opening +a minimal public issue requesting a private contact channel. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Project maintainers will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of this +Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from project maintainers, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +. Translations are available at +. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..791081aa --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,81 @@ +# Security Policy + +## About this project + +DreadGOAD intentionally deploys **vulnerable Active Directory environments** +for offensive security training, penetration-testing practice, detection +engineering, and security research. Weak passwords, kerberoastable accounts, +ADCS misconfigurations (ESC1–8), ACL abuse paths, MSSQL attack chains, and +similar weaknesses inside the deployed labs are **intentional product +features**, not security bugs. + +> [!CAUTION] +> Never deploy DreadGOAD on a production network, on a network shared with +> production assets, or on any host reachable from the public internet without +> strict isolation. Treat any DreadGOAD deployment as fully compromised by +> default. + +## What counts as a vulnerability in DreadGOAD + +We *do* want to hear about security issues in the **DreadGOAD tooling itself**, +which is everything that ships outside the deliberately-vulnerable lab content: + +- The `dreadgoad` Go CLI (`cli/`) +- The Ansible collection and custom modules (`ansible/`) +- Terraform / Terragrunt modules (`infra/`, `modules/`) +- Warpgate AMI build templates (`warpgate-templates/`) +- Packer templates (`packer/`) +- Variant generator and other tooling (`tools/`) +- GitHub Actions workflows (`.github/workflows/`) + +Examples of issues we consider in scope: + +- Command injection, path traversal, or unsafe deserialization in the CLI or + Python tooling +- Privilege escalation in deployment scripts that runs against the operator's + workstation rather than the lab +- Exposure of operator credentials (AWS keys, Azure tokens, etc.) by the + tooling — for example, leaking them into world-readable logs or remote state +- Supply-chain issues such as a compromised release artifact or a malicious + dependency pin +- A cloud module that opens lab VMs to the public internet by default rather + than gating them behind SSM / a private subnet + +Examples of issues that are **not** vulnerabilities (please do not report +these — they are how the project works): + +- Weak or known passwords on lab accounts +- Kerberoastable / AS-REP-roastable users +- Vulnerable ADCS templates, ACL misconfigurations, unconstrained delegation +- Plaintext credentials inside `ad/`, `ansible/`, or `extensions/` lab content +- The lab being exploitable end-to-end — that is the point + +## How to report + +Please report tooling vulnerabilities **privately** using GitHub's private +vulnerability reporting: + +1. Go to +2. Provide a clear description, affected version / commit, reproduction steps, + and (if possible) a suggested fix or mitigation. + +If GitHub private reporting is unavailable to you, you may instead open a +minimal public issue asking for a private contact channel — do not include +exploit details in the public issue. + +Please do **not** report tooling vulnerabilities via public GitHub issues, +pull requests, discussions, or social media before we have had a chance to +respond. + +## What to expect + +- We will acknowledge receipt of your report within a few business days. +- We will work with you to confirm the issue and determine impact. +- Once a fix is ready, we will coordinate disclosure and credit you in the + release notes (unless you prefer to remain anonymous). + +## Supported versions + +DreadGOAD is provided as-is for research and training. Security fixes are +applied to the `main` branch; users are expected to track `main` or the most +recent tagged release. Older releases do not receive backports. From 18eedebd26b94dac0d93d49ec940a612dab66275 Mon Sep 17 00:00:00 2001 From: mkultraWasHere Date: Wed, 8 Apr 2026 00:06:37 -0400 Subject: [PATCH 03/10] docs: clarify dreadgoad CLI vs goad.py provider scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A new user clones the repo and finds two entry points (the legacy Python goad.py REPL and the newer dreadgoad Go CLI) with no clear guidance on which to use when. The previous installation/usage docs still led with goad.py while README examples used dreadgoad — and dreadgoad's operational commands (provision, validate, health-check, verify-trusts, lab, ssm) are in fact AWS-only, not cross-provider as the docs implied. Adds a new docs/mkdocs/docs/cli-vs-goadpy.md migration page with the provider x tool support table, a three-line decision rule, capability matrix, and a goad.py-to-dreadgoad command equivalence table. Updates installation/index.md to drop the misleading upstream-OCD "GOAD use no more bash" paragraph and lead with the actual tool scope. Rewrites usage/index.md as three sections: AWS workflow (dreadgoad), all other providers (goad.sh), and provider-agnostic dreadgoad utilities. Rewrites providers/aws.md to drop goad.py / goad.ini / jumpbox REPL references in favor of dreadgoad infra/ami/provision/ssm flow. Adds the new page to mkdocs.yml nav and to README's Documentation section. Adds a provider-scope note to README Quick Start so it stops implying dreadgoad works on every provider. Co-Authored-By: Claude --- README.md | 10 +++- docs/mkdocs/docs/cli-vs-goadpy.md | 97 +++++++++++++++++++++++++++++++ docs/mkdocs/mkdocs.yml | 1 + 3 files changed, 107 insertions(+), 1 deletion(-) create mode 100644 docs/mkdocs/docs/cli-vs-goadpy.md diff --git a/README.md b/README.md index 3eb9bd96..735fbec1 100644 --- a/README.md +++ b/README.md @@ -60,8 +60,15 @@ cd cli && go build -o dreadgoad . && cd .. ### Deploy a Lab +DreadGOAD ships two tools, scoped strictly by provider: + +- **AWS** → `dreadgoad` end-to-end (Terragrunt + Warpgate + Ansible + SSM). +- **VirtualBox / VMware / Proxmox / Azure / Ludus** → `./goad.sh` end-to-end. + +`dreadgoad`'s operational commands (`provision`, `health-check`, `validate`, `verify-trusts`, `lab`, `ssm`, …) are **AWS-only** — they assume EC2 + SSM. See [CLI vs `goad.py`](docs/mkdocs/docs/cli-vs-goadpy.md) for the full breakdown. + ```bash -# Provision the full GOAD lab +# AWS workflow — provision the lab against an existing AWS deployment ./cli/dreadgoad provision # Health check all instances @@ -85,6 +92,7 @@ See [tools/variant_generator/](tools/variant_generator/) for details. ## Documentation +- [CLI vs `goad.py`](docs/mkdocs/docs/cli-vs-goadpy.md) -- which tool to use for which provider, capability matrix, command equivalence - [CLI configuration](docs/cli.md) -- Viper-based config, environment variables, per-environment settings - [Domains and users](docs/domains-and-users.md) -- full network topology, credentials, and attack paths - [Vulnerability catalog](docs/GOAD-vulnerabilities-comprehensive.md) -- all 50+ vulnerabilities with exploitation techniques diff --git a/docs/mkdocs/docs/cli-vs-goadpy.md b/docs/mkdocs/docs/cli-vs-goadpy.md new file mode 100644 index 00000000..dcf9a7cd --- /dev/null +++ b/docs/mkdocs/docs/cli-vs-goadpy.md @@ -0,0 +1,97 @@ +# CLI vs `goad.py` — which tool to use + +DreadGOAD ships **two tools, scoped strictly by provider**. They are not interchangeable. + +- **`dreadgoad`** — the Go CLI (`cli/dreadgoad`). One-shot commands, declarative flags, no REPL. **AWS only** for everything operational. Drives the full AWS workflow: Terragrunt infrastructure, Warpgate golden AMIs, Ansible provisioning, AWS Session Manager access, vulnerability validation, and lab lifecycle. +- **`goad.sh`** (a wrapper around `goad.py`) — the Python REPL. The tool for **VirtualBox, VMware, Proxmox, Azure, and Ludus**. Drives Vagrant-based VM lifecycle and Ansible provisioning end-to-end. Still fully supported. + +If you remember nothing else: **AWS → `dreadgoad`. Anything else → `goad.sh`.** + +## Provider × tool support + +| Provider | Tool | Notes | +|--------------|--------------|--------------------------------------------------------------| +| AWS | `dreadgoad` | Terragrunt + Warpgate + Ansible + SSM. No public ports. | +| VirtualBox | `goad.sh` | Vagrant + Ansible. | +| VMware | `goad.sh` | Vagrant + Ansible. | +| Proxmox | `goad.sh` | Proxmoxer + Ansible. | +| Azure | `goad.sh` | Azure SDK + Ansible. | +| Ludus | `goad.sh` | Ludus API + Ansible. | + +> [!IMPORTANT] +> `dreadgoad`'s operational commands (`provision`, `health-check`, `validate`, `verify-trusts`, `inventory`, `lab`, `ssm`) all assume the lab is running on AWS EC2 and access it through Systems Manager. They will not work against a VirtualBox / VMware / Proxmox / Azure / Ludus deployment. For those providers, use `goad.sh` for the entire workflow. + +## What `dreadgoad` does (AWS only) + +Full lifecycle for an AWS lab: + +| Command | Purpose | +|--------------------------------------------------|---------------------------------------------------------------| +| `dreadgoad doctor` | Pre-flight checks (ansible-core, AWS CLI, Terragrunt, …) | +| `dreadgoad ami build|list-resources|purge` | Build / inspect / clean up Warpgate golden AMIs | +| `dreadgoad infra init|plan|apply|destroy|output` | Manage Terragrunt-backed AWS infrastructure | +| `dreadgoad inventory sync|show|mapping` | Sync the Ansible inventory with live EC2 instance IDs | +| `dreadgoad provision` | Run the Ansible playbooks against the deployed lab | +| `dreadgoad health-check` | Verify all instances are reachable and healthy via SSM | +| `dreadgoad validate [--quick]` | Verify the intentional vulnerabilities are configured | +| `dreadgoad verify-trusts` | Verify AD trust relationships across domains | +| `dreadgoad lab status|start|stop` | Lab-wide EC2 instance lifecycle | +| `dreadgoad lab start-vm|stop-vm|restart-vm` | Per-host EC2 lifecycle | +| `dreadgoad ssm connect|run|status|cleanup` | AWS Session Manager access — no open ports | +| `dreadgoad env create|list` | Manage multiple deployment environments (dev / staging / prod)| + +## What `goad.sh` / `goad.py` does (everything else) + +Full lifecycle for VirtualBox, VMware, Proxmox, Azure, and Ludus, via an interactive REPL: + +| REPL command | Purpose | +|------------------------------------|--------------------------------------------------------------| +| `set_lab ` / `set_provider` | Select the lab and provider for the current session | +| `check` | Pre-flight checks | +| `install` | Create the VMs and run all provisioning playbooks | +| `provide` | Create the VMs only (Vagrant / API / etc.) | +| `provision_lab` | Run the full Ansible playbook sequence | +| `provision_lab_from ` | Resume provisioning from a specific playbook | +| `start` / `stop` / `status` | Lab-wide VM lifecycle | +| `start_vm` / `stop_vm` / `destroy_vm` | Per-VM lifecycle | +| `snapshot` / `reset` | Snapshot and restore VM state | +| `ssh_jumpbox` / `ssh_jumpbox_proxy`| Access lab VMs through the jumpbox | +| `config` | Show current settings | +| `?` | Interactive help | + +There is also `goad_docker.sh`, which runs the same tool with `-m docker -d local -d runner` to drive Ansible from inside a Docker container. + +## Provider-agnostic `dreadgoad` utilities + +A handful of `dreadgoad` subcommands have **no AWS dependency** and can be used regardless of which tool you use to deploy your lab: + +- `dreadgoad config show|init|set` — manage `~/.config/dreadgoad/dreadgoad.yaml` +- `dreadgoad variant generate ...` — generate graph-isomorphic randomized lab copies (operates on lab definition files in `ad/`) +- `dreadgoad lab-list` — list available labs + +These are file/config utilities, not operational commands. + +## Mental model: AWS workflow vs `goad.py` workflow + +If you've used the legacy Python REPL and are wondering "what does that look like on AWS?": + +| Goal | `goad.py` REPL (any non-AWS provider) | `dreadgoad` (AWS only) | +|---------------------------------------------|---------------------------------------|----------------------------------------------| +| Pre-flight checks | `check` | `dreadgoad doctor` | +| Build / customize the base VM image | (Packer or vendor's default image) | `dreadgoad ami build