PurpleCloud Documentation

PurpleCloud is a collection of Python-based Terraform generators designed to rapidly deploy various Azure security labs for offensive and defensive training. Instead of manually editing static Terraform templates, you run Python scripts that generate customized Terraform files based on your specific requirements.

Key lab types include:

• Azure Sentinel Labs: Build environments with automated log shipping (Sysmon, Windows Security logs) to a Log Analytics Workspace/Sentinel. Includes support for Entra ID logs via Diagnostic settings.
• Active Directory (AD) Labs: Build AD DS environments, including support for ADFS (Federation) and Azure AD Join labs.
• Azure Managed Identity Labs: Create environments specifically for testing Managed Identity attack pathways.
• Phishing Application Labs: Spin up multi-tenant Azure AD applications for app consent phishing simulations.
• Azure Storage Labs: Deploy storage accounts with file shares, containers, blobs, and Key Vaults.

Active Directory is built on the Domain Controller (DC) using a CSV file. By default, the DC uses ad_users.csv (located at C:\terraform\ad_users.csv on the DC).

Customizing Users:

• Use the --csv <csv_file> flag to provide your own user list. This file is copied to ad_users.csv and uploaded to the storage container for the DC to download.
• OUs: The oupath field in the CSV determines the Organizational Unit. If the OU= string specifies an OU that doesn't exist, the script creates it.
• Groups: The groups field in the CSV determines which AD groups the user is added to. Ensure the groups and OU= portion of the oupath match to avoid errors.

Default Users: The system includes a set of default users defined in a Python dictionary in adfs.py. After the first five default users are created, additional users are randomly generated based on the --ad_users count.

Use aadjoin.py to generate a lab consisting of Windows 10 Pro systems that automatically join to Azure Active Directory as managed devices. This is useful for security research into managed device registration, SSO tokens (PRT), Intune, or VDI deployments.

Prerequisites:

1. Navigate to the generator directory before running the script:

   cd generators/aadjoin

2. You must provide at least one endpoint (VM) and a UPN suffix.

Core Workflow:

1. Run the aadjoin.py script with your desired parameters.
2. The script generates several Terraform files (e.g., main_aadjoin.tf, users.tf, roles.tf) and user data files (azure_users.csv).
3. Run terraform apply to provision the resources in Azure.
4. Note that terraform apply will generate a random password shared by all users; this password is displayed at the end of the process or can be retrieved via terraform output.

python3 aadjoin.py --upn <upn_suffix_domain> --endpoints <vm_count>

Follow these steps to set up the PurpleCloud environment on Ubuntu Linux 20.04.

1. Clone the repository

Use git to clone the repository. Note that the shared directory contains large files (Sysmon, Azure AD Connect, etc.). If you use a standard git client, ensure you have git-lfs installed, or download the repository as a ZIP file from your browser to include the large files.

To install git-lfs on Ubuntu:

apt-get install git-lfs

git clone https://github.com/iknowjason/PurpleCloud.git

2. Install Python dependencies

Install the faker library via pip. This is required for several generation scripts including azure_ad.py, ad.py, managed_identity.py, sentinel.py, adfs.py, and aadjoin.py.

pip3 install faker

3. Generate and Run Terraform

After setting up your environment (see Azure Authentication Setup), follow these steps:

1. Generate Terraform: Run one of the PurpleCloud Python scripts (e.g., sentinel.py) to generate the Terraform configuration files.
2. Initialize Terraform:

   terraform init

3. Plan the deployment:

   terraform plan -out=run.plan

4. Apply the configuration:

   terraform apply run.plan

The generated Terraform files allow for manual customization of roles and network access.

Managed Identity Role Assignment

By default, the User Assigned Identity role is scoped to the subscription. You can scope it to specific resources like a Key Vault by uncommenting the scope line in the azurerm_role_assignment resource:

resource "azurerm_role_assignment" "uai" {
  # scope                = azurerm_key_vault.example.id
  scope                = data.azurerm_subscription.mi.id
  role_definition_name = "ROLE_DEFINITION_NAME"
  principal_id         = azurerm_user_assigned_identity.uai.principal_id
}

Azure AD User Role

To change the role of the generated Azure AD user, modify the user_role variable:

variable "user_role" {
  default = "Virtual Machine Contributor"
  # default = "Contributor"
  # default = "Reader"
  # default = "Owner"
}

Network Access (NSG Whitelisting)

To allow access from a specific IP or all IPs, modify the src_ip local variable in the Terraform configuration:

locals {
  src_ip = chomp(data.http.firewall_allowed.response_body)
  # src_ip = "0.0.0.0/0" # Uncomment to allow all IPs
}

# Example: Scoping Managed Identity to a Key Vault
resource "azurerm_role_assignment" "uai" {
  scope                = azurerm_key_vault.example.id
  role_definition_name = "Reader"
  principal_id         = azurerm_user_assigned_identity.uai.principal_id
}

You can deploy a full Active Directory environment including a Domain Controller (DC) and Windows 10 endpoints joined to the domain.

Example: Randomly Generated Users

This command creates a Sentinel deployment, a Domain Controller with a forest named rtcfingroup.com, a custom local admin, and 500 randomly generated domain users. It also joins 2 Windows 10 endpoints to the domain.

python3 sentinel.py --domain_controller --ad_domain rtcfingroup.com --admin RTCAdmin --password MyPassword012345 --ad_users 500 --endpoints 2 --domain_join

Example: Import Custom Users from CSV

Instead of random users, you can provide a users.csv file to populate the Active Directory. The script validates the format.

CSV Format Example:

name,upn,password,groups,oupath,domain_admin
Lars Borgerson,larsborgerson@rtcfingroup.com,MyPassword012345,IT,OU=IT;DC=rtcfingroup;DC=com,False
Olivia Odinsdottir,oliviaodinsdottir@rtcfingroup.com,MyPassword012345,IT,OU=IT;DC=rtcfingroup;DC=com,True

python3 sentinel.py --domain_controller --ad_domain rtcfingroup.com --admin RTCAdmin --password MyPassword012345 --csv users.csv --endpoints 2 --domain_join