Windows / PowerShell
Incorporating Windows PowerShell into your Discovery enhances vScope’s ability to collect information from the operating systems of Windows servers or clients.
Using PowerShell, instead of WMI over DCOM or WinRM, allows for a more flexible inventory, including the capability to customize the collection of Windows Registry Keys. Furthermore, PowerShell enables the use of Microsoft’s JEA (Just Enough Administration) for more efficient permission management and GMSA for seamless authentication in your environment.
Adding Windows OS (PowerShell)
Notice: Administrator privileges are required to add Windows OS to vScope.
- Go to Discovery > Credentials.
- Click Create Credential, and select Windows (PowerShell).
- Configure your Integration Settings by adding the credential details. You can reuse an existing credential, or create a new one from scratch.
- Select the target to be discovered by this credential and click Create.
Good job! You have now configured Windows OS inventory using PowerShell.
Settings
Windows Powershell comes with default values that should work in most environments but you may change them to suit your needs.
Advanced Settings
Use HTTPS
- Forces vScope to use HTTPS instead of HTTP when connecting to the target. To use another port than the default, use thePort
option.Skip Common Name Check
- Indicates that certificate common name (CN) of the target need not match the hostname or ip used during the connection. This might be needed when connecting to a target using an IP address instead of a host name. Only use this for trusted targets.Port
- If empty, the default ports are used. 5985 for HTTP and 5986 for HTTPS.JEA Endpoint Name
- The name of the JEA (Just Enough Administration) endpoint configuration to use. Read more about JEA below.Registry Keys
- Add registry keys to collect data from. Read more about collecting registry keys below.
Collect registry keys from Windows OS
With PowerShell, you can collect additional values from the operating system, specifically from the Windows Registry, by configuring the keys in your credentials and Creating tags from Discovery.
- Go to your Windows (PowerShell) credential in Discovery > Credentials.
- Under Advanced Settings, enter a registry key that you want to collect from your Windows assets.
eg.HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\TimeZoneInformation
vScope will automatically collect all nested subkeys from the configured key. - Click Add and then Update to save your changes.
- Run a Discovery, and go to Tags > Created from discovery.
- Click Create tag and select Windows > All Machines.
- Configure your tag by entering a name and selecting the key you want to collect the value from. You can choose to format the value.
- Click Create and rerun a Discovery (Discovery > Credentials > Select Windows (PowerShell) and Rediscovery).
Congratulations, vScope will now collect your configured registry key(s) for every Windows OS discovered with your Windows PowerShell credential!
Configuring JEA (Just Enough Administration)
Using JEA, vScope can safely collect inventory data from Windows systems with limited privileges. JEA gives vScope access only to the specific commands and resources it needs and makes vScope both efficient and fully compliant with enterprise security policies. JEA provides full traceability for auditing.
Simple illustration of the basic Just Enough Administration (JEA) setup.
Prerequisites
- The vScope Server and target server must be part of a Windows domain.
- The JEA credentials with non-administrator rights must be domain-level credentials.
- PowerShell 5.0 or Windows Management Framework 5.1 must be installed on the target Windows machines.
- PowerShell Remoting must be enabled on the target Windows machines.
Example Assumptions
For the sake of the guide, we will assume the following in our example:
- The JEA endpoint will be registered as
vScopeScan
- The role capabilities will be registered as
vScopeJEA
- The user allowed to connect to the JEA endpoint is
DOMAIN\VSCOPEUSER
and will be assigned the role capabilitiesvScopeJEA
- The computer where the JEA endpoint is configured is named
ComputerXYZ
Role Capabilities
The Role Capabilities file (psrc) is the heart of JEA and specifies what a role is allowed to do when connecting with JEA. This file is a detailed specification of which cmdlets, functions, providers and modules are available when using the JEA endpoint.
Execute the following in a PowerShell to create a new file with default contents.
New-PSRoleCapabilityFile -Path .\vScopeJEA.psrc
Edit the vScopeJEA.psrc
to specify the cmdlets, functions, providers and modules that vScope is allowed access to. Here’s the contents of the most recent role capabilities file needed for a complete vScope inventory:
@{ # ID used to uniquely identify this document GUID = '65e98262-941e-45f6-8ca8-979a3b6824ed'
# Author of this document Author = 'Administrator'
# Cmdlets to allow specific functions VisibleCmdlets = @( 'ConvertTo-Xml', 'ConvertTo-Json', 'Get-ChildItem', 'Get-Command', 'Get-Item', 'Get-ItemProperty' 'Get-Variable', 'Get-WmiObject', 'Get-LocalUser', 'Microsoft.PowerShell.Utility\Select-Object', # Service Management 'Get-Service',
# IIS-specific Cmdlets for managing bindings, websites, applications, and app pools 'Get-WebApplication', 'Get-WebBinding', 'Get-Website', 'Get-WebVirtualDirectory' )
# Custom functions visible VisibleFunctions = @('Get-IslSecurityDescriptor', 'Get-IslEnumDefinition', 'Get-IslAppxPackage')
# Custom function definitions FunctionDefinitions = @( @{ Name = 'Get-IslSecurityDescriptor' ScriptBlock = { param([Parameter(ValueFromPipeline=$true)]$SecuritySetting)
if ($SecuritySetting) { $SecuritySetting.GetSecurityDescriptor().Descriptor } } }, @{ Name = 'Get-IslEnumDefinition' ScriptBlock = { param([string]$EnumName) if ($EnumName) { [Enum]::GetValues($EnumName) | Microsoft.PowerShell.Utility\Select-Object @{ n = "Name"; e = { $_ } }, @{ n = "Value"; e = { $_.value__ } } } } }, @{ Name = 'Get-IslAppxPackage' ScriptBlock = { $windowsAppsPath = "C:\Program Files\WindowsApps"
# Make sure the folder exists if (!(Test-Path $windowsAppsPath)) { return }
# Store extracted data $apps = @()
foreach ($folder in (Get-ChildItem -Path $windowsAppsPath -Directory -ErrorAction SilentlyContinue)) { # Construct full path to AppxManifest.xml $manifestPath = Join-Path -Path $folder.FullName -ChildPath "AppxManifest.xml"
# Check if the manifest file exists if (Test-Path $manifestPath) { try { # Load the manifest file [xml]$xmlContent = Get-Content -Path $manifestPath -ErrorAction Stop
# Parse manifest into custom object $apps += [PSCustomObject]@{ Name = $xmlContent.Package.Identity.Name Version = $xmlContent.Package.Identity.Version Publisher = $xmlContent.Package.Identity.Publisher PublisherFriendly = $xmlContent.Package.Properties.PublisherDisplayName InstallDate = [System.DateTimeOffset]::new( ($folder.CreationTime) ).ToUnixTimeMilliSeconds() } } catch { # Silently continue } } } # Output results $apps } } )
# Allow IIS Provider VisibleProviders = @('IIS','Variable','Certificate','Registry')
# Modules needed in the session ModulesToImport = @('WebAdministration')}
The next step is to register the role capabilities.
Create a PowerShell Module for Role Capabilities
The following example creates a PowerShell script module called vScopeJEA
in the $env:ProgramFiles
path to host the role capabilities file vScopeJEA.psrc
. Run the following from the same folder as the vScopeJEA.psrc
file you created earlier.
# Create the module folder$modulePath = Join-Path $env:ProgramFiles "WindowsPowerShell\Modules\vScopeJEA"New-Item -ItemType Directory -Path $modulePath
# Create necessary empty files (script module and manifest).# At least one file must be named the same name as the folder: vScopeJEA$rootModulePath = Join-Path $modulePath "vScopeJEAFunctions.psm1"$moduleManifestPath = Join-Path $modulePath "vScopeJEA.psd1"New-Item -ItemType File -Path $RootModulePathNew-ModuleManifest -Path $moduleManifestPath -RootModule "vScopeJEAFunctions.psm1"
# Create the folder for the RoleCapabilities file and copy in the PSRC file (vScopeJEA.psrc)$rcFolder = Join-Path $modulePath "RoleCapabilities"New-Item -ItemType Directory $rcFolderCopy-Item -Path .\vScopeJEA.psrc -Destination $rcFolder
vScopeJEA.psrc
is copied to C:\Program Files\WindowsPowerShell\Modules\vScopeJEA\RoleCapabilities
and can be edited at any time.
Create Session Configuration
A JEA endpoint must be registered on the system. This done using a PowerShell session configuration file (pssc). This configuration defines who can use the JEA endpoint and which roles they have access to. It also contains global settings that apply to all users of the JEA session.
To configure the PowerShell JEA endpoint for vScope, first create a session configuration file by executing the following in a PowerShell:
$roles = @{ 'DOMAIN\VSCOPEUSER' = @{ RoleCapabilities = 'vScopeJEA' } }$parameters = @{ SessionType = 'RestrictedRemoteServer' Path = '.\vScopeJEA.pssc' RunAsVirtualAccount = $true RoleDefinitions = $roles}New-PSSessionConfigurationFile @parametersTest-PSSessionConfigurationFile -Path .\vScopeJEA.pssc
This will create vScopeJEA.pssc
and then test the validity of the configuration with Test-PSSessionConfigurationFile
. The result of the command should be true
, otherwise there is something wrong with the configuration.
SessionType
defines the most strict and locked down mode of PowerShell (RestrictedRemoteServer
) which operates in NoLanguage
mode. Only a few commands and cmdlets are available in this mode:
Clear-Host
(cls
,clear
)Exit-PSSession
(exsn
,exit
)Get-Command
(gcm
)Get-FormatData
Get-Help
Measure-Object
(measure
)Out-Default
Select-Object
(select
)
There is no way for vScope to execute arbitrary commands or scripts in RestrictedRemoteServer
mode. This is why the role capabilities file contains extra cmdlets (VisibleCmdlets), functions (VisibleFunctions and FunctionDefinitions), providers (VisibleProviders) and modules (ModulesToImport) that vScope needs for a successful inventory.
RunAsVirtualAccount
makes users connecting to the JEA endpoint administrators but only within the capabilities allowed by the role capabilities.
RoleDefinitions
specifies the RoleCapabilities assigned to users that have access to the JEA endpoint. The account DOMAIN\VSCOPEUSER
is assigned the capabilities in the vScopeJEA.psrc
file we created earlier. Change this to match the account used in your environment.
Register Session Configuration
The session configuration (vScopeJEA.pssc
) we created earlier must be registered to create the JEA endpoint. Execute the following command from the same folder vScopeJEA.pssc
. This will register a new JEA endpoint named vScopeScan
:
Register-PSSessionConfiguration -Path .\vScopeJEA.pssc -Name 'vScopeScan' -Force
To verify that the session configuration is registered:
Get-PSSessionConfiguration
The output should include the vScopeScan
endpoint and list DOMAIN\VSCOPEUSER
with permissions.
Name : microsoft.powershellPSVersion : 5.1StartupScript :RunAsUser :Permission : NT AUTHORITY\INTERACTIVE AccessAllowed, BUILTIN\Administrators AccessAllowed, BUILTIN\Remote Management Users AccessAllowed
Name : vScopeScanPSVersion : 5.1StartupScript :RunAsUser :Permission : DOMAIN\vscopeuser AccessAllowed
If you ever need to change the session configuration you must first unregister it and then register it again.
Unregister-PSSessionConfiguration -Name 'vScopeScan' -Force
Test the JEA Endpoint
From the same computer where the JEA endpoint was configured you may run the command below. When you input credentials, make sure to use an account specified in the session configuration. In our example this would be DOMAIN\VSCOPEUSER
specified in the session configuration.
Enter-PSSession computername localhost -Credential (Get-Credential) -ConfigurationName 'vScopeScan'
From a remote computer, use the command below to connect:
Enter-PSSession -computername ComputerXYZ -Credential (Get-Credential) -ConfigurationName 'vScopeScan'
To list the cmdlets and functions available in the remote session execute the following in the established remote session created with Enter-PSSession
:
Get-Command
The output should include all default commands the extra cmdlets and functions defined in the role capabilities file.
CommandType Name Version Source----------- ---- ------- ------Function Clear-HostFunction Exit-PSSessionFunction Get-CommandFunction Get-FormatDataFunction Get-HelpFunction Get-IslEnumDefinitionFunction Get-IslSecurityDescriptorFunction Measure-ObjectFunction Out-DefaultFunction Select-ObjectCmdlet ConvertTo-Json 3.0.0.0 Microsoft.PowerShell.UtilityCmdlet ConvertTo-Xml 3.0.0.0 Microsoft.PowerShell.UtilityCmdlet Get-ChildItem 3.0.0.0 Microsoft.PowerShell.ManagementCmdlet Get-Command 3.0.0.0 Microsoft.PowerShell.CoreCmdlet Get-Item 3.0.0.0 Microsoft.PowerShell.ManagementCmdlet Get-ItemProperty 3.0.0.0 Microsoft.PowerShell.ManagementCmdlet Get-Service 3.0.0.0 Microsoft.PowerShell.ManagementCmdlet Get-Variable 3.0.0.0 Microsoft.PowerShell.UtilityCmdlet Get-WebApplication 1.0.0.0 WebAdministrationCmdlet Get-WebBinding 1.0.0.0 WebAdministrationCmdlet Get-Website 1.0.0.0 WebAdministrationCmdlet Get-WebVirtualDirectory 1.0.0.0 WebAdministrationCmdlet Get-WmiObject 3.0.0.0 Microsoft.PowerShell.ManagementCmdlet Select-Object 3.0.0.0 Microsoft.PowerShell.Utility
Deployment
For managing JEA endpoints across large environments, consider using PowerShell Desired State Configuration (DSC). Follow the instructions by Microsoft to deploy JEA using DSC: Multi-machine configuration with DSC.
There are examples for DSC available in the JEA GitHub Repository.
You may also use Ansible Playbooks for deployment.
Further Reading
Read more about configuring JEA at Microsoft. There you will also find information on how to audit JEA and other security considerations.
Using GMSA (Group Managed Service Accounts)
GMSA allows vScope to authenticate itself without a user or password configured. When configured in the Windows Credential, vScope relies on the operating system to handle the authentication using GMSA or similar.
Prerequisites
- The GMSA account must be part of the local administrators group on the system running vScope Server/Proxy Service. This is required for vScope to be able to update itself with new releases.
- The vScope Server/Proxy Service must be running as the GMSA account.
- Stop
vScope Server Service
- Run ->
services.msc
-> Right clickvScope Server Service
-> Properties -> Logon Tab -> Enter GMSA account/password -> Click OK - Start
vScope Server Service
- Stop
No Authentication Credential
must be selected as Credential Type in the Windows data source. This tells vScope that authentication is handled by the operating system.- Since Kerberos is being used by GMSA, vScope must be able to resolve the FQDN of any IP address being inventoried by the Windows data source.
- The SPN (Service Principal Name) registered in the KDC (Key Distribution Center) must match the FQDN resolved by vScope, otherwise Kerberos will not be used.
- Example: Inventorying machine
192.168.1.100
with FQDNserver01.domain.com
requires the SPNWSMAN/server01.domain.com
to be registered in the KDC and vScope must be able to resolve192.168.1.100
toserver01.domain.com
.
JEA and GMSA
Since JEA and GMSA are not mutually exclusive they may be used in combination. However, using a GMSA account in combination with JEA requires that RunAsVirtualAccount
is removed completely from the PowerShell session configuration and that the GMSA account is used in RoleDefinitions
.
# Replaced DOMAIN\VSCOPEUSER with GMSA account DOMAIN\GMSAAccount$# $roles = @{ 'DOMAIN\VSCOPEUSER' = @{ RoleCapabilities = 'vScopeJEA' } }$roles = @{ 'DOMAIN\GMSAAccount$' = @{ RoleCapabilities = 'vScopeJEA' } }$parameters = @{ SessionType = 'RestrictedRemoteServer' Path = '.\vScopeJEA.pssc' # Removed RunAsVirtualAccount # RunAsVirtualAccount = $true RoleDefinitions = $roles}# Create the session configuration file with the contents aboveNew-PSSessionConfigurationFile @parametersTest-PSSessionConfigurationFile -Path .\vScopeJEA.pssc
# Unregister the existing session configurationUnregister-PSSessionConfiguration -Name 'vScopeScan' -Force
# Register the updated session configurationRegister-PSSessionConfiguration -Path .\vScopeJEA.pssc -Name 'vScopeScan' -Force