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 in your environment.

Note

As of 30 January 2024, the recommended approach is to use WMI as the primary method for collecting bulk information from Windows operating systems, with Windows PowerShell serving as a complementary method. This combination not only extends the tag collection but also facilitates the use of Just Enough Administration.

---

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.

---

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)

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.

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',
    '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')

  # 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__ } }
          }
      }
    }
  )

  # 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.

# 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:

$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-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.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.

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.

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-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 DSC. Learn more here:

• PowerShell DSC Overview

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.