InvokePsExec.psm1
|
#requires -version 3 function Invoke-PsExec { <# .SYNOPSIS Svendsen Tech's Invoke-PsExec for PowerShell is a function that lets you execute PowerShell and batch/cmd.exe code asynchronously on target Windows computers, using PsExec.exe. Versions of PsExec.exe after about 2015 some time (don't quote me on the date) use encrypted credentials when connecting to remote computers. Online documentation: http://www.powershelladmin.com/wiki/Invoke-PsExec_for_PowerShell Copyright (C) 2015-2017, Joakim Borger Svendsen All rights reserved. Svendsen Tech. MIT license. http://www.opensource.org/licenses/MIT .PARAMETER ComputerName IP address or computer name. .PARAMETER Command PowerShell or batch/cmd.exe code to execute. .PARAMETER IsPSCommand This indicates that the specified command string is pure PowerShell code (you will usually want single quotes around that to avoid escaping). .PARAMETER IsLongPSCommand Use this if the PowerShell code produces a base64-encoded string of a length greater than 260, so you get 'Argument to long' [SIC] from PsExec. This uses a temporary file that's created on the remote computer. .PARAMETER CustomPsExecParameters Custom parameters for PsExec. .PARAMETER PSFile PowerShell file in the local file system to be run via PsExec on the remote computer. .PARAMETER Dns Perform a DNS lookup. .PARAMETER Credential Pass in alternate credentials. Get-Help Get-Credential. .PARAMETER ContinueOnPingFail Attempt PsExec command even if ping fails. .PARAMETER ThrottleLimit Number of concurrent threads. Default of 8. Lower it if results appear to be missing without reason. .PARAMETER HideProgress Do not display progress with Write-Progress. .PARAMETER Timeout Timeout in seconds. Causes problems if too short. 30-60 as a default seems OK. Increase if doing a lot of processing with PsExec. .PARAMETER HideSummary Do not display the end summary with start and end time, using Write-Host. #> [CmdletBinding()] param( # IP address or computer name. [Parameter(Mandatory=$True,ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True)][ValidateNotNullOrEmpty()][Alias('PSComputerName', 'Cn')][string[]] $ComputerName, # PowerShell or batch/cmd.exe code to execute. [string] $Command, # This indicates that the specified command string is pure PowerShell code (you will usually want single quotes around that to avoid escaping). [switch] $IsPSCommand, # Use this if the PowerShell code produces a base64-encoded string of a length greater than 260, so you get 'Argument to long' [SIC] from PsExec. This uses a temporary file that's created on the remote computer. [switch] $IsLongPSCommand, # Custom parameters for PsExec. [string] $CustomPsExecParameters = '', # PowerShell file in the local file system to be run via PsExec on the remote computer. [ValidateScript({Test-Path -Path $_ -PathType Leaf})][string] $PSFile = '', # Perform a DNS lookup. [switch] $Dns, # Pass in alternate credentials. Get-Help Get-Credential. [System.Management.Automation.PSCredential][System.Management.Automation.Credential()] $Credential = [System.Management.Automation.PSCredential]::Empty, # Attempt PsExec command even if ping fails. [switch] $ContinueOnPingFail, # Number of concurrent threads. [int] $ThrottleLimit = 8, # Do not display progress with Write-Progress. [switch] $HideProgress, # Timeout in seconds. Causes problems if too short. 60 as a default seems OK. Increase if doing a lot of processing with PsExec. [int] $Timeout = 60, # Do not display the end summary with start and end time, using Write-Host. [switch] $HideSummary) # PowerShell Invoke-PsExec ("PsExec Wrapper v2"). # Copyright (c) 2015-2017, Joakim Borger Svendsen, All rights reserved. Svendsen Tech. # Author: Joakim Borger Svendsen # MIT license - http://www.opensource.org/licenses/MIT # August 15, 2015. beta1 # August 23, 2015. beta2 # December 02, 2015, beta3, bug fixes, documentation # 2017-01-23 to -25: Making a module of it, v1.0, rearranging some stuff according to newly learned best practices.. # Setting throttle limit default to 8. The module will require PowerShell v3 due to $PSScriptRoot # being used. Wish I had used K&R-style blocks now, but keeping them because it's too much work for too little gain. # 2017-02-14: Trying to conform to PSScriptAnalyzer warnings. begin { Set-StrictMode -Version Latest $MyEAP = 'Stop' $ErrorActionPreference = $MyEAP $StartTime = Get-Date if ($PsExecExecutable = Get-Item -LiteralPath (Join-Path (Get-Location) 'PsExec.exe') -ErrorAction SilentlyContinue | Select-Object -ErrorAction SilentlyContinue -ExpandProperty FullName) { Write-Verbose -Message "Found PsExec.exe in current working directory. Using this PsExec.exe executable: '$PsExecExecutable'." } # Missing $PSScriptRoot in PSv2.. Abandoning v2 support for this module. #Write-Verbose -Message ("MyInvocation: " + ($MyInvocation.MyCommand.Path)) # doesn't exist in my PSv4 ... elseif ($PsExecExecutable = Get-Item -LiteralPath "$PSScriptRoot\PsExec.exe" -ErrorAction SilentlyContinue | Select-Object -ErrorAction SilentlyContinue -ExpandProperty FullName) { Write-Verbose -Message "Found PsExec.exe in directory script was called from. Using this PsExec.exe executable: '$PsExecExecutable'." } #> elseif ($PsExecExecutable = Get-Command -Name psexec -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1 | Select-Object -ExpandProperty Definition -ErrorAction SilentlyContinue) { Write-Verbose -Message "Found PsExec.exe in `$Env:PATH. Using this PsExec.exe executable: '$PsExecExecutable'." } else { Write-Error -Message "You need PsExec.exe from Microsoft's SysInternals suite to use this script. Either in the working dir, or somewhere in `$Env:PATH." -ErrorAction Stop return } $RunspaceTimers = [HashTable]::Synchronized(@{}) $Data = [HashTable]::Synchronized(@{}) $Runspaces = New-Object -TypeName System.Collections.ArrayList $RunspaceCounter = 0 Write-Verbose -Message 'Creating initial session state.' $ISS = [System.Management.Automation.Runspaces.InitialSessionState]::CreateDefault() $ISS.Variables.Add((New-Object -TypeName System.Management.Automation.Runspaces.SessionStateVariableEntry -ArgumentList 'RunspaceTimers', $RunspaceTimers, '')) $ISS.Variables.Add((New-Object -TypeName System.Management.Automation.Runspaces.SessionStateVariableEntry -ArgumentList 'Data', $Data, '')) Write-Verbose -Message 'Creating runspace pool.' $RunspacePool = [System.Management.Automation.Runspaces.RunspaceFactory]::CreateRunspacePool(1, $ThrottleLimit, $ISS, $Host) $RunspacePool.ApartmentState = 'STA' $RunspacePool.Open() # This is run for every computer. $PsExecScriptBlock = { [CmdletBinding()] param( [int] $ID, [string] $ComputerName, [string] $Command, [switch] $IsPSCommand, [switch] $IsLongPSCommand, [string] $CustomPsExecParameters, [string] $PSFile, [switch] $ContinueOnPingFail, [switch] $Dns, [string] $PsExecExecutable, [System.Management.Automation.PSCredential][System.Management.Automation.Credential()] $Credential) $RunspaceTimers.$ID = Get-Date if (-not $Data.ContainsKey($ComputerName)) { $Data[$ComputerName] = New-Object -TypeName PSObject -Property @{ ComputerName = $ComputerName } } if ($Dns) { Write-Verbose -Message "${ComputerName}: Performing DNS lookup." $ErrorActionPreference = 'SilentlyContinue' $HostEntry = [System.Net.Dns]::GetHostEntry($ComputerName) $Result = $? $ErrorActionPreference = $MyEAP #Write-Verbose -Message "`$Result from DNS lookup: $Result (type: $($Result.GetType().FullName))" # It looks like it's sometimes "successful" even when it isn't, for any practical purposes (pass in IP, get the same IP as .HostName)... if ($Result) { ## This is a best-effort attempt at handling things flexibly. if ($HostEntry.HostName.Split('.')[0] -ieq $ComputerName.Split('.')[0]) { $IPDns = @($HostEntry | Select-Object -ExpandProperty AddressList | Select-Object -ExpandProperty IPAddressToString) } else { $IPDns = @(@($HostEntry.HostName) + @($HostEntry.Aliases)) } $Data[$ComputerName] | Add-Member -MemberType NoteProperty -Name 'IP/DNS' -Value $IPDns } else { $Data[$ComputerName] | Add-Member -MemberType NoteProperty -Name 'IP/DNS' -Value $Null } } Write-Verbose -Message "${ComputerName}: Pinging." if (-not (Test-Connection -ComputerName $ComputerName -Count 1 -Quiet)) { $Data[$ComputerName] | Add-Member -MemberType NoteProperty -Name Ping -Value $False if (-not $ContinueOnPingFail) { continue } } else { $Data[$ComputerName] | Add-Member -MemberType NoteProperty -Name Ping -Value $True } if ($null -ne $Credential.Username) { [string] $CommandString = "-u `"$($Credential.Username)`" -p `"$($Credential.GetNetworkCredential().Password)`" /accepteula $CustomPsExecParameters \\$ComputerName" } else { [string] $CommandString = "/accepteula $CustomPsExecParameters \\$ComputerName" } if ($IsLongPSCommand -or $PSFile) { if ($IsLongPSCommand) { $TempPSFile = [System.IO.Path]::GetTempFileName() $Command | Out-File -LiteralPath $TempPSFile } elseif ($PSFile) { $TempPSFile = $PSFile } # Try to handle multiple people running the script at the same time (race condition not handled, but it's better than nothing). $Destination = "\\${ComputerName}\ADMIN`$\SvendsenTechInvokePsExecTemp.ps1" if (Test-Path -LiteralPath $Destination) { Write-Verbose -Message "${ComputerName}: Destination file '$Destination' already exists. Tacking on numbers until it doesn't." [bool] $GotAvailableFileName = $False foreach ($i in 0..10000) { $TempDest = $Destination -replace '\.ps1$', "$i.ps1" if (-not (Test-Path -LiteralPath $TempDest)) { $Destination = $TempDest $GotAvailableFileName = $True break } } if (-not $GotAvailableFileName) { Write-Warning -Message "${ComputerName}: All 10,000 temp file names already present in the file system. What are you up to? Skipping this computer." continue } } try { Copy-Item -LiteralPath $TempPSFile -Destination $Destination -ErrorAction Stop } catch { Write-Warning -Message "${ComputerName}: Unable to copy (temporary) PowerShell script file to destination: '$Destination': $_" if ($IsLongPSCommand) { Write-Verbose -Message "${ComputerName}: Deleting local temporary PS script file: '$TempPSFile'." Remove-Item -LiteralPath $TempPSFile -Force -ErrorAction Continue } continue } if ($IsLongPSCommand) { Write-Verbose -Message "${ComputerName}: Deleting temporary PS script file: '$TempPSFile'." Remove-Item -LiteralPath $TempPSFile -Force -ErrorAction Continue } $CommandString += " cmd /c `"echo . | powershell.exe -ExecutionPolicy Bypass -File $Env:SystemRoot\$($Destination.Split('\')[-1])`"" } elseif ($IsPSCommand) { $EncodedCommand = [System.Convert]::ToBase64String([System.Text.Encoding]::Unicode.GetBytes($Command)) $CommandString += " cmd /c `"echo . | powershell.exe -ExecutionPolicy Bypass -EncodedCommand $EncodedCommand`"" } else { $CommandString += " cmd /c `"$Command`"" } $TempFileNameSTDOUT = [System.IO.Path]::GetTempFileName() $TempFileNameSTDERR = [System.IO.Path]::GetTempFileName() Write-Verbose -Message "${ComputerName}: Running PsExec command." $Result = Start-Process -FilePath $PsExecExecutable -ArgumentList $CommandString -Wait -NoNewWindow -PassThru -RedirectStandardOutput $TempFileNameSTDOUT -RedirectStandardError $TempFileNameSTDERR -ErrorAction Continue $Data[$ComputerName] | Add-Member -MemberType NoteProperty -Name ExitCode -Value $Result.ExitCode $Data[$ComputerName] | Add-Member -MemberType NoteProperty -Name STDOUT -Value ((Get-Content -LiteralPath $TempFileNameSTDOUT) -join "`n") #Write-Verbose -Message ('Content of temp STDERR file: ' + ((Get-Content -LiteralPath $TempFileNameSTDERR) -join "`n")) $Data[$ComputerName] | Add-Member -MemberType NoteProperty -Name STDERR -Value ((Get-Content -LiteralPath $TempFileNameSTDERR) -join "`n") Write-Verbose -Message "${ComputerName}: Deleting local STDOUT temporary file: '$TempFileNameSTDOUT'." Remove-Item -LiteralPath $TempFileNameSTDOUT -Force -ErrorAction Continue Write-Verbose -Message "${ComputerName}: Deleting local STDERR temporary file: '$TempFileNameSTDERR'." Remove-Item -LiteralPath $TempFileNameSTDERR -Force -ErrorAction Continue if ($IsLongPSCommand -or $PSFile) { Write-Verbose -Message "${ComputerName}: Deleting remote temporary PowerShell file: '$Destination'." Remove-Item -LiteralPath $Destination -ErrorAction Continue } } function Get-Result { [CmdletBinding()] param( [switch] $Wait ) do { $More = $false foreach ($Runspace in $Runspaces) { $StartTime = $RunspaceTimers[$Runspace.ID] if ($Runspace.Handle.IsCompleted) { #Write-Verbose -Message ('Thread done for {0}' -f $Runspace.IObject) $Runspace.PowerShell.EndInvoke($Runspace.Handle) $Runspace.PowerShell.Dispose() $Runspace.PowerShell = $null $Runspace.Handle = $null } elseif ($null -ne $Runspace.Handle) { $More = $true } if ($Timeout -and $StartTime) { if ((New-TimeSpan -Start $StartTime).TotalSeconds -ge $Timeout -and $Runspace.PowerShell) { Write-Warning -Message ('Timeout {0}' -f $Runspace.IObject) $Runspace.PowerShell.Dispose() $Runspace.PowerShell = $null $Runspace.Handle = $null } } } if ($More -and $PSBoundParameters['Wait']) { Start-Sleep -Milliseconds 100 } foreach ($Thread in $Runspaces.Clone()) { if (-not $Thread.Handle) { Write-Verbose -Message ('Removing {0} from runspaces' -f $Thread.IObject) $Runspaces.Remove($Thread) } } if (-not $HideProgress) { $ProgressSplatting = @{ Activity = 'Running PsExec Commands' Status = 'Processing: {0} of {1} total threads done' -f ($RunspaceCounter - $Runspaces.Count), $RunspaceCounter PercentComplete = ($RunspaceCounter - $Runspaces.Count) / $RunspaceCounter * 100 } Write-Progress @ProgressSplatting } } while ($More -and $PSBoundParameters['Wait']) } # end of Get-Result } process { foreach ($Computer in $ComputerName) { Write-Verbose -Message "Processing $Computer." ++$RunspaceCounter $psCMD = [System.Management.Automation.PowerShell]::Create().AddScript($PsExecScriptBlock) [void] $psCMD.AddParameter('ID', $RunspaceCounter) [void] $psCMD.AddParameter('ComputerName', $Computer) [void] $PSCMD.AddParameter('Command', $Command) [void] $PSCMD.AddParameter('IsPSCommand', $IsPSCommand) [void] $PSCMD.AddParameter('CustomPsExecParameters', $CustomPsExecParameters) [void] $PSCMD.AddParameter('PSFile', $PSFile) [void] $PSCMD.AddParameter('IsLongPSCommand', $IsLongPSCommand) [void] $PSCMD.AddParameter('Dns', $Dns) [void] $PSCMD.AddParameter('PsExecExecutable', $PsExecExecutable) [void] $PSCMD.AddParameter('ContinueOnPingFail', $ContinueOnPingFail) [void] $PSCMD.AddParameter('Credential', $Credential) [void] $psCMD.AddParameter('Verbose', $VerbosePreference) $psCMD.RunspacePool = $RunspacePool [void]$Runspaces.Add(@{ Handle = $psCMD.BeginInvoke() PowerShell = $psCMD IObject = $Computer ID = $RunspaceCounter }) Get-Result } } end { Get-Result -Wait if (-not $HideProgress) { Write-Progress -Activity 'Running PsExec Commands' -Status 'Done' -Completed } Write-Verbose -Message "Closing and disposing runspace pool." $RunspacePool.Close() $RunspacePool.Dispose() [hashtable[]] $PsExecProperties = @{ Name = 'ComputerName'; Expression = { $_.Name } } if ($Dns) { $PsExecProperties += @{ Name = 'IP/DNS'; Expression = { $_.Value.'IP/DNS' } } } $PsExecProperties += @{ Name = 'Ping'; Expression = { $_.Value.Ping } }, @{ Name = 'ExitCode'; Expression = { $_.Value.ExitCode } }, @{ Name = 'STDOUT'; Expression = { $_.Value.STDOUT } }, @{ Name = 'STDERR'; Expression = { $_.Value.STDERR } } $Data.GetEnumerator() | Select-Object -Property $PsExecProperties Write-Verbose -Message '"Exporting" $Global:STPsExecData and $Global:STPsExecDataProperties' $Global:STPsExecData = $Data $Global:STPsExecDataProperties = $PsExecProperties if (-not $HideSummary) { Write-Host -ForegroundColor Green ('Start time: ' + $StartTime) Write-Host -ForegroundColor Green ('End time: ' + (Get-Date)) } } } |