Skip to content

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.

  1. Go to Discovery > Credentials.
  2. Click Create Credential, and select Windows (PowerShell).
  3. Configure your Integration Settings by adding the credential details. You can reuse an existing credential, or create a new one from scratch.
  4. 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 the Port 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.

  1. Go to your Windows (PowerShell) credential in Discovery > Credentials.
  2. 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.
  3. Click Add and then Update to save your changes.
  4. Run a Discovery, and go to Tags > Created from discovery.
  5. Click Create tag and select Windows > All Machines.
  6. 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.
  7. 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.

Screenshot of settings for Microsoft JEA

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 capabilities vScopeJEA
  • 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.

Creation of vScopeJEA.psrc
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:

vScopeJEA.psrc
@{
# 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.

Creation of vScopeJEA PowerShell module for role capabilities
# 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 $RootModulePath
New-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 $rcFolder
Copy-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:

Creation of PowerShell session configuration
$roles = @{ 'DOMAIN\VSCOPEUSER' = @{ RoleCapabilities = 'vScopeJEA' } }
$parameters = @{
SessionType = 'RestrictedRemoteServer'
Path = '.\vScopeJEA.pssc'
RunAsVirtualAccount = $true
RoleDefinitions = $roles
}
New-PSSessionConfigurationFile @parameters
Test-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 PowerShell session configuration
Register-PSSessionConfiguration -Path .\vScopeJEA.pssc -Name 'vScopeScan' -Force

To verify that the session configuration is registered:

Test of PowerShell session configuration
Get-PSSessionConfiguration

The output should include the vScopeScan endpoint and list DOMAIN\VSCOPEUSER with permissions.

Name : microsoft.powershell
PSVersion : 5.1
StartupScript :
RunAsUser :
Permission : NT AUTHORITY\INTERACTIVE AccessAllowed, BUILTIN\Administrators AccessAllowed, BUILTIN\Remote Management Users AccessAllowed
Name : vScopeScan
PSVersion : 5.1
StartupScript :
RunAsUser :
Permission : DOMAIN\vscopeuser AccessAllowed

If you ever need to change the session configuration you must first unregister it and then register it again.

Unregistering PowerShell session configuration
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.

Testing JEA endpoint on the local computer
Enter-PSSession computername localhost -Credential (Get-Credential) -ConfigurationName 'vScopeScan'

From a remote computer, use the command below to connect:

Testing JEA endpoint from a remote computer
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:

Listing available cmdlets and functions
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-Host
Function Exit-PSSession
Function Get-Command
Function Get-FormatData
Function Get-Help
Function Get-IslEnumDefinition
Function Get-IslSecurityDescriptor
Function Measure-Object
Function Out-Default
Function Select-Object
Cmdlet ConvertTo-Json 3.0.0.0 Microsoft.PowerShell.Utility
Cmdlet ConvertTo-Xml 3.0.0.0 Microsoft.PowerShell.Utility
Cmdlet Get-ChildItem 3.0.0.0 Microsoft.PowerShell.Management
Cmdlet Get-Command 3.0.0.0 Microsoft.PowerShell.Core
Cmdlet Get-Item 3.0.0.0 Microsoft.PowerShell.Management
Cmdlet Get-ItemProperty 3.0.0.0 Microsoft.PowerShell.Management
Cmdlet Get-Service 3.0.0.0 Microsoft.PowerShell.Management
Cmdlet Get-Variable 3.0.0.0 Microsoft.PowerShell.Utility
Cmdlet Get-WebApplication 1.0.0.0 WebAdministration
Cmdlet Get-WebBinding 1.0.0.0 WebAdministration
Cmdlet Get-Website 1.0.0.0 WebAdministration
Cmdlet Get-WebVirtualDirectory 1.0.0.0 WebAdministration
Cmdlet Get-WmiObject 3.0.0.0 Microsoft.PowerShell.Management
Cmdlet 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 click vScope Server Service -> Properties -> Logon Tab -> Enter GMSA account/password -> Click OK
    • Start vScope Server Service
  • 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 FQDN server01.domain.com requires the SPN WSMAN/server01.domain.com to be registered in the KDC and vScope must be able to resolve 192.168.1.100 to server01.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.

Updating PowerShell session configuration for GMSA
# 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 above
New-PSSessionConfigurationFile @parameters
Test-PSSessionConfigurationFile -Path .\vScopeJEA.pssc
# Unregister the existing session configuration
Unregister-PSSessionConfiguration -Name 'vScopeScan' -Force
# Register the updated session configuration
Register-PSSessionConfiguration -Path .\vScopeJEA.pssc -Name 'vScopeScan' -Force