PowerShell Just Enough Administration

https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea
Admin
Just Enough Administration (JEA) is a security technology for PowerShell that enables delegated...
Tokens:53,497
Snippets:442
Trust Score:10
Update:9 months ago
Show doc for...
Tokens:
Raw
### Start Process - PowerShell

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/role-capabilities_view=powershell-7.5

This example shows how to start an external process, which poses a risk in JEA as it can be used to run arbitrary code, malware, or bypass security protections. It requires specifying the file path of the executable to run.

```powershell
Start-Process -FilePath '\san\share\malware.exe'
```

--------------------------------

### Example of Dangerous Command: Start-Process

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/role-capabilities_source=recommendations

This example shows how 'Start-Process' can be misused to run arbitrary code, potentially leading to security breaches. Limiting its use is vital for JEA security.

```powershell
Start-Process -FilePath '\\san\share\malware.exe'
```

--------------------------------

### Define JEA Role Capability (Least Privilege)

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/security-considerations_source=recommendations

This snippet illustrates how to define a JEA role capability with specific cmdlets. It shows both a less secure example using wildcards and a more secure version explicitly listing allowed cmdlets to adhere to the principle of least privilege. Avoid wildcards to prevent unintended access.

```PowerShell
# Less Secure Example with Wildcard
# @{
#     VisibleCmdlets = 'Microsoft.PowerShell.Management\*-Process'
# }

# More Secure Example
@{
    VisibleCmdlets = 'Microsoft.PowerShell.Management\Get-Process',
                     'Microsoft.PowerShell.Management\Stop-Process'
}
```

--------------------------------

### Start Interactive JEA Session with PowerShell

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/using-jea_source=recommendations

Initiates an interactive PowerShell remoting session to a JEA endpoint. Requires the target computer name, JEA configuration name, and credentials. The session uses `Enter-PSSession` and supports parameter options for `New-PSSession`.

```powershell
$sessionParams = @{
    ComputerName      = 'localhost'
    ConfigurationName = 'JEAMaintenance'
    Credential        = Get-Credential
}
Enter-PSSession @sessionParams

```

--------------------------------

### Define Role Capability with Specific Cmdlets

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/security-considerations_view=powershell-5.1

This example illustrates how to define a JEA role capability that limits users to specific cmdlets, such as `Get-Process` and `Stop-Process`, from the `Microsoft.PowerShell.Management` module. This approach avoids the use of wildcards and enhances security by restricting potentially dangerous commands.

```powershell
@{
    VisibleCmdlets = 'Microsoft.PowerShell.Management\Get-Process',
                     'Microsoft.PowerShell.Management\Stop-Process'
}
```

--------------------------------

### Enter JEA Session via PowerShell Direct - VMName and VMId

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/using-jea_source=recommendations

Demonstrates how to initiate a JEA session to a virtual machine using PowerShell Direct. This requires the guest OS to be Windows 10, Windows Server 2016, or higher. The examples show connecting by both VM name and VM ID.

```powershell
$sharedParams = @{
    ConfigurationName = 'NICMaintenance'
    Credential        = Get-Credential -UserName 'localhost\JEAformyHoster'
}
# Entering a JEA session using PowerShell Direct when the VM name is unique
Enter-PSSession -VMName 'SQL01' @sharedParams

# Entering a JEA session using PowerShell Direct using VM ids
$vm = Get-VM -VMName 'MyVM' | Select-Object -First 1
Enter-PSSession -VMId $vm.VMId @sharedParams

```

--------------------------------

### Allowing Cmdlets/Functions Without Parameter Restrictions

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/role-capabilities_source=recommendations&view=powershell-7.5

These examples show how to permit the execution of cmdlets or functions without any limitations on their parameters. This includes specifying a cmdlet/function by name, by module, or using wildcards for verbs and nouns.

```powershell
@{ Name = 'My-Func' }
```

```powershell
@{ Name = 'MyModule\My-Func' }
```

```powershell
@{ Name = 'My-*' }
```

```powershell
@{ Name = '*-Func' }
```

--------------------------------

### Listing Available Commands on JEA Endpoint

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/using-jea_source=recommendations&view=powershell-7.5

This snippet demonstrates how to retrieve and display the available commands on a JEA endpoint. It uses Invoke-Command to get all commands and then filters them by CommandType, formatting the output to show command names and their parameters. This helps in understanding what actions can be performed via the JEA session.

```PowerShell
$commandParameters = @{
    ComputerName      = 'SERVER01'
    ConfigurationName = 'JEAMaintenance'
    ScriptBlock       = { Get-Command }
}
Invoke-Command @commandParameters |
    Where-Object { $_.CommandType -in @('Function', 'Cmdlet') } |
    Format-Table Name, Parameters
```

--------------------------------

### JEA Role Capability Merging Example

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/role-capabilities_view=powershell-7.5

This example demonstrates how JEA merges cmdlet visibility and parameter constraints from multiple roles. It defines two roles, Role A and Role B, each with specific configurations for 'Get-Service' and 'Restart-Service'. The comments illustrate how the merging rules apply to determine the final permissions for a user belonging to both roles, highlighting specific rules like parameter constraint overrides.

```powershell
# Role A Visible Cmdlets
$roleA = @{
    VisibleCmdlets = @(
        'Get-Service' 
         @{
            Name       = 'Restart-Service'
            Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Client' }
        }
    )
}

# Role B Visible Cmdlets
$roleB = @{
    VisibleCmdlets = @(
        @{
            Name       = 'Get-Service';
            Parameters = @{ Name = 'DisplayName'; ValidatePattern = 'DNS.*' }
        }
        @{
            Name       = 'Restart-Service'
            Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Server' }
        }
    )
}

# Resulting permissions for a user who belongs to both role A and B
# - The constraint in role B for the DisplayName parameter on Get-Service
#   is ignored because of rule #4

```

--------------------------------

### Check PowerShell Version

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/prerequisites_view=powershell-7.4

This command checks the installed version of PowerShell on your system by accessing the `$PSVersionTable` variable. The output displays the Major, Minor, Build, and Revision numbers of the PowerShell installation.

```powershell
$PSVersionTable.PSVersion

```

--------------------------------

### Allowing Cmdlets by Verb Wildcard

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/role-capabilities_view=powershell-7.5

This snippet demonstrates how to allow any cmdlet or function that starts with a specific verb, using a wildcard. This can be used for broad authorization based on command types.

```PowerShell
@{ Name = 'My-*' }
```

--------------------------------

### JEA Role Capability Merging Logic Example

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/role-capabilities_source=recommendations

This example demonstrates how JEA merges role capabilities, specifically for VisibleCmdlets and their parameters, based on a set of predefined rules. It defines two roles, Role A and Role B, with different constraints on `Get-Service` and `Restart-Service`. The comments illustrate how the merging rules are applied to determine the final permissions for a user belonging to both roles. This is particularly useful for understanding how parameter validation sets and patterns are handled.

```powershell
# Role A Visible Cmdlets
$roleA = @{
    VisibleCmdlets = @(
        'Get-Service'
         @{
            Name       = 'Restart-Service'
            Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Client' }
        }
    )
}

# Role B Visible Cmdlets
$roleB = @{
    VisibleCmdlets = @(
        @{
            Name       = 'Get-Service';
            Parameters = @{ Name = 'DisplayName'; ValidatePattern = 'DNS.*' }
        }
        @{
            Name       = 'Restart-Service'
            Parameters = @{ Name = 'DisplayName'; ValidateSet = 'DNS Server' }
        }
    )
}

# Resulting permissions for a user who belongs to both role A and B
# - The constraint in role B for the DisplayName parameter on Get-Service
#   is ignored because of rule #4

```

--------------------------------

### PowerShell: JEA Conditional Access Rule Examples

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/session-configurations_view=powershell-5.1

Demonstrates how to define conditional access rules in a JEA session configuration file using hashtables with 'And' and 'Or' keys. These rules refine access by requiring users to belong to specific security groups beyond role assignments. Conditional access rules require PowerShell 5.1 or newer.

```powershell
# Example 1: Connecting users must belong to a security group called "elevated-jea"
RequiredGroups = @{ And = 'elevated-jea' }

# Example 2: Connecting users must have signed on with 2 factor authentication or a smart card
# The 2 factor authentication group name is "2FA-logon" and the smart card group
# name is "smartcard-logon"
RequiredGroups = @{ Or = '2FA-logon', 'smartcard-logon' }

# Example 3: Connecting users must elevate into "elevated-jea" with their JIT system and
# have logged on with 2FA or a smart card
RequiredGroups = @{ And = 'elevated-jea', @{ Or = '2FA-logon', 'smartcard-logon' }}

```

--------------------------------

### Example of Dangerous Command: Add-LocalGroupMember

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/role-capabilities_source=recommendations

This example demonstrates a command that could grant administrative privileges, bypassing JEA's security. It's crucial to restrict such commands in JEA role capabilities.

```powershell
Add-LocalGroupMember -Member 'CONTOSO\jdoe' -Group 'Administrators'
```

--------------------------------

### Defining Role Capability with Wildcards (Insecure)

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/security-considerations_view=powershell-7.4

This snippet illustrates an insecure role capability definition in PowerShell for JEA. Using a wildcard with `*-Process` allows users to run any cmdlet with the 'Process' noun, including `Start-Process`, which can be exploited to execute arbitrary programs with administrator privileges, potentially bypassing JEA security boundaries.

```PowerShell
@{
    VisibleCmdlets = 'Microsoft.PowerShell.Management\*-Process'
}
```

--------------------------------

### Create PowerShell Runspace for JEA Session in C#

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/using-jea_view=powershell-7.5

This C# snippet illustrates how to create a PowerShell runspace that connects to a JEA session. It involves constructing a WSManConnectionInfo object with the JEA endpoint details (computer name, configuration name, credentials) and then using this information to create and open a Runspace. Subsequently, PowerShell commands can be added and invoked within this JEA-connected runspace.

```csharp
// using System.Management.Automation;
var computerName = "SERVER01";
var configName   = "JEAMaintenance";
// See https://learn.microsoft.com/dotnet/api/system.management.automation.pscredential
var creds        = // create a PSCredential object here

WSManConnectionInfo connectionInfo = new WSManConnectionInfo(
    false,                 // Use SSL
    computerName,          // Computer name
    5985,                  // WSMan Port
    "/wsman",              // WSMan Path
                           // Connection URI with config name
    string.Format(
        CultureInfo.InvariantCulture,
        "http://schemas.microsoft.com/powershell/{0}",
        configName
    ),
    creds                  // Credentials
);

// Now, use the connection info to create a runspace where you can run the commands
using (Runspace runspace = RunspaceFactory.CreateRunspace(connectionInfo))
{
    // Open the runspace
    runspace.Open();

    using (PowerShell ps = PowerShell.Create())
    {
        // Set the PowerShell object to use the JEA runspace
        ps.Runspace = runspace;

        // Now you can add and invoke commands
        ps.AddCommand("Get-Command");
        foreach (var result in ps.Invoke())
        {
            Console.WriteLine(result);
        }
    }

    // Close the runspace
    runspace.Close();
}


```

--------------------------------

### Import JEA commands with filtering

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/using-jea_source=recommendations

This snippet demonstrates how to establish a PSSession to a JEA endpoint, retrieve all available commands, filter out default cmdlets, and then import the remaining commands with a 'JEA' prefix. This is useful when the default JEA cmdlets cannot import an entire session.

```PowerShell
# Create a new PSSession to your JEA endpoint
$jeaSession = New-PSSession -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance'

# Get a list of all the commands on the JEA endpoint
$commands = Invoke-Command -Session $jeaSession -ScriptBlock { Get-Command }

# Filter out the default cmdlets
$jeaDefaultCmdlets = @(
    'Clear-Host'
    'Exit-PSSession'
    'Get-Command'
    'Get-FormatData'
    'Get-Help'
    'Measure-Object'
    'Out-Default'
    'Select-Object'
)
$filteredCommands = $commands.Name | Where-Object { $jeaDefaultCmdlets -notcontains $_ }

# Import only commands explicitly added in role capabilities and prefix each
# imported cmdlet with "JEA"
Import-PSSession -Session $jeaSession -Prefix 'JEA' -CommandName $filteredCommands

```

--------------------------------

### Validate Parameter Values for PowerShell Cmdlets

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/role-capabilities_view=powershell-5.1

This advanced snippet illustrates how to restrict the values that can be passed to a cmdlet's parameter using either a ValidateSet for specific allowed values or a ValidatePattern for a regular expression match. It shows examples for 'Restart-Service' with a ValidateSet and 'Start-Website' with a ValidatePattern.

```PowerShell
VisibleCmdlets = @(
    @{
        Name       = 'Restart-Service'
        Parameters = @{ Name = 'Name'; ValidateSet = @('Dns', 'Spooler') }
    }
    @{
        Name       = 'Start-Website'
        Parameters = @{ Name = 'Name'; ValidatePattern = 'HR_*' }
    }
)
```

--------------------------------

### Create a PowerShell runspace for JEA in C#

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/using-jea_source=recommendations

This C# code snippet demonstrates how to create a PowerShell runspace that connects to a JEA session. It utilizes `WSManConnectionInfo` to specify connection details such as computer name, port, and credentials, and then allows for invoking PowerShell commands within that JEA session.

```C#
// using System.Management.Automation;
var computerName = "SERVER01";
var configName   = "JEAMaintenance";
// See https://learn.microsoft.com/dotnet/api/system.management.automation.pscredential
var creds        = // create a PSCredential object here

WSManConnectionInfo connectionInfo = new WSManConnectionInfo(
    false,                 // Use SSL
    computerName,          // Computer name
    5985,                  // WSMan Port
    "/wsman",              // WSMan Path
                           // Connection URI with config name
    string.Format(
        CultureInfo.InvariantCulture,
        "http://schemas.microsoft.com/powershell/{0}",
        configName
    ),
    creds                  // Credentials
);

// Now, use the connection info to create a runspace where you can run the commands
using (Runspace runspace = RunspaceFactory.CreateRunspace(connectionInfo))
{
    // Open the runspace
    runspace.Open();

    using (PowerShell ps = PowerShell.Create())
    {
        // Set the PowerShell object to use the JEA runspace
        ps.Runspace = runspace;

        // Now you can add and invoke commands
        ps.AddCommand("Get-Command");
        foreach (var result in ps.Invoke())
        {
            Console.WriteLine(result);
        }
    }

    // Close the runspace
    runspace.Close();
}

```

--------------------------------

### Register JEA Endpoint with Role Definitions

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/security-considerations_view=powershell-5.1

This snippet demonstrates how to register a JEA endpoint with specific role definitions. It uses `New-PSSessionConfigurationFile` to create a session configuration file and `Register-PSSessionConfiguration` to register the endpoint. The `-RunAsVirtualAccount` parameter specifies that the session should run under a virtual account.

```powershell
$roles = @{ 'CONTOSO\JEA_Lev1' = 'Lev1Role'; 'CONTOSO\JEA_Lev2' = 'Lev2Role' }
New-PSSessionConfigurationFile -Path '.\jea.pssc' -SessionType RestrictedRemoteServer -RoleDefinitions $roles -RunAsVirtualAccount
Register-PSSessionConfiguration -Path '.\jea.pssc' -Name 'MyJEAEndpoint'
```

--------------------------------

### Find Local Role Capabilities - PowerShell Function

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/audit-and-report_source=recommendations&view=powershell-7.5

This PowerShell function, `Find-LocalRoleCapability`, locates all available JEA role capabilities on a computer. It searches through installed modules for a 'RoleCapabilities' subfolder containing '.psrc' files and formats the results to display the capability name and its path.

```powershell
function Find-LocalRoleCapability {
    $results = @()

    # Find modules with a "RoleCapabilities" subfolder and add any PSRC files to the result set
    Get-Module -ListAvailable | ForEach-Object {
        $psrcpath = Join-Path -Path $_.ModuleBase -ChildPath 'RoleCapabilities'
        if (Test-Path $psrcpath) {
            $results += Get-ChildItem -Path $psrcpath -Filter *.psrc
        }
    }

    # Format the results nicely to make it easier to read
    $results | Select-Object @{ Name = 'Name'; Expression = { $_.Name.TrimEnd('.psrc') }}, @{
        Name = 'Path'; Expression = { $_.FullName }
    } | Sort-Object Name
}
```

--------------------------------

### Find Local Role Capabilities

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/audit-and-report_view=powershell-7.5

This PowerShell function locates all role capabilities available on a computer by searching for '.psrc' files within the 'RoleCapabilities' subfolder of installed PowerShell modules. It then formats the results to display the name and full path of each role capability file, sorted alphabetically by name.

```powershell
function Find-LocalRoleCapability {
    $results = @()

    # Find modules with a "RoleCapabilities" subfolder and add any PSRC files to the result set
    Get-Module -ListAvailable | ForEach-Object {
        $psrcpath = Join-Path -Path $_.ModuleBase -ChildPath 'RoleCapabilities'
        if (Test-Path $psrcpath) {
            $results += Get-ChildItem -Path $psrcpath -Filter *.psrc
        }
    }

    # Format the results nicely to make it easier to read
    $results | Select-Object @{ Name = 'Name'; Expression = { $_.Name.TrimEnd('.psrc') }}, @{
        Name = 'Path'; Expression = { $_.FullName } 
    } | Sort-Object Name
}
```

--------------------------------

### Establish and Import Session for Implicit Remoting with JEA

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/using-jea_source=recommendations

Sets up an implicit remoting session to a JEA endpoint. It first creates a `PSSession` to the JEA endpoint and then imports the cmdlets from that session, optionally prefixing them to avoid naming conflicts.

```powershell
# Create a new PSSession to your JEA endpoint
$jeaSession = New-PSSession -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance'

# Import the entire PSSession and prefix each imported cmdlet with "JEA"
Import-PSSession -Session $jeaSession -Prefix 'JEA'

```

--------------------------------

### Configure User Drive with Size Limit in JEA

Source: https://learn.microsoft.com/en-us/powershell/scripting/security/remoting/jea/session-configurations_view=powershell-7.4

Enables the user drive and sets a per-user maximum data consumption limit. This example sets the limit to 500MB (524,288,000 bytes). User drive data is persistent across sessions unless explicitly cleaned up.

```PowerShell
# Enables the user drive with a per-user limit of 500MB (524288000 bytes)
MountUserDrive = $true
UserDriveMaximumSize = 524288000

```
Tokens:
Raw