Manual Steps to build and test a new module

INTEGRATION_TESTING_GUIDE.md

Manual Integration Testing Guide

Environment:

• PE Server: rich-tandem.delivery.puppetlabs.net (RedHat 8)
• Windows Agent: alma-woomera.delivery.puppetlabs.net (Windows 2022)
• Module: poc_dsc_replacement (MinimumPasswordLength implementation)

---

Phase 1: Module Packaging & Deployment

Step 1.1: Build the Module Package

cd /Users/mehul.jain/work/modules/poc_dsc_replacement

# Build the tarball
pdk build

# Output should show:
# pdk (INFO): Building poc_dsc_replacement with pdk ...
# pdk (INFO): Module built: pkg/puppet-poc_dsc_replacement-0.1.0.tar.gz

Step 1.2: Verify Package Contents

# Check what was packaged
tar -tzf pkg/puppet-poc_dsc_replacement-0.1.0.tar.gz | head -20

# Should include:
# - lib/puppet/type/securityoption.rb
# - lib/puppet/provider/securityoption/ruby.rb
# - lib/puppet_x/secedit.rb
# - lib/puppet_x/inf.rb
# - lib/puppet_x/security_policy/data.rb
# - spec/ (unit tests)

Step 1.3: Copy Module to PE Server

# From your local machine, copy to the PE server
scp pkg/puppet-poc_dsc_replacement-0.1.0.tar.gz \
  mehul.jain@rich-tandem.delivery.puppetlabs.net:/tmp/

# Verify transfer
ssh mehul.jain@rich-tandem.delivery.puppetlabs.net \
  "ls -lh /tmp/puppet-poc_dsc_replacement-0.1.0.tar.gz"

Step 1.4: Install Module on PE Server

# SSH into PE server
ssh mehul.jain@rich-tandem.delivery.puppetlabs.net

# Extract to modules directory
sudo tar -xzf /tmp/puppet-poc_dsc_replacement-0.1.0.tar.gz -C /etc/puppetlabs/code/environments/production/modules/

# Verify installation
ls -la /etc/puppetlabs/code/environments/production/modules/poc_dsc_replacement/

# Should show:
# lib/
# spec/
# metadata.json
# README.md
# etc.

Step 1.5: Verify Module on PE Server

# Run PDK validate on the installed module
cd /etc/puppetlabs/code/environments/production/modules/poc_dsc_replacement
sudo pdk validate

# Expected output:
# pdk (INFO): Running all available validators...
# pdk (INFO): Validator 'ruby-syntax' completed successfully
# pdk (INFO): Validator 'rubocop' completed successfully

---

Phase 2: Windows Agent Configuration

Step 2.1: Verify Windows Agent Connectivity

# From PE server, test agent connectivity
sudo puppet node list | grep alma-woomera

# Or from Windows agent (via SSH or WinRM):
# Test SSL certificate is trusted:
# Run on Windows agent:
# C:\Program Files\Puppet Labs\Puppet\bin\puppet agent --test

Step 2.2: Create Puppet Manifest for Testing

On PE Server, create test manifest:

# Create or edit the Windows agent's node classifier
# Option A: Using node classification (GUI)
# - Log into PE Console
# - Navigate to: Configuration > Classification
# - Find or create node group for alma-woomera

# Option B: Using code (preferred for testing)
cat > /etc/puppetlabs/code/environments/production/manifests/windows_test.pp << 'EOF'
# Test manifest for Windows security options
node 'alma-woomera.delivery.puppetlabs.net' {
  # Include the poc_dsc_replacement module
  include poc_dsc_replacement
  
  # Test Case 1: Set MinimumPasswordLength to 14
  securityoption { 'MinimumPasswordLength':
    ensure => present,
    value  => '14',
  }
  
  # Test Case 2: Set MaximumPasswordAge to 90 days
  # (This tests the data.rb mapping works correctly)
  securityoption { 'MaximumPasswordAge':
    ensure => present,
    value  => '90',
  }
  
  # Test Case 3: Set PasswordHistorySize to 24
  securityoption { 'PasswordHistorySize':
    ensure => present,
    value  => '24',
  }
}
EOF

# Verify syntax
sudo puppet parser validate /etc/puppetlabs/code/environments/production/manifests/windows_test.pp
sudo systemctl restart pe-puppetserver
puppet agent -t
/opt/puppetlabs/bin/puppet resource --types | grep securityoption

Step 2.3: Alternative - Use Site.pp

# If using site.pp instead
cat >> /etc/puppetlabs/code/environments/production/manifests/site.pp << 'EOF'

# Windows Security Options Test
node 'alma-woomera.delivery.puppetlabs.net' {
  securityoption { 'MinimumPasswordLength':
    ensure => present,
    value  => '14',
  }
}
EOF

# Verify
sudo puppet parser validate /etc/puppetlabs/code/environments/production/manifests/site.pp
sudo systemctl restart pe-puppetserver
puppet agent -t
/opt/puppetlabs/bin/puppet resource --types | grep securityoption

---

Phase 3: Run Puppet Agent on Windows Node

Step 3.1: Trigger Puppet Run

# Option A: SSH into Windows agent (if SSH enabled)
ssh Administrator@alma-woomera.delivery.puppetlabs.net

rm -rf /cygdrive/c/ProgramData/PuppetLabs/puppet/cache/lib/*
puppet.bat plugin download --verbose

# Run puppet agent manually
C:\Program Files\Puppet Labs\Puppet\bin\puppet agent --test --verbose

# Expected output:
# Notice: Starting Puppet client version 8.x.x
# Info: Caching catalog for alma-woomera.delivery.puppetlabs.net
# Info: Applying configuration version '...'
# Notice: /Stage[main]/... [resource_title] (notice)
# Info: Creating state file /var/lib/puppet/state/state.yaml
# Notice: Applied catalog in X.XX seconds

Step 3.2: Check Agent Logs (PE Server)

# From PE server, check agent reports
sudo tail -100 /var/log/puppetlabs/puppetserver/puppetserver.log | grep alma-woomera

# Or view in PE Console:
# - Navigate to: Nodes > alma-woomera.delivery.puppetlabs.net
# - Check last report status

---

Phase 4: Windows System Verification

Step 4.1: Verify Security Policy Changes

On Windows Agent (alma-woomera), verify the settings were applied:

Using secedit (Command Prompt as Admin):

# Export current security policy
secedit /export /cfg %TEMP%\secpol_export.inf /areas SECURITYPOLICY

# View the exported file
notepad %TEMP%\secpol_export.inf

# Look for:
# [System Access]
# MinimumPasswordLength = 14
# MaximumPasswordAge = 90
# PasswordHistorySize = 24

Using PowerShell (as Admin):

# Test 1: Check if minimum password length was set
$policy = Get-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\Netlogon\Parameters" -Name MinimumPasswordLength -ErrorAction SilentlyContinue
if ($policy) {
    Write-Host "MinimumPasswordLength is set to: $($policy.MinimumPasswordLength)"
} else {
    Write-Host "MinimumPasswordLength not found in registry"
}

# Test 2: Export and parse the security policy
secedit /export /cfg C:\temp\policy.inf /areas SECURITYPOLICY
$content = Get-Content C:\temp\policy.inf
$content | Select-String "MinimumPasswordLength" | ForEach-Object {
    Write-Host "Found: $_"
}

# Test 3: Check using net accounts (only shows local account policy)
net accounts
# Look for "Minimum password length"

Using GUI:

1. Open: Settings > Security Settings > Account Policies > Password Policy
2. Look for "Minimum password length" 
3. Verify it shows "14 characters"

OR using secpol.msc:
1. Run: secpol.msc
2. Navigate: Security Settings > Account Policies > Password Policy
3. Verify: "Minimum password length" = 14

Step 4.2: Verify Puppet Created the INF File

# Check if temporary INF files were created during Puppet run
dir C:\Windows\Temp\puppet*.inf

# If no longer present (cleaned up), check Puppet logs:
dir C:\ProgramData\PuppetLabs\puppet\var\log\puppet.log

Step 4.3: Check Puppet Agent Log

# View Puppet agent log
Get-Content C:\ProgramData\PuppetLabs\puppet\var\log\puppet.log -Tail 50

# Look for:
# Info: Applying configuration
# Notice: [resource_title] (notice)
# Notice: Applied catalog in X.XX seconds

---

Phase 5: Test Idempotency

Step 5.1: Run Puppet Agent Again

# From Windows agent (second run)
C:\Program Files\Puppet Labs\Puppet\bin\puppet agent --test

# Expected output:
# Notice: Using cached catalog
# Notice: Applied catalog in X.XX seconds
# (No resource changes should appear - idempotency confirmed)

Step 5.2: Verify No Changes

# Export policy again
secedit /export /cfg C:\temp\policy2.inf /areas SECURITYPOLICY

# Compare the exports
diff C:\temp\policy.inf C:\temp\policy2.inf

# Should show no differences (or only date/time stamps)

---

Phase 6: Test Modification & Rollback

Step 6.1: Modify the Manifest

On PE Server, update the manifest:

# Edit the manifest to change the password length
sudo cat > /etc/puppetlabs/code/environments/production/manifests/windows_test.pp << 'EOF'
node 'alma-woomera.delivery.puppetlabs.net' {
  securityoption { 'MinimumPasswordLength':
    ensure => present,
    value  => '12',  # Changed from 14 to 12
  }
}
EOF

# Verify syntax
sudo puppet parser validate /etc/puppetlabs/code/environments/production/manifests/windows_test.pp

Step 6.2: Apply Changes

# Run Puppet agent on Windows
C:\Program Files\Puppet Labs\Puppet\bin\puppet agent --test

# Verify change in secedit
secedit /export /cfg C:\temp\policy3.inf /areas SECURITYPOLICY
findstr "MinimumPasswordLength" C:\temp\policy3.inf

# Should now show: MinimumPasswordLength = 12

Step 6.3: Test Rollback

# Restore to original setting
sudo cat > /etc/puppetlabs/code/environments/production/manifests/windows_test.pp << 'EOF'
node 'alma-woomera.delivery.puppetlabs.net' {
  securityoption { 'MinimumPasswordLength':
    ensure => present,
    value  => '14',  # Back to 14
  }
}
EOF

# Apply
C:\Program Files\Puppet Labs\Puppet\bin\puppet agent --test

# Verify
secedit /export /cfg C:\temp\policy4.inf /areas SECURITYPOLICY
findstr "MinimumPasswordLength" C:\temp\policy4.inf

# Should show: MinimumPasswordLength = 14

---

Phase 7: Test Error Handling

Step 7.1: Test Invalid Value

On PE Server:

# Create a manifest with invalid value (out of range)
cat > /etc/puppetlabs/code/environments/production/manifests/windows_test.pp << 'EOF'
node 'alma-woomera.delivery.puppetlabs.net' {
  securityoption { 'MinimumPasswordLength':
    ensure => present,
    value  => '999',  # Invalid - too large
  }
}
EOF

Step 7.2: Run and Check Error

# Run Puppet agent
C:\Program Files\Puppet Labs\Puppet\bin\puppet agent --test

# Expected: Puppet should handle gracefully (error message in logs)
# Check: C:\ProgramData\PuppetLabs\puppet\var\log\puppet.log
# Look for error message about invalid value

---

Phase 8: Test Multiple Settings Together

Step 8.1: Create Comprehensive Test

On PE Server:

cat > /etc/puppetlabs/code/environments/production/manifests/windows_test.pp << 'EOF'
node 'alma-woomera.delivery.puppetlabs.net' {
  # Password Policy Settings
  securityoption { 'MinimumPasswordLength':
    ensure => present,
    value  => '14',
  }
  
  securityoption { 'MaximumPasswordAge':
    ensure => present,
    value  => '90',
  }
  
  securityoption { 'PasswordHistorySize':
    ensure => present,
    value  => '24',
  }
  
  securityoption { 'LockoutBadCount':
    ensure => present,
    value  => '3',
  }
  
  securityoption { 'LockoutDuration':
    ensure => present,
    value  => '30',
  }
}
EOF

Step 8.2: Run and Verify All

# On Windows agent
C:\Program Files\Puppet Labs\Puppet\bin\puppet agent --test

# Verify all settings
secedit /export /cfg C:\temp\comprehensive.inf /areas SECURITYPOLICY
findstr /E "MinimumPasswordLength MaximumPasswordAge PasswordHistorySize LockoutBadCount LockoutDuration" C:\temp\comprehensive.inf

# Should show all values set correctly

---

Phase 9: Cleanup & Documentation

Step 9.1: Restore Original Settings (Optional)

# If you want to revert to original Windows defaults:
cat > /etc/puppetlabs/code/environments/production/manifests/windows_test.pp << 'EOF'
node 'alma-woomera.delivery.puppetlabs.net' {
  # Empty - no securityoption resources
}
EOF

Step 9.2: Generate Test Report

# Collect results from Puppet Enterprise Console
# Path: https://rich-tandem.delivery.puppetlabs.net
# Navigate to: Nodes > alma-woomera.delivery.puppetlabs.net > Reports
# Download/screenshot the successful run report

Step 9.3: Document Results

# Create a test results file
cat > TEST_RESULTS.md << 'EOF'
# Integration Test Results

Date: $(date)
Module: poc_dsc_replacement
Version: 0.1.0
PE Server: rich-tandem.delivery.puppetlabs.net
Windows Agent: alma-woomera.delivery.puppetlabs.net
OS: Windows Server 2022

## Test Cases

### Test 1: Module Installation
- [ ] Module packaged successfully
- [ ] Module deployed to PE server
- [ ] Module syntax validated

### Test 2: Basic Application
- [ ] Puppet catalog compiled
- [ ] Puppet applied without errors
- [ ] MinimumPasswordLength set to 14

### Test 3: Windows Verification
- [ ] secedit shows correct value
- [ ] Security policy updated
- [ ] Registry reflects change (if applicable)

### Test 4: Idempotency
- [ ] Second run shows no changes
- [ ] Configuration stable

### Test 5: Modification
- [ ] Value updated to 12
- [ ] Windows policy reflects change
- [ ] Rollback to 14 succeeds

### Test 6: Multiple Settings
- [ ] All 5 settings applied
- [ ] All verified in secedit export

## Notes
[Add any observations, issues, or additional findings]
EOF

---

Troubleshooting Guide

Issue: Agent Certificate Errors

# On PE Server, accept the Windows agent certificate
sudo puppetserver ca list
sudo puppetserver ca sign --certname alma-woomera.delivery.puppetlabs.net

Issue: Module Not Found

# Verify module is in correct location
sudo ls /etc/puppetlabs/code/environments/production/modules/ | grep poc_dsc_replacement

# If missing, reinstall:
sudo tar -xzf /tmp/puppet-poc_dsc_replacement-0.1.0.tar.gz -C /etc/puppetlabs/code/environments/production/modules/

Issue: Puppet Run Fails

# Check Puppet server logs
sudo tail -100 /var/log/puppetlabs/puppetserver/puppetserver.log | grep -i error

# Check catalog compilation
sudo puppet catalog compile alma-woomera.delivery.puppetlabs.net

# Check module syntax on server
cd /etc/puppetlabs/code/environments/production/modules/poc_dsc_replacement
sudo pdk validate

Issue: secedit Command Fails

# Run CMD as Administrator
# Verify secedit is available
where secedit

# Check permissions
icacls "C:\Windows\System32\secedit.exe"

# Try manual secedit export
secedit /export /cfg C:\temp\test.inf /areas SECURITYPOLICY /log C:\temp\secedit.log /verbose

Issue: Value Not Applied

# Check Puppet agent logs on Windows
Get-Content C:\ProgramData\PuppetLabs\puppet\var\log\puppet.log -Tail 200 | Select-String -Pattern "securityoption|error" -Context 2,2

# Check if INF file was created
dir C:\Windows\Temp\puppet*.inf

# Manually run the secedit command that Puppet would run:
secedit /configure /db C:\Windows\Security\Database\secedit.sdb /cfg C:\temp\puppet_policy.inf /overwrite /log C:\temp\secedit_manual.log /verbose

---

Success Criteria

✅ All tests pass when:

1. Module packages without errors
2. Module deploys to PE server successfully
3. Puppet manifest syntax validates
4. Puppet agent run succeeds with no errors
5. secedit export shows correct values
6. Second Puppet run shows no changes (idempotency)
7. Modified values apply correctly
8. Rollback succeeds
9. Multiple settings work together
10. Error conditions handled gracefully

---

Next Steps After Successful Testing

1. Create accountpolicy resource type (following same pattern)
2. Expand to all ~100 security settings in data.rb
3. Create integration tests that verify secedit output
4. Package as Puppet module for distribution
5. Document for production use