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 or LAPS for seamless authentication in your environment.

---

Requirements

• Permission: Ensure the account used for PowerShell discovery has the necessary permissions on the target Windows systems. These settings can be controlled using…
  • Access through GPO
  • Local/domain administrator
  • Just Enough Administration (JEA)
  • Group Managed Service Account (GMSA)
• Access: Ensure that the selected port is open on the target machine.

You may want to review different options for Windows Discovery

Adding Windows OS (PowerShell)

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 credential type depending on your environment:
   • User & Password for normal user password authentication.
   • No Authentication for GMSA or similar where the OS will handle the authentication.
   • LAPS for LAPS where vScope will use Local Administrator Password Solution to query the AD for the password.
5. 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.
   e.g. 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.

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.

Note

The Role Capabilities file was updated on 2025-04-07. To ensure that your vScope inventory is successful, update the your capabilities file with the latest version from this page.

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.

Note

Prior to PowerShell 6, for PowerShell to find the role capability file it must be stored in a RoleCapabilities folder in a PowerShell module. The module can be stored in any folder included in the $env:PSModulePath environment variable, but don’t place it in $env:SystemRoot\System32 or a folder where untrusted users could modify the files.

You may skip the next step of creating a PowerShell Module if you are running PowerShell 6 or later. Read about the RoleDefinitions property which can be used in the session configuration to locate the role configuration file instead of placing the file within a PowerShell Module.

---

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.

Note

A new version of vScope that provides updated Windows inventory might require an update of the role capabilities file to include new required cmdlets, functions, providers or modules.

---

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

Note

Unregistering a JEA endpoint forces the WinRM service to restart. This will interrupt remote management operations in progress like other PowerShell sessions and WMI invocations. Only unregister endpoints during maintenance windows.

---

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

Credentials Example

After you have successfully completed the configuration, the credentials for the JEA configuration should look like this.

Credential type
-Credential type: User & Password Credential

Details
-Username: YOURUSERNAME
-Password: YOURPASSWORD

Advanced settings
-Enter port: leave empty for default value
-JEA Endpoint Name: vScopeScan

Registry keys
Key: HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\TimeZoneInformation

Note

HTTP uses port 5985 and HTTPS uses port 5986 by default.

You can toggle Use HTTPS to force vScope to use HTTPS instead of HTTP. It will use port 5986 if no other port is defined.

Ensure your environment is configured to support remote PowerShell over HTTPS.

---

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 LAPS (Windows Local Administrator Password Solution)

LAPS allows vScope to query the Active Directory for the local administrator password for any domain-joined machine without a user or password configured in vScope. When configured in the Windows Credential, vScope expects that the user account that the vScope Server/Proxy service is running as has permissions to get passwords from Active Directory.

Note

LAPS is only supported if vScope is running on Windows Server 2019 (April 11 2023 Update) or later with Get-LapsADPassword cmdlet available.

Learn more about LAPS and Get-LapsADPassword.

Prerequisites

• An account (“Password Reader Account”) with permissions to read passwords from the Active Directory domain (“Domain”) must exist.
  • Read more about Set-LapsADReadPasswordPermission which can be used to control these permissions.
• The vScope Server/Proxy Service must be running as the Password Reader Account.
• The system (“vScope System”) that the vScope Server/Proxy Service is running on must be domain-joined to the Domain.
• The systems being inventoried using LAPS must be domain-joined to the Domain.
  • The vScope System running as the Password Reader Account executes Get-LapsADPassword -Identity SystemX and must be able to find “SystemX” in the Domain.
• The Password Reader Account must be part of the local administrators group on the vScope System. This is required for vScope to be able to update itself with new releases.
• LAPS Credential must be selected as Credential Type in the Windows data source. This tells vScope that authentication is handled via LAPS.
  • Optionally specify Local Administrator Username to control the local administrator account being used during inventory. If not set it defaults to .\Administrator which corresponds to the default local administrator account.

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.

Note

Group managed service accounts are only available on domain-joined machines using PowerShell 5.1 or newer.

Learn more about GMSA.

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.

Note

GMSA must be setup correctly in your environment so that vScope is able to use it. vScope relies on the New-PSSession cmdlet to setup a non-interactive remote PowerShell to the machine being inventoried. When using No Authentication Credential as the credential type the -Credential option is omitted (from New-PSSession) and it is expected that New-PSSession is able to use GMSA during the authentication process.

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

Note

The GMSA account ('DOMAIN\GMSAAccount$' in this example) used in RoleDefinitions MUST be the same account as the vScope Server/Proxy Service is running as.

---