custom-atomics-deployment

name: Custom Atomics Deployment description: Create, deploy, and execute custom Atomic Red Team tests (T9999.XXX series) for detection validation. Covers YAML authoring, Ansible deployment, and manual alternatives.

Custom Atomics Deployment Skill

Overview

When no standard Atomic Red Team test covers your detection scenario, create a custom atomic using the T9999.XXX numbering scheme. This avoids collisions with upstream technique IDs while giving you full control over the test payload.

Configuration

Required environment variables:

Target placeholders:

• <TARGET_IP> — IP address of the test endpoint
• <TARGET_NAME> — Hostname of the test endpoint (e.g., ar-win-1)

T9999.XXX Numbering Convention

YAML Authoring

Directory Structure

$CUSTOM_ATOMICS_PATH/
  T9999.001/
    T9999.001.yaml
    src/
      payload.ps1    (optional supporting files)
  T9999.002/
    T9999.002.yaml

YAML Template

attack_technique: T9999.001
display_name: "Custom - Suspicious Encoded PowerShell Download"
atomic_tests:
  - name: "PowerShell download cradle with Net.WebClient and encoding"
    auto_generated_guid: <generate-a-uuid>
    description: |
      Simulates an encoded PowerShell download cradle using Net.WebClient.
      Maps to T1059.001 (PowerShell) + T1105 (Ingress Tool Transfer).
      Designed to trigger detections for encoded command execution.
    supported_platforms:
      - windows
    input_arguments:
      target_url:
        description: URL to download from
        type: url
        default: "http://127.0.0.1:8080/test.txt"
    dependency_executor_name: powershell
    dependencies:
      - description: "PowerShell must be available"
        prereq_command: "Get-Command powershell.exe"
        get_prereq_command: "echo 'PowerShell not found'"
    executor:
      command: |
        $encoded = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes("(New-Object Net.WebClient).DownloadString('#{target_url}')"))
        powershell.exe -EncodedCommand $encoded
      cleanup_command: |
        echo "No cleanup required"
      name: powershell
      elevation_required: false

YAML Authoring Tips

• Always include auto_generated_guid — Generate with uuidgen or any UUID tool
• Use input_arguments — Makes tests reusable across environments
• Include dependencies — Prerequisite checks prevent confusing failures
• Include cleanup_command — Even if it's just a no-op, document it
• Map to real techniques — Note which ATT&CK technique(s) the custom atomic simulates in the description

Deployment Methods

Method 1: Ansible (Recommended)

Ansible provides idempotent, repeatable deployment to one or many targets.

Deploy custom atomic to Windows target:

ansible <TARGET_NAME> -m win_copy \
  -a "src=$CUSTOM_ATOMICS_PATH/T9999.001/ dest=C:\\AtomicRedTeam\\atomics\\T9999.001\\" \
  --extra-vars "ansible_host=<TARGET_IP>"

Deploy to Linux target:

ansible <TARGET_NAME> -m copy \
  -a "src=$CUSTOM_ATOMICS_PATH/T9999.100/ dest=/opt/atomic-red-team/atomics/T9999.100/ mode=0755" \
  --extra-vars "ansible_host=<TARGET_IP>"

Deploy all custom atomics at once:

ansible <TARGET_NAME> -m win_copy \
  -a "src=$CUSTOM_ATOMICS_PATH/ dest=C:\\AtomicRedTeam\\atomics\\" \
  --extra-vars "ansible_host=<TARGET_IP>"

Method 2: SCP / WinRM (Manual)

For one-off deployments without Ansible:

# Linux target
scp -r "$CUSTOM_ATOMICS_PATH/T9999.100" user@<TARGET_IP>:/opt/atomic-red-team/atomics/

# Windows target (via PowerShell remoting)
$session = New-PSSession -ComputerName <TARGET_IP> -Credential (Get-Credential)
Copy-Item -Path "$env:CUSTOM_ATOMICS_PATH\T9999.001" -Destination "C:\AtomicRedTeam\atomics\" -ToSession $session -Recurse

Method 3: Attack Range (if using AR)

cd "$ATTACK_RANGE_PATH"
source "$ATTACK_RANGE_VENV/bin/activate"

# Use AR's simulate with custom atomics path
python attack_range.py simulate -t T9999.001 --target <TARGET_NAME>

Note: Attack Range may need configuration to recognize custom atomics paths.

Alternatives to Ansible

Execution

On Windows Target (PowerShell)

# Import module (if not already loaded)
Import-Module "C:\AtomicRedTeam\invoke-atomicredteam\Invoke-AtomicRedTeam.psd1"

# List custom atomic tests
Invoke-AtomicTest T9999.001 -ShowDetailsBrief

# Run prerequisites
Invoke-AtomicTest T9999.001 -TestNumbers 1 -GetPrereqs

# Execute
Invoke-AtomicTest T9999.001 -TestNumbers 1

# Cleanup
Invoke-AtomicTest T9999.001 -TestNumbers 1 -Cleanup

On Linux Target (Bash)

If using the Go-based atomic runner (goart):

./goart run T9999.100

Or execute manually based on the YAML's command field.

Remote Execution via Ansible

# Windows
ansible <TARGET_NAME> -m win_shell \
  -a "Import-Module C:\\AtomicRedTeam\\invoke-atomicredteam\\Invoke-AtomicRedTeam.psd1; Invoke-AtomicTest T9999.001 -TestNumbers 1" \
  --extra-vars "ansible_host=<TARGET_IP>"

# Linux
ansible <TARGET_NAME> -m shell \
  -a "/opt/goart/goart run T9999.100" \
  --extra-vars "ansible_host=<TARGET_IP>"

Validation Checklist

After deploying and executing a custom atomic:

• YAML passes syntax validation (yamllint T9999.XXX.yaml)
• auto_generated_guid is present and unique
• Atomic deploys to target without errors
• Invoke-AtomicTest -ShowDetailsBrief lists the test correctly
• Prerequisites pass or install successfully
• Execution completes without errors
• Expected telemetry appears in SIEM (check after appropriate delay)
• Detection rule fires on the generated telemetry
• Cleanup command runs without errors

Troubleshooting