powershell-scripts/winrm-https/WINRM_HTTPS_DEPLOYMENT_GUIDE.md

# WinRM HTTPS Deployment Guide for Shopfloor PCs

This guide covers deploying WinRM over HTTPS to shopfloor PCs using a wildcard certificate for the `*.logon.ds.ge.com` domain.

## Overview

WinRM HTTPS provides secure, encrypted PowerShell remoting for asset collection across multiple shopfloor computers. This deployment uses a wildcard certificate to simplify certificate management across all PCs in the domain.

### Components

1. **Setup-WinRM-HTTPS.ps1** - Configures WinRM HTTPS on target computers
2. **Invoke-RemoteAssetCollection-HTTPS.ps1** - Executes remote asset collection via HTTPS
3. **Wildcard Certificate** - `*.logon.ds.ge.com` certificate (PFX format with private key)

### Advantages Over HTTP WinRM

- **Encrypted traffic** - All data and credentials encrypted in transit
- **No TrustedHosts** - No need to configure TrustedHosts on management server
- **Better security** - Industry standard for production environments
- **Certificate authentication** - Mutual authentication support
- **Compliance** - Meets security compliance requirements

## Prerequisites

### Certificate Requirements

- Wildcard certificate for `*.logon.ds.ge.com`
- Certificate format: PFX (with private key)
- Certificate type: Server Authentication
- Must not be expired or revoked
- Same certificate can be used on all shopfloor PCs

### Target Computers (Shopfloor PCs)

- Windows 10/11 or Windows Server 2016+
- PowerShell 5.1 or later
- Network connectivity
- Administrator account for setup
- Hostnames that resolve to `hostname.logon.ds.ge.com`

### Management Server

- Windows with PowerShell 5.1 or later
- Network connectivity to shopfloor PCs on port 5986
- Administrator credentials for target computers
- DNS resolution for `*.logon.ds.ge.com`

## Deployment Steps

### Phase 1: Prepare Certificate Distribution

1. **Obtain Wildcard Certificate**
   ```powershell
   # Ensure you have the wildcard certificate PFX file
   # Example: wildcard-logon-ds-ge-com.pfx
   # Store in a secure location: C:\Certs\wildcard.pfx
   ```

2. **Create Distribution Package**
   ```
   Create a deployment folder with:
   - wildcard.pfx (the certificate)
   - Setup-WinRM-HTTPS.ps1
   - deploy-winrm-https.bat (optional batch file)
   ```

3. **Secure Certificate Password**
   ```powershell
   # Store certificate password securely
   # Document password in secure password manager
   # Share with authorized personnel only
   ```

### Phase 2: Deploy to Target Computers

#### Option A: Manual Deployment (Single Computer)

1. **Copy files to target computer**
   ```
   Copy to C:\Temp\WinRM-HTTPS-Setup\:
   - wildcard.pfx
   - Setup-WinRM-HTTPS.ps1
   ```

2. **Run setup script as Administrator**
   ```powershell
   cd C:\Temp\WinRM-HTTPS-Setup

   # Interactive mode (will prompt for certificate password)
   .\Setup-WinRM-HTTPS.ps1 -CertificatePath ".\wildcard.pfx" -Domain "logon.ds.ge.com"

   # Or with password parameter
   $certPass = ConvertTo-SecureString "YourCertPassword" -AsPlainText -Force
   .\Setup-WinRM-HTTPS.ps1 -CertificatePath ".\wildcard.pfx" `
       -CertificatePassword $certPass -Domain "logon.ds.ge.com"
   ```

3. **Verify setup**
   ```powershell
   # Check WinRM listeners
   winrm enumerate winrm/config/listener

   # Should show HTTPS listener on port 5986
   ```

#### Option B: Batch Deployment (Multiple Computers)

1. **Create deployment script**
   ```powershell
   # deploy-to-all.ps1
   $computers = Get-Content ".\shopfloor-hostnames.txt"
   $domain = "logon.ds.ge.com"
   $certPath = "C:\Certs\wildcard.pfx"
   $certPass = ConvertTo-SecureString "YourPassword" -AsPlainText -Force
   $cred = Get-Credential  # Domain admin credentials

   foreach ($hostname in $computers) {
       $fqdn = "$hostname.$domain"
       Write-Host "Deploying to $fqdn..." -ForegroundColor Yellow

       # Copy files
       $remotePath = "\\$fqdn\C$\Temp\WinRM-Setup"
       New-Item -Path $remotePath -ItemType Directory -Force
       Copy-Item ".\wildcard.pfx" -Destination $remotePath
       Copy-Item ".\Setup-WinRM-HTTPS.ps1" -Destination $remotePath

       # Execute remotely (requires existing WinRM/admin access)
       Invoke-Command -ComputerName $fqdn -Credential $cred -ScriptBlock {
           param($CertPath, $CertPass, $Domain)
           Set-Location C:\Temp\WinRM-Setup
           .\Setup-WinRM-HTTPS.ps1 -CertificatePath $CertPath `
               -CertificatePassword $CertPass -Domain $Domain
       } -ArgumentList "C:\Temp\WinRM-Setup\wildcard.pfx", $certPass, $domain

       Write-Host "Completed: $fqdn" -ForegroundColor Green
   }
   ```

#### Option C: Group Policy Deployment

1. **Import certificate via GPO**
   - Computer Configuration > Policies > Windows Settings > Security Settings
   - Public Key Policies > Certificates (Local Computer > Personal)
   - Import wildcard.pfx

2. **Deploy setup script via GPO**
   - Computer Configuration > Policies > Windows Settings > Scripts
   - Startup script: Setup-WinRM-HTTPS.ps1

### Phase 3: Test Connections

1. **Create hostname list file**
   ```
   # shopfloor-hostnames.txt
   SHOPPC001
   SHOPPC002
   SHOPPC003
   PROD-LINE-01
   PROD-LINE-02
   ```

2. **Test HTTPS connections**
   ```powershell
   .\Invoke-RemoteAssetCollection-HTTPS.ps1 `
       -HostnameListFile ".\shopfloor-hostnames.txt" `
       -Domain "logon.ds.ge.com" `
       -TestConnections
   ```

3. **Verify each connection**
   ```
   Expected output:
   Resolving SHOPPC001.logon.ds.ge.com... [192.168.x.x]
   Testing SHOPPC001.logon.ds.ge.com... [OK]
   ```

### Phase 4: Deploy Asset Collection

1. **Run asset collection**
   ```powershell
   # Get credentials once
   $cred = Get-Credential

   # Run collection across all shopfloor PCs
   .\Invoke-RemoteAssetCollection-HTTPS.ps1 `
       -HostnameListFile ".\shopfloor-hostnames.txt" `
       -Domain "logon.ds.ge.com" `
       -Credential $cred `
       -MaxConcurrent 10
   ```

2. **Monitor progress**
   ```
   Watch console output for:
   - DNS resolution results
   - Connection validation
   - Batch processing progress
   - Success/failure summary
   ```

3. **Review logs**
   ```powershell
   # Check log file
   Get-Content ".\logs\remote-collection-https.log" -Tail 50
   ```

## Configuration Options

### Setup-WinRM-HTTPS.ps1 Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| CertificatePath | Path to PFX file | - |
| CertificatePassword | SecureString password | (prompts) |
| CertificateThumbprint | Use existing cert by thumbprint | - |
| Domain | Domain suffix (e.g., logon.ds.ge.com) | Required |
| Port | HTTPS port | 5986 |
| SkipFirewall | Skip firewall configuration | false |
| TestConnection | Test after setup | false |

### Invoke-RemoteAssetCollection-HTTPS.ps1 Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| HostnameList | Array of hostnames | @() |
| HostnameListFile | Path to hostname list file | - |
| Domain | Domain suffix | Required |
| Credential | PSCredential object | (prompts) |
| MaxConcurrent | Max parallel sessions | 5 |
| Port | HTTPS port | 5986 |
| ScriptPath | Remote script path | C:\Scripts\Update-PC-CompleteAsset.ps1 |
| SkipCertificateCheck | Skip cert validation | false |
| TestConnections | Test only, no collection | false |

## Troubleshooting

### Certificate Issues

**Problem**: "Certificate not found"
```powershell
# Solution: Verify certificate is installed
Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Subject -like "*logon.ds.ge.com*"}
```

**Problem**: "Certificate has no private key"
```powershell
# Solution: Re-import certificate with private key
# Ensure PFX file includes private key
# Check "Mark this key as exportable" during import
```

**Problem**: "Certificate expired"
```powershell
# Solution: Check certificate expiration
$cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Subject -like "*logon.ds.ge.com*"}
$cert.NotAfter  # Shows expiration date
```

### Connection Issues

**Problem**: "Unable to connect to remote server"
```powershell
# Check 1: Test DNS resolution
Resolve-DnsName "shoppc001.logon.ds.ge.com"

# Check 2: Test port connectivity
Test-NetConnection -ComputerName "shoppc001.logon.ds.ge.com" -Port 5986

# Check 3: Test WinRM HTTPS
Test-WSMan -ComputerName "shoppc001.logon.ds.ge.com" -Port 5986 -UseSSL
```

**Problem**: "The SSL certificate is signed by an unknown authority"
```powershell
# Solution 1: Install root CA certificate on management server
# Import the CA certificate to Trusted Root Certification Authorities

# Solution 2: Use SkipCertificateCheck (not recommended for production)
.\Invoke-RemoteAssetCollection-HTTPS.ps1 -SkipCertificateCheck ...
```

### Firewall Issues

**Problem**: "Connection timeout"
```powershell
# On target computer, verify firewall rule
Get-NetFirewallRule -DisplayName "WinRM HTTPS-In"

# If missing, create manually
New-NetFirewallRule -DisplayName "WinRM HTTPS-In" `
    -Name "WinRM HTTPS-In" `
    -Profile Any `
    -LocalPort 5986 `
    -Protocol TCP `
    -Direction Inbound `
    -Action Allow `
    -Enabled True
```

### Authentication Issues

**Problem**: "Access denied"
```powershell
# Solution: Verify credentials have admin rights
# Check user is member of local Administrators group on target computer

# Test credentials
$cred = Get-Credential
Test-WSMan -ComputerName "shoppc001.logon.ds.ge.com" -Credential $cred -UseSSL -Port 5986
```

### Diagnostic Commands

```powershell
# On target computer (run as Administrator)

# Show all WinRM configuration
winrm get winrm/config

# Show listeners
winrm enumerate winrm/config/listener

# Show service status
Get-Service WinRM

# Test local HTTPS listener
Test-WSMan -ComputerName localhost -UseSSL -Port 5986

# Check certificate in use
$cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Subject -like "*logon.ds.ge.com*"}
$cert | Format-List *
```

## Security Best Practices

### Certificate Management

1. **Protect Private Key**
   - Store PFX files in encrypted storage
   - Limit access to certificate files
   - Use strong passwords for PFX files
   - Delete PFX files after installation

2. **Monitor Expiration**
   ```powershell
   # Create reminder for certificate renewal
   # Typical certificate lifetime: 1-2 years
   # Plan renewal 30-60 days before expiration
   ```

3. **Certificate Revocation**
   - Have process for certificate revocation if compromised
   - Distribute new certificate to all PCs
   - Remove old certificate from all systems

### Network Security

1. **Firewall Configuration**
   - Limit port 5986 to specific management IPs if possible
   - Use Windows Firewall with Advanced Security
   - Document firewall rules

2. **Network Segmentation**
   - Keep shopfloor network segregated
   - Use VLANs for additional isolation
   - Restrict management access

### Credential Management

1. **Service Accounts**
   ```powershell
   # Use dedicated service account for automation
   # Grant minimum required permissions
   # Rotate passwords regularly
   ```

2. **Credential Storage**
   ```powershell
   # For scheduled tasks, use Credential Manager
   # Never hardcode passwords in scripts
   # Use SecureString for password handling
   ```

## Maintenance

### Certificate Renewal

When wildcard certificate needs renewal:

1. **Obtain new certificate**
   - Request renewal from certificate authority
   - Export as PFX with private key

2. **Deploy new certificate**
   ```powershell
   # Run on each target computer
   .\Setup-WinRM-HTTPS.ps1 -CertificatePath ".\new-wildcard.pfx" `
       -CertificatePassword $certPass -Domain "logon.ds.ge.com"

   # This will replace the HTTPS listener with new certificate
   ```

3. **Verify deployment**
   ```powershell
   # Test connections with new certificate
   .\Invoke-RemoteAssetCollection-HTTPS.ps1 -TestConnections ...
   ```

4. **Remove old certificate**
   ```powershell
   # On each computer, remove old certificate
   Get-ChildItem Cert:\LocalMachine\My |
       Where-Object {$_.Thumbprint -eq "OLD_THUMBPRINT"} |
       Remove-Item
   ```

### Regular Checks

```powershell
# Monthly verification script
$computers = Get-Content ".\shopfloor-hostnames.txt"
$domain = "logon.ds.ge.com"

foreach ($hostname in $computers) {
    $fqdn = "$hostname.$domain"

    try {
        $result = Test-WSMan -ComputerName $fqdn -UseSSL -Port 5986 -ErrorAction Stop
        Write-Host "[OK] $fqdn" -ForegroundColor Green
    }
    catch {
        Write-Host "[FAIL] $fqdn - $($_.Exception.Message)" -ForegroundColor Red
    }
}
```

## Migration from HTTP to HTTPS

If currently using WinRM HTTP, follow these steps:

1. **Continue running HTTP during transition**
   - HTTPS and HTTP listeners can coexist
   - Test HTTPS thoroughly before removing HTTP

2. **Deploy HTTPS to all computers**
   - Use deployment procedures above
   - Verify each computer is accessible via HTTPS

3. **Update collection scripts**
   - Switch from Invoke-RemoteAssetCollection.ps1
   - To Invoke-RemoteAssetCollection-HTTPS.ps1
   - Test with small batch first

4. **Remove HTTP listeners (optional)**
   ```powershell
   # Only after HTTPS is fully verified
   winrm delete winrm/config/Listener?Address=*+Transport=HTTP
   ```

## Example Workflows

### Daily Asset Collection

```powershell
# scheduled-collection.ps1
# Run this as a scheduled task

$domain = "logon.ds.ge.com"
$hostnameFile = "C:\Scripts\shopfloor-hostnames.txt"
$logPath = "C:\Logs\asset-collection-$(Get-Date -Format 'yyyyMMdd').log"

# Use stored credentials (setup via Credential Manager)
$username = "DOMAIN\svc-assetcollection"
$password = Get-Content "C:\Secure\svc-pass.txt" | ConvertTo-SecureString
$cred = New-Object PSCredential($username, $password)

# Run collection
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile $hostnameFile `
    -Domain $domain `
    -Credential $cred `
    -MaxConcurrent 10 `
    -LogPath $logPath
```

### Ad-Hoc Single Computer Collection

```powershell
# Quick collection from one computer
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameList @("SHOPPC001") `
    -Domain "logon.ds.ge.com"
```

### Batch Collection with Reporting

```powershell
# Run collection and generate report
$result = .\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile ".\shopfloor-hostnames.txt" `
    -Domain "logon.ds.ge.com" `
    -MaxConcurrent 10

# Send email report
$summary = Get-Content ".\logs\remote-collection-https.log" | Select-Object -Last 20
Send-MailMessage -To "it-team@example.com" `
    -Subject "Asset Collection Complete - $(Get-Date -Format 'yyyy-MM-dd')" `
    -Body ($summary -join "`n") `
    -SmtpServer "smtp.example.com"
```

## Reference

### Default Ports

- HTTP WinRM: 5985 (not recommended)
- HTTPS WinRM: 5986 (recommended)

### File Locations

- Certificates: `Cert:\LocalMachine\My`
- WinRM Config: `WSMan:\localhost`
- Logs: `.\logs\remote-collection-https.log`

### Useful Commands

```powershell
# Test HTTPS connection
Test-WSMan -ComputerName "hostname.logon.ds.ge.com" -UseSSL -Port 5986

# Create session
New-PSSession -ComputerName "hostname.logon.ds.ge.com" -UseSSL -Port 5986 -Credential $cred

# Interactive session
Enter-PSSession -ComputerName "hostname.logon.ds.ge.com" -UseSSL -Port 5986 -Credential $cred

# View WinRM configuration
winrm get winrm/config

# View listeners
winrm enumerate winrm/config/listener
```

### Additional Resources

- Microsoft WinRM Documentation: https://learn.microsoft.com/en-us/windows/win32/winrm/
- PowerShell Remoting Guide: https://learn.microsoft.com/en-us/powershell/scripting/learn/remoting/
- Certificate Management: https://learn.microsoft.com/en-us/windows-server/networking/core-network-guide/

## Support

For issues or questions:
1. Check troubleshooting section above
2. Review log files in `.\logs\`
3. Verify prerequisites are met
4. Test with single computer first
5. Contact IT support team