Add Windows Host

Prerequisites for adding the Windows Host to CHAI™ for discovery and transform¶

Recommended resource requirements¶

Resource	CPU	RAM	Disk space
Requirement	4 cores	8 GB	>20 GB in C:\ drive

Administrative access on host¶

You account used for authenticating with Windows Host from CHAI™ should have Administrator rights.

PowerShell Version 3+¶

CHAI™ connects to the Windows Host over the network using WinRM ( Windows Remote Management ) and it has a dependency on underneath PowerShell version. The minimum version required is 3.

⚠️ Windows 2012 R2, 2016 and 2022 are supported out of box and hence no installation of PowerShell is required.

OS	PS Version 3	PS Version 4	PS Version 5
2012	-	Default	-
2016	-	-	Default

Verify PowerShell version as below

C:\>$PSVersionTable.PSVersion
Output:
Major Minor Build Revision
----- ----- ----- --------
3     0     -1    -1

Remote Execution Policy¶

Execute the command Get-ExecutionPolicy -List and verify if you get similar output

PS> Get-ExecutionPolicy -List
    Scope ExecutionPolicy
    ----- ---------------
    MachinePolicy Undefined
    UserPolicy Undefined
    Process Undefined
    CurrentUser Undefined
    LocalMachine RemoteSigned

If you see LocalMachine Undefined then set the said policy to "RemoteSigned" using the following powershell command.

PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine

Verify the updated policy as follows.

PS> Get-ExecutionPolicy -List
    Scope ExecutionPolicy
    ----- ---------------
    MachinePolicy Undefined
    UserPolicy Undefined
    Process Undefined
    CurrentUser Undefined
    LocalMachine RemoteSigned

Configure WinRM¶

The following other pre-requisites also needed to be enabled.

Enable PSRemoting
Set WinRM to run with following configuration:
- Basic authentication for server.
- Port 5986 is open.

CHAI™ uses a PowerShell script that will ensure all the above prerequisites are set.

Kindly download the official PowerShell script on your Windows Host and save it as "ConfigureRemoting.ps1". This configuration script is officially provided and maintained by Ansible.

The core functions of the script are as below:

Checks Administrative Privileges: Verifies that the script is running with elevated Administrator privileges before making system changes.
Enables WinRM Service: Starts the Windows Remote Management service and sets its startup type to Automatic.
Enables PowerShell Remoting: Runs the native Enable-PSRemoting command to prepare the operating system for incoming connections.
Generates a Self-Signed SSL Certificate: Creates a 4096-bit self-signed TLS/SSL certificate to encrypt data sent over the network.
Configures an HTTPS Listener: Binds the generated certificate to a WinRM HTTPS listener (listening on port 5986).
Modifies Local Accounts Policy: Adjusts the LocalAccountTokenFilterPolicy registry key to allow local administrative users to connect remotely.
Opens Windows Firewall: Creates or updates firewall rules to allow traffic through TCP ports 5985 (HTTP) and 5986 (HTTPS).
Validates Configuration: Runs a quick connection test back to localhost to confirm that HTTP and HTTPS remoting sessions work perfectly.

Execute the script as follows:

PS C:\> .\ConfigureRemoting.ps1
    Self-signed SSL certificate generated; thumbprint: 89E65FE46301E79A5A583244945201C3A72FCEDE
    wxf: http://schemas.xmlsoap.org/ws/2004/09/transfer
    a : http://schemas.xmlsoap.org/ws/2004/08/addressing
    w : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
    Lang : en-US
    Address: http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
    ReferenceParameters : ReferenceParameters
    Ok.

Disable UAC remote restrictions¶

⚠️ Skip the below steps if you are using AD user or domain user to login to host

A. Open windows powershell as an Administrator and execute below command

  Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System" -Name "LocalAccountTokenFilterPolicy" -Value 1

OR¶

B. Manually disable it as follows

Click Start, click Run, type regedit, and then press Enter.
Locate and then click the following registry subkey: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System
If the LocalAccountTokenFilterPolicy registry entry doesn't exist, follow these steps
- Right-click on blank white area, click New, and then select DWORD Value.
- Type LocalAccountTokenFilterPolicy, and then press Enter.
Right-click LocalAccountTokenFilterPolicy, and then select Modify.
In the Value data box, type 1, and then select Ok.
Exit Registry Editor.

Whitelist winchtoolpy.exe in the AntiVirus Software¶

If the Windows host is running an AntiVirus software, add winchtoolpy.exe to the AntiVirus Software whitelist

Connection between Host and CHAI™¶

CHAI™ authenticates with the Windows Host using the following 2 methods over winRM,

Kerberos
Username and password

Host communicates back to CHAI™ over port 443 ( https ). Please ensure that port 443 is enabled on the Host for external communication and unblocked on the firewall in between Host and CHAI™.

Connection between Discovery Host and Windows Build Box¶

⚠️ If the config setting for "TrustedHosts" are not managed by policies then no change required. - If the config setting for "TrustedHosts" is managed by policies then the policy would need to be set to "Not Configured" in order to change the config setting.

Config settings could be set as "Not Configured" using "Local Group Policy Editor" (gpedit.msc) at

Computer Configuration\Policies\Administrative Templates\Windows Components\Windows Remote Management(WinRM)\WinRM Client\Trusted Hosts

- To reflect the changes gpupdate /force command needs to be executed using powershell