Discovering Windows hosts by using PowerShell
Windows host discovery by using PowerShell
PowerShell discovery requires a valid PowerShell credential for the host to be discovered.
BMC Helix Discovery looks for open PowerShell ports on the target host. If open PowerShell ports are available, BMC Helix Discovery attempts to connect to the PowerShell API over https and uses the PowerShell credential to log in. PowerShell can be used over HTTP, and the content returned is encrypted. Using HTTP with Basic authentication makes it possible for credentials to be compromised. We recommend you use NTLM (Negotiate) authentication.
PowerShell discovery can also discover hosts using Windows Just Enough Administration (JEA). To do this you must configure JEA on the target hosts, see Additional JEA configuration in this topic. You must also enable JEA in the credential, and specify the JEA Endpoint. For more information, see Adding-credentials.
PowerShell discovery from BMC Discovery Outposts
PowerShell discovery proceeds through a BMC Discovery Outpost. In BMC Helix Discovery, PowerShell is the preferred method of discovering Windows hosts. Where a PowerShell credential is available, it is used in preference to any other Windows credential. Where a PowerShell credential is not available, the BMC Discovery Outpost runs the PowerShell commands by using the existing Windows AD credentials. If the request for connection fails, the BMC Discovery Outpost tries WMI and RemQuery credentials to connect with PowerShell. Many PowerShell commands access WMI objects, so it is important that WMI is available and can be used by PowerShell.
The order of precedence for Windows discovery methods is:
- Powershell > WMI > RemQuery > SNMP
You manage Record and Playback modes for PowerShell discovery from the BMC Discovery Outpost.
PowerShell cmdlets
PowerShell commands are referred to as cmdlets. When additional software is installed on a Windows host, such as Exchange, often additional Exchange-related cmdlets are installed into PowerShell on that host, and are available for PowerShell discovery. However, additional cmdlets might require additional permissions.
PowerShell versions
Windows Remote Management was introduced in Server 2003 SP1. Windows Remote Management should work with PowerShell versions 3 and 4. Windows Remote Management does work in PowerShell version 5 which is the version that we recommend. PowerShell version 5 is a requirement for Windows host discovery by using JEA and PowerShell.
BMC Helix Discovery supports PowerShell 3.0 or later. This is equivalent to Windows Server 2012 or later. Where RemQuery runs powershell.exe on a target host, earlier PowerShell versions might provide usable results.
How to discover Windows hosts by using PowerShell
The following video (03:39) provides an introduction to discovering Windows hosts by using PowerShell.
Before you begin
- The target hosts that you intend to discover must have the Windows Remote Management (WS-Management) service running. The service is enabled by default on modern Windows Server OSs, and you need not make any additional configuration on the target. However, for desktops, or where the WS-Management service is disabled, you must run the Windows Remote Management service. To run the Windows Remote Management service, perform one of the following steps:
Start the Windows Remote Management (WS-Management) service using a domain-wide policy, or for individual hosts, start the service using the following PowerShell cmdlet:
Enable-PSRemoting- Open the Windows Control Panel, access the Services tool, search for the Windows Remote Management (WS-Management) service, right-click the service, and select Start.
- Confirm that Windows Remote Management is allowed by the Windows Firewall.
Authentication uses AD, so by default only domain hosts can connect. You can add BMC Discovery Outposts by IP address using the following cmdlet:
Set-Item WSMan:\localhost\Client\TrustedHosts -Value "x.x.x.x"where "x.x.x.x" is the IP address of the BMC Discovery Outpost. See these Microsoft resources for more information:
- By default, only Administrator, or permitted accounts using JEA can connect by using PowerShell remoting. For Windows Server 2012 and later, you can enable individual user accounts to connect by adding them to the Remote Management Users group. Adding users can also be managed by using a Group policy.
Additional configuration for discovery by using JEA
Windows JEA enables administrators to permit non-administrator users to execute specific cmdlets (commands) and external processes, without granting them full administrative privileges. By using JEA in BMC Helix Discovery, you can discover Windows hosts without providing credentials with full administrator access.
JEA is supported for the following credential types:
- PowerShell
- Active Directory
Windows host discovery by using JEA and PowerShell requires the following:
- PowerShell 5.0 or Windows Management Framework 5.1 must be installed on the target Windows hosts.
JEA must be configured on the target Windows hosts. The following parameters must be specified in the JEA session configuration file:
language = 'FullLanguage'
session type = 'Default'
See the Microsoft article Registering JEA Configurations - PowerShell for more information.
To verify that a target was discovered by using JEA
To verify that a target was discovered by using JEA, perform one of the following steps:
- Log in to the target Windows host and verify that a new log/transcript file is present in the Transcripts folder. Transcription should be enabled and the directory set in the host's session configuration file by using the TranscriptDirectory parameter.
- In the UI, open the DiscoveryAccess-page for the scanned Windows target host and verify that the "PowerShell" protocol was used for discovery.
Troubleshooting
Cannot discover a host by using PowerShell
If you cannot discover a host that you expect to by using PowerShell, it is possible that the Windows Remote Management (WS-Management) service is not running. Verify this for the host by using the following PowerShell command on your local Windows host:
Enter-PSSession -ComputerName DISC-QA03.test.lab -Credential DOMAINNAME\Administrator
Cannot discover a host by using JEA
If you are using JEA, confirm that it is correctly configured on the target host. Confirm that the session configuration file has the following parameters defined:
session type = 'Default'
Further troubleshooting information is provided in Troubleshooting-PowerShell-discovery-issues.
Known issue
If the connection is lost when the PowerShell script is running, the script might be unable to resume, and fails to time out. This issue is being tracked on the PowerShell GitHub project.