Setting up PowerShell discoveries with TADDM

With the release of TADDM 7.3.0.2 came the ability to perform Windows discoveries with PowerShell instead of WMI. In comparison with WMI a PowerShell session sends fewer requests to access target systems, which in turn reduces the number of events that are logged. In addition if you use SSL it should also be more secure.

In this blog I will look at both the standard set-up and then how to extend the discovery to use SSL.

Discovery Server Set-Up

There are several changes that need to be made on each discovery server that are required in order to enable PowerShell usage and control the prioritization. All of these settings are in collation.properties on the discovery server (found in $COLLATION_HOME/etc).

Let’s look at these one by one:

Parameter Value Description
com.collation.PowerShellAccessEnabled true This needs to be set to true to enable the PowerShell usage. Without this it will not attempt discovery.
com.ibm.cdb.discover.PreferScriptDiscovery true The PowerShell session can be used only with the script-based sensors. If you want to start using the PowerShell session, you must enable it because it is disabled by default.
com.collation.PowerShellPorts 5985,

5986

This property specifies the PowerShell ports. By default, ports 5985 and 5986 are specified. The PortSensor checks whether these ports are active. If the ports are active, the PowerShell session can be established. If the ports are not active, the WMI session is used instead, unless you disabled it. In such case, error messages are displayed.
com.collation.PreferPowerShellOverWMI true This property specifies whether to use the PowerShell or the WMI session, if both of them are enabled. By default, the PowerShell session is preferred.  This is a scope-based property. You can override the global value for a specific scope set or IP in the collation.properties file.

e.g.

com.collation.PreferPowerShellOverWMI.myScopeABC= false

com.collation.PreferPowerShellOverWMI.10.100.27.8= true

com.ibm.cdb.session.ps.allowDNS true This property specifies whether the PowerShell script uses DNS on the gateway to resolve the IP of the remote host. By default, the usage of DNS is allowed
com.ibm.cdb.session.ps.fallbackToIP true This property specifies whether the PowerShell script falls back to IP when a secure session cannot be established by using FQDN. By default, the PowerShell script falls back to IP.  This is also a scope-based property.
com.collation.PowerShellTimeoutFudge 10000 This property specifies the time after which SSH protocol times out, starting with the timeout of the Powershell script. By default, when the Powershell script times out, the SSH protocol times out 10000 milliseconds later.
com.ibm.cdb.session.ps.urlPrefix wsman This property specifies the value of the URLPrefix property of a WinRM listener on the discovered Windows system. The value of this property and the URLPrefix property on the Windows targets must be the same. This is a scope-based property.

This only came in at FixPack 3.

com.ibm.cdb.session.ps.useSSL false This property specifies whether the PowerShell script uses the SSL protocol to connect to the remote host. By default, the SSL protocol is not used. This is a scope-based property.

e.g.

com.collation.PowerShellAccessEnabled=true
com.ibm.cdb.discover.PreferScriptDiscovery=true
com.collation.WmiAccessEnabled=true
com.collation.PreferPowerShellOverWMI=true
com.collation.PowerShellPorts=5985,5986
com.ibm.cdb.session.ps.useSSL=false
com.ibm.cdb.session.ps.allowDNS=true
com.ibm.cdb.session.ps.fallbackToIP=true
com.collation.PowerShellTimeoutFudge=10000
com.ibm.cdb.session.ps.urlPrefix=wsman

Once you have made these changes restart the discovery server with the control restart command.

Gateway Setup

To setup the gateway for PowerShell you need to do fulfil the following pre-requisites:

  1. A dedicated Windows Server computer system is required to serve as the gateway.
  2. You must install PowerShell version 2, or later, on the gateway and the target systems. Only targets that run Windows Server 2008, or later, are supported.
  3. You must configure the gateway by running the following command

Set-Item WSMan:\localhost\Client\TrustedHosts * -Force

This command sets the trustedHosts list. By default, the list exists but it is empty, so it must be set before the remote session is opened. With the -Force parameter, PowerShell executes the command without prompting you for each step.

Please note that this command could have security implications. To run PowerShell securely use SSL (detailed below)

  1. You must configure the target systems by opening a PowerShell session and running the following command:

Enable-PSRemoting -Force

This command starts the WinRM service, sets it to start automatically with your system, and creates a firewall rule to allow the incoming connections. With the -Force parameter, PowerShell executes these actions without prompting you for each step.

SSL Discovery

If you decide that PowerShell is not secure enough then you can use SSL (Secure Sockets Layer). To do this change the following parameter in collation.properties

com.ibm.cdb.session.ps.useSSL true This property specifies whether the PowerShell script uses the SSL protocol to connect to the remote host. By default, the SSL protocol is not used. This is a scope-based property.

On the machine to be discovered

Create the Certificate

To secure the connection a certificate needs to be created inside the system to be discovered. For this example, we need a self-signed certificate.

During the creation, you need to provide a DNS name for your server. This should be the name that your system resolves to on the TADDM gateway.

  1. Open a PowerShell prompt as Administrator
  2. Run the following command:

New-SelfSignedCertificate -DnsName <your_server_dns_name> -CertStoreLocation Cert:\LocalMachine\My

Create the Listener

By default WinRM over HTTP is configured to listed on 5985. We need to enable it on 5986 and bind the certificate.

  1. Open a command prompt window as Administrator (not PowerShell)
  2. Run the following command, pasting your new certificate’s thumbprint into the command (all on one line):

winrm create winrm/config/Listener?Address=*+Transport=HTTPS @{Hostname=”WIN-RIT675L12G3″; CertificateThumbprint=”1EE4A3851FC4EE3C50A58D0BBC830252C71F43E2″}

Export the certificate

The certificate we have created needs to be copied to the gateway.

  1. Open a PowerShell prompt as Administrator.
  2. Run the following command, to set the correct location.

PS C:\Users\orbdata> set-location cert:\localmachine\my

  1. This will set the correct location to export the certificate. Now list the certificate or certificates on this system . We are looking for the same one we used for the listener.

PS Cert:\localmachine\my> get-childitem

Directory: Microsoft.PowerShell.Security\Certificate::localmachine\my

Thumbprint                                Subject

———-                                ——-

F06C726A629F203FEA9D5FE5C20BE4BB78DEBD21  CN=WIN-RIT675L12G3

1EE4A3851FC4EE3C50A58D0BBC830252C71F43E2  CN=WIN-RIT675L12G3

009DBB1E3FF5EE5A3731240D082364A81A8A8DBB  CN=WIN-RIT675L12G3

  1. In our case it is the second one. Now we can set this certificate into a variable so it is easier to export.

PS Cert:\localmachine\my> $selectedcert = (Get-ChildItem -Path cert:\LocalMachine\My\1EE4A3851FC4EE3C50A58D0BBC830252C71F43E2)

  1. Then using this variable, we can export the certificate.

PS Cert:\localmachine\my> Export-Certificate -Cert $selectedcert -FilePath c:\taddm.cer

Directory: C:\

Mode                LastWriteTime     Length Name

—-                ————-     —— —-

-a—          9/8/2017   2:15 PM        814 taddm.cer

  1. Lastly copy this certificate file to the gateway using a windows share or some other copying mechanism of your choice.

On the gateway

We now need to import the created certificate on the TADDM gateway.

  1. Open a PowerShell command prompt window as Administrator
  2. Run the following commands, to set the correct location.

PS C:\Windows\system32> Import-Certificate -FilePath “c:\certs\taddm.cer” -CertStoreLocation “Cert:\LocalMachine\Root”

Directory: Microsoft.PowerShell.Security\Certificate::LocalMachine\Root

Thumbprint                                Subject

———-                                ——-

1EE4A3851FC4EE3C50A58D0BBC830252C71F43E2  CN=WIN-RIT675L12G3

Test the connection

Lastly we need to test the SSL connection from the TADDM gateway to the target.

  1. Open a PowerShell command prompt window as Administrator
  2. Run the following commands, to set the correct location.

$so = New-PsSessionOption –SkipCACheck -SkipCNCheck
Enter-PSSession -ComputerName <ip_address_or_dns_name_of_server>  -Credential <local_admin_username> -UseSSL -SessionOption $so

This should prompt you for a password and then show the prompt of the remote system. If it does not then it is not working.

Run a Discovery

Lastly we should be able to run a discovery of the new system. If you look at the image below you can see that my sessionsensor is using port 5986 (SSL) to do the discovery which is what we want and you can also see that is has used PowerShell (PS) successfully.

Debugging

Ports

The first thing to check is what ports the Port Sensor detects on the target. If ports 5985 or 5986 are not detected then PowerShell remoting is not configured.

Check that you have started PowerShell remoting and if you are using SSL that you have configured a listener.

Error CTJTD1622E

If you get the error

CTJTD1622E Failed to discover Windows computer system. Only script-based Windows computer system sensor can be run with PowerShell session.

Then you need to configure the discovery server for Script Based discovery (See earlier in this blog).

Logs

The best logfile to use is the SessionSensor log on the anchor itself. To see debugging on the anchor set the following setting and restart the discovery server.

com.collation.log.level.vm.Anchor=DEBUG

Once this has been done and you have re-run the discovery look in the SessionSensor logfile for the target in c:\windows\temp\TADDM7.3.0.3\anchor\logs\sensors for the command powershellSession.ps1.

This script gets copied into c:\Windows\Temp\taddm.xxxxx (where xxxxx is different on each system) and is run to execute TADDM commands.

For example in my setup I found this output.

powershellSession.ps1 -user Administrator -password 43028e530bd7796f9e -ip 192.168.237.225 -port 5986 -urlPrefix wsman -useSSL -allowDNS -fallbackToIP  -remoteCommand Base64
!DEBUG MSG! Specified user: Administrator
!DEBUG MSG! Specified remote IP: 192.168.237.225
!DEBUG MSG! Specified remote port: 5986
!DEBUG MSG! Specified remote URL prefix: wsman
!DEBUG MSG! Specified useSSL: True
!DEBUG MSG! Specified allowDNS: True
!DEBUG MSG! Specified fallbackToIP: True
!DEBUG MSG! Specified remote command: Base64
!DEBUG MSG! Remote IP 192.168.237.225 resolves to: WIN-RIT675L12G3.localdomain
!DEBUG MSG! Trying to create secure Powershell session by using FQDN.
!DEBUG MSG! Cannot create Powershell session by using FQDN.
!DEBUG MSG! Trying to create secure Powershell session by using IP.
!ERROR MSG! Failed to create PowerShell session: [192.168.237.225] Connecting to remote server 192.168.237.225 failed with the following error message : The server certificate on the destination computer (192.168.237.225:5986) has the following errors:
!ERROR MSG! The SSL certificate contains a common name (CN) that does not match the hostname. For more information, see the about_Remote_Troubleshooting Help topic.

If you look at this error it says

“The SSL certificate contains a common name (CN) that does not match the hostname”.

The IP has resolved to WIN-RIT675L12G3.localdomain which in my case is not correct. If you remember the examples earlier I used WIN-RIT675L12G3 as the DNS name. To fix this on my system I changed the hosts file and after the next run I got the following output in the logfile and the discovery worked.


2017-09-08 17:43:12,929  [Thread: 3] 2017090817403175#SessionSensor-192.168.237.225-[135,445,5986] DEBUG util.OsCommand – execute(cmd.exe /C echo ” | cmd.exe /c powershell.exe Invoke-Command -ScriptBlock {Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Force -Scope Process; $job = Start-Job -ScriptBlock { C:\WINDOWS/temp/taddm.f7082x/powershellSession.ps1 -user Administrator -password 43028e530bd7796f9e -ip 192.168.237.225 -port 5986 -urlPrefix wsman -useSSL -allowDNS -fallbackToIP  -remoteCommand Base64_ZQBjAGgAbwAgACIAVgBlAHIAaQBmAHkAaQBuAGcAIABQAG8AdwBlAHIAUwBoAGUAbABsACAAcwBlAHMAcwBpAG8AbgAiAA==}; if (! (Wait-Job $job -Timeout 120)) {Write-Host “!ERROR MSG! Command timed out”}; Receive-Job $job; Remove-Job -force $job} ): output=
!DEBUG MSG! Specified user: Administrator
!DEBUG MSG! Specified remote IP: 192.168.237.225
!DEBUG MSG! Specified remote port: 5986
!DEBUG MSG! Specified remote URL prefix: wsman
!DEBUG MSG! Specified useSSL: True
!DEBUG MSG! Specified allowDNS: True
!DEBUG MSG! Specified fallbackToIP: True
!DEBUG MSG! Specified remote command: echo “Verifying PowerShell session”
!DEBUG MSG! Remote IP 192.168.237.225 resolves to: WIN-RIT675L12G3
!DEBUG MSG! Trying to create secure Powershell session by using FQDN.
!DEBUG MSG! Powershell session to host WIN-RIT675L12G3 created.
!DEBUG MSG! Directly executing remote command
!DEBUG MSG! Executed remote command
Verifying PowerShell session
!DEBUG MSG! Execution finished.

If you want to know exactly what it was executing look at my blog on decoding TADDM Base64 commands here.

I hope this blog has been useful. If you have any improvements or recommendations then please let me know.

Visits: 403