discovery.runPowerShell
discovery.runPowerShell(target, script, restrict_paths)
Returns a DiscoveredCommandResult node containing the result of running the specified PowerShell script.
The function takes the following parameters:
- target, where target is:
- a node used to identify the discovery target; one of the following nodes:
- Host
- DiscoveryAccess
- DiscoveredDirectoryEntry
- DiscoveredFQDN
- DiscoveredHBA
- DiscoveredListeningPort
- DiscoveredNetworkConnection
- DiscoveredNetworkInterface
- DiscoveredProcess
- DiscoveredSNMPRow
- DiscoveredWMI
- SQLResultRow
- DirectoryListing
- DiscoveredPackages
- DiscoveredSNMPTable
- DiscoveredWMIQuery
- FQDNList
- HBAInfoList
- IntegrationResult
- InterfaceList
- NetworkConnectionList
- ProcessList
- DeviceInfo
- DiscoveredCommandResult
- DiscoveredFile
- DiscoveredPatches
- DiscoveredRegistryValue
- DiscoveredSNMP
- HostInfo
- Or a data source against which the request is performed. See also, discovery-dataSource.
- a node used to identify the discovery target; one of the following nodes:
- script is the PowerShell script to run.
- restrict_paths is a string or list of strings that are checked against the any path restrictions that are configured. The system prevents execution of any commands accessed using matching paths. The restrict_paths parameter enables you to validate that paths determined in your pattern are not restricted, so your pattern is free to use command on those paths.
The following code examples shows discovery.runPowerShell being used to determine the time zone and daylight saving information of a Windows host. This comes from the TKU Microsoft.WindowsHost pattern module.
// *command_info_start
// command_windows := "powershell.exe Get-TimeZone"
// reason := "Determine time zone of host"
// when := "Always"
// *command_info_end
ps_out := discovery.runPowerShell(host, "Get-TimeZone");
if ps_out and ps_out.result then
// Time Zone attribute
time_zone := regex.extract(ps_out.result,
regex"StandardName\s*\:\s*([\w\s]+ Time)",
raw '\1');
// Supports Daylight Saving attribute
dst_raw := regex.extract(
ps_out.result,
regex"SupportsDaylightSavingTime\s*\:\s*((?:True|False))",
raw '\1');
if dst_raw then
if dst_raw = "True" then
supports_dst := true;
else
supports_dst := false;
end if;
end if;
end if;
Format of PowerShell session output
There are some differences between running PowerShell scripts using a remote session and running powershell.exe on the local machine. The main issue to be aware of is how output will be formatted. Unlike UNIX shells which largely pipe text from one command to another, PowerShell passes objects around. When a command, or “pipeline” in PowerShell terms, completes, the result is an object (or multiple objects) so powershell.exe automatically converts those objects to strings for display. When using a PS remote session, this automatic conversion does not happen; the session receives the objects themselves. Currently BMC Discovery attempts to convert those objects into strings for parsing, and so on, but for some objects the results are different.
For example, if you run Get-TimeZone in PowerShell on a local Windows host you receive output in this form:
Id : GMT Standard Time
DisplayName : (UTC+00:00) Dublin, Edinburgh, Lisbon, London
StandardName : GMT Standard Time
DaylightName : GMT Summer Time
BaseUtcOffset : 00:00:00
SupportsDaylightSavingTime : True
However, if you run Get-TimeZone over a remote session from BMC Discovery you receive a simpler value:
While the object received by BMC Discovery has all the data, it is not in a string format and there is no information with which to replicate the expected format. The format could be approximated, but the fields, for example, would be in a random order.
The way around all this is to explicitly format results into strings using cmdlets like Out-String. In the example above, changing the command to Get-TimeZone | Out-String returns the expected format by using PS remoting and running powershell.exe on the machine by using RemQuery.