Capacidades de função JEA

Ao criar um ponto de extremidade JEA, é necessário definir uma ou mais capacidades de função que descrevam o que alguém pode fazer em uma sessão JEA. Uma capacidade de função é um arquivo de dados do PowerShell com a extensão .psrc que lista todos os cmdlets, funções, provedores e programas externos que são disponibilizados para os usuários que se conectam.

Determinar quais comandos permitir

A primeira etapa na criação de um arquivo de funcionalidade de função é considerar ao que os usuários precisam de acesso. O processo de coleta de requisitos pode demorar um pouco, mas é importante. Dar aos usuários acesso a poucos cmdlets e funções pode impedi-los de realizar suas tarefas. Permitir o acesso a muitos cmdlets e funções pode permitir que os usuários façam mais do que você pretendia e enfraquecer sua posição de segurança.

A maneira como você faz esse processo depende de sua organização e metas. As dicas a seguir podem ajudar a garantir que você esteja no caminho certo.

1. Identifique os comandos que os usuários estão usando para fazer seus trabalhos. Isso pode envolver o levantamento da equipe de TI, a verificação de scripts de automação ou a análise de transcrições e logs de sessão do PowerShell.
2. Atualize o uso de ferramentas de linha de comando para equivalentes do PowerShell, sempre que possível, para a melhor experiência de auditoria e personalização JEA. Programas externos não podem ser restritos tão granularmente quanto cmdlets e funções nativas do PowerShell no JEA.
3. Restrinja o escopo dos cmdlets para permitir apenas parâmetros ou valores de parâmetro específicos. Isso é especialmente importante se os usuários devem gerenciar apenas parte de um sistema.
4. Crie funções personalizadas para substituir comandos ou comandos complexos que são difíceis de restringir no JEA. Uma função simples que encapsula um comando complexo ou aplica lógica de validação adicional pode oferecer controle adicional para administradores e simplicidade do usuário final.
5. Teste a lista com escopo de comandos permitidos com seus usuários ou serviços de automação e ajuste conforme necessário.

Exemplos de comandos potencialmente perigosos

A seleção cuidadosa de comandos é importante para garantir que o endpoint JEA não permita que o usuário eleve suas permissões.

A lista a seguir contém exemplos de comandos que podem ser usados maliciosamente se permitidos em um estado sem restrições. Essa não é uma lista completa e deve ser usada apenas como um ponto de partida de advertência.

• Risco: Conceder privilégios de administrador ao usuário que se conecta para contornar o JEA

  Exemplo:

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

  Comandos relacionados:

  • Add-ADGroupMember
  • Add-LocalGroupMember
  • net.exe
  • dsadd.exe

• Risco: Executando código arbitrário, como malware, explorações ou scripts personalizados para ignorar proteções

  Exemplo:

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

  Comandos relacionados:

  • Start-Process
  • New-Service
  • Invoke-Item
  • Invoke-WmiMethod
  • Invoke-CimMethod
  • Invoke-Expression
  • Invoke-Command
  • New-ScheduledTask
  • Register-ScheduledJob

Criar um arquivo de capacidades de função

Você pode criar um novo arquivo de capacidade de função do PowerShell com o cmdlet New-PSRoleCapabilityFile.

New-PSRoleCapabilityFile -Path .\MyFirstJEARole.psrc

Você deve editar o arquivo de funcionalidade de função criado para permitir apenas os comandos necessários para a função. A documentação de ajuda do PowerShell contém vários exemplos de como você pode configurar o arquivo.

Permitir cmdlets e funções do PowerShell

Para autorizar os usuários a executar cmdlets ou funções do PowerShell, adicione o cmdlet ou o nome da função aos campos VisibleCmdlets ou VisibleFunctions . Se você não tiver certeza se um comando é um cmdlet ou uma função, poderá executar Get-Command <name> e verificar a propriedade CommandType na saída.

VisibleCmdlets = @('Restart-Computer', 'Get-NetIPAddress')

Às vezes, o escopo de um cmdlet ou função específico é muito amplo para as necessidades dos usuários. Um administrador DNS, por exemplo, pode precisar apenas de acesso para reiniciar o serviço DNS. Em ambientes multilocatários, os locatários têm acesso a ferramentas de gerenciamento de autoatendimento. Os locatários devem ser limitados ao gerenciamento de seus próprios recursos. Para esses casos, você pode restringir quais parâmetros são expostos do cmdlet ou função.

VisibleCmdlets = @{
    Name       = 'Restart-Computer'
    Parameters = @{ Name = 'Name' }
}

Em cenários mais avançados, talvez você também precise restringir os valores que um usuário pode usar com esses parâmetros. As capacidades de função permitem definir um conjunto de valores ou um padrão de expressão regular que determinam qual entrada é permitida.

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

A lista abaixo descreve as várias maneiras de personalizar um cmdlet ou função visível. Você pode misturar e combinar qualquer um dos itens abaixo no campo VisibleCmdlets.

• Caso de uso: Permitir que o usuário execute My-Func sem nenhuma restrição nos parâmetros.

  @{ Name = 'My-Func' }
  

• Caso de uso: Permitir que o usuário execute My-Func no módulo MyModule sem nenhuma restrição nos parâmetros.

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

• Caso de uso: Permitir que o usuário execute qualquer cmdlet ou função com o verbo My.

  @{ Name = 'My-*' }
  

• Caso de uso: Permitir que o usuário execute qualquer cmdlet ou função com o substantivo Func.

  @{ Name = '*-Func' }
  

• Caso de uso: Permitir que o usuário execute My-Func com os parâmetros Param1 e Param2. Qualquer valor pode ser fornecido aos parâmetros.

  @{ Name = 'My-Func'; Parameters = @{ Name = 'Param1'}, @{ Name = 'Param2' }}
  

• Caso de uso: Permitir que o usuário execute My-Func com o parâmetro Param1. Somente Value1 e Value2 pode ser fornecido para o parâmetro.

  @{
      Name       = 'My-Func'
      Parameters = @{ Name = 'Param1'; ValidateSet = @('Value1', 'Value2') }
  }
  

• Caso de uso: Permitir que o usuário execute My-Func com o parâmetro Param1. Qualquer valor começando com contoso pode ser fornecido para o parâmetro.

  @{
      Name       = 'My-Func'
      Parameters = @{ Name = 'Param1'; ValidatePattern = 'contoso.*' }
  }
  

Você não pode aplicar um ValidatePattern e ValidateSet ao mesmo cmdlet ou função.

Se você fizer isso, o ValidatePattern substituirá o ValidateSet.

Para obter mais informações sobre ValidatePattern, confira esta postagem Hey, Scripting Guy! e o conteúdo de referência de Expressões Regulares do PowerShell.

Permitindo comandos externos e scripts do PowerShell

Para permitir que os usuários executem executáveis e scripts do PowerShell (.ps1) em uma sessão JEA, você precisa adicionar o caminho completo a cada programa no campo VisibleExternalCommands .

VisibleExternalCommands = @(
    'C:\Windows\System32\whoami.exe'
    'C:\Program Files\Contoso\Scripts\UpdateITSoftware.ps1'
)

Sempre que possível, use o cmdlet do PowerShell ou equivalentes de função para quaisquer executáveis externos autorizados, pois você tem controle sobre os parâmetros permitidos com cmdlets e funções do PowerShell.

Muitos executáveis permitem ler o estado atual e alterá-lo fornecendo parâmetros diferentes.

Por exemplo, considere a função de um administrador de servidor de arquivos que gerencia compartilhamentos de rede hospedados em um sistema. Uma maneira de gerenciar compartilhamentos é usar net share. No entanto, a permissão net.exe é perigosa porque o usuário pode usar o comando para obter privilégios de administrador com o comando net group Administrators unprivilegedjeauser /add. Uma opção mais segura é permitir o cmdlet Get-SmbShare , que obtém o mesmo resultado, mas tem um escopo muito mais limitado.

Ao disponibilizar comandos externos aos usuários em uma sessão JEA, sempre especifique o caminho completo para o executável. Isso impede a execução de programas de nomes semelhantes e potencialmente mal-intencionados localizados em outros lugares do sistema.

Permitindo o acesso aos provedores do PowerShell

Por padrão, nenhum provedor do PowerShell está disponível em sessões JEA. Isso reduz o risco de informações confidenciais e configurações serem divulgadas para o usuário que se conecta.

Quando necessário, você pode permitir o acesso aos provedores do PowerShell usando o VisibleProviders comando. Para obter uma lista completa de provedores, execute Get-PSProvider.

VisibleProviders = 'Registry'

Para tarefas simples que exigem acesso ao sistema de arquivos, registro, repositório de certificados ou outros provedores confidenciais, considere escrever uma função personalizada que funcione com o provedor em nome do usuário. As funções, os cmdlets e os programas externos disponíveis em uma sessão JEA não estão sujeitos às mesmas restrições que o JEA. Eles podem acessar qualquer provedor por padrão. Considere também o uso da unidade de usuário quando os usuários precisarem copiar arquivos de ou para um ponto de extremidade JEA.

Criando funções personalizadas

Você pode criar funções personalizadas em um arquivo de capacidade de função para facilitar a execução de tarefas complexas pelos usuários finais. Funções personalizadas também são úteis quando você precisa de lógica de validação avançada para valores de parâmetro de cmdlet. Você pode escrever funções simples no campo FunctionDefinitions :

VisibleFunctions = 'Get-TopProcess'

FunctionDefinitions = @{
    Name        = 'Get-TopProcess'
    ScriptBlock = {
        param($Count = 10)

        Get-Process |
            Sort-Object -Property CPU -Descending |
            Microsoft.PowerShell.Utility\Select-Object -First $Count
    }
}

O corpo (bloco de script) de funções personalizadas é executado no modo de linguagem padrão para o sistema e não está sujeito às restrições de linguagem do JEA. Isso significa que as funções podem acessar o sistema de arquivos e o registro do sistema e executar comandos que não foram tornados visíveis no arquivo de capacidades de função. Tome cuidado para evitar a execução de código arbitrário ao usar parâmetros. Evite canalizar a entrada do usuário diretamente em cmdlets como Invoke-Expression.

No exemplo acima, observe que o FQMN (nome do módulo totalmente qualificado) Microsoft.PowerShell.Utility\Select-Object foi usado em vez da abreviação Select-Object. As funções definidas nos arquivos de capacidade de função ainda estão sujeitas ao escopo das sessões JEA, que inclui as funções de proxy que JEA cria para restringir os comandos existentes.

Por padrão, Select-Object é um cmdlet restrito em todas as sessões JEA que não permite a seleção de propriedades arbitrárias em objetos. Para usar as funções sem restrições Select-Object , você deve solicitar explicitamente a implementação completa usando o FQMN. Qualquer cmdlet restrito em uma sessão JEA tem as mesmas restrições quando invocado de uma função. Para obter mais informações, consulte about_Command_Precedence.

Se você estiver escrevendo várias funções personalizadas, é mais conveniente colocá-las em um módulo de script do PowerShell. Você torna essas funções visíveis na sessão JEA usando o campo VisibleFunctions como faria com módulos internos e de terceiros.

Para que a conclusão de tabulação funcione corretamente em sessões JEA, você deve incluir a função interna TabExpansion2 na lista VisibleFunctions.

Disponibilizar os recursos de função para uma configuração

Antes do PowerShell 6, para que o PowerShell encontre um arquivo de capacidade de função, ele deve ser armazenado em uma pasta RoleCapabilities dentro de um módulo do PowerShell. O módulo pode ser armazenado em qualquer pasta incluída na variável de $Env:PSModulePath ambiente; no entanto, você não deve colocá-lo em $Env:SystemRoot\System32 ou em uma pasta onde usuários não confiáveis possam modificar os arquivos.

O exemplo a seguir cria um módulo de script do PowerShell chamado ContosoJEA no $Env:ProgramFiles caminho para hospedar o arquivo de funcionalidades de função.

# Create a folder for the module
$modulePath = Join-Path $Env:ProgramFiles "WindowsPowerShell\Modules\ContosoJEA"
New-Item -ItemType Directory -Path $modulePath

# Create an empty script module and module manifest.
# At least one file in the module folder must have the same name as the folder itself.
$rootModulePath = Join-Path $modulePath "ContosoJEAFunctions.psm1"
$moduleManifestPath = Join-Path $modulePath "ContosoJEA.psd1"
New-Item -ItemType File -Path $RootModulePath
New-ModuleManifest -Path $moduleManifestPath -RootModule "ContosoJEAFunctions.psm1"

# Create the RoleCapabilities folder and copy in the PSRC file
$rcFolder = Join-Path $modulePath "RoleCapabilities"
New-Item -ItemType Directory $rcFolder
Copy-Item -Path .\MyFirstJEARole.psrc -Destination $rcFolder

Para obter mais informações sobre módulos do PowerShell, consulte Noções básicas sobre um módulo do PowerShell.

A partir do PowerShell 6, a propriedade RoleDefinitions foi adicionada ao arquivo de configuração de sessão. Essa propriedade permite que você especifique o local de um arquivo de configuração de função para sua definição de função. Veja os exemplos em New-PSSessionConfigurationFile.

Atualizando capacidades de função

Você pode editar um arquivo de funcionalidade de função para atualizar as configurações a qualquer momento. As novas sessões JEA iniciadas após a atualização da capacidade de função refletem os recursos revisados.

É por isso que controlar o acesso à pasta de funcionalidades de função é tão importante. Somente administradores altamente confiáveis devem ter permissão para alterar arquivos de funcionalidade de função. Se um usuário não confiável puder alterar os arquivos de capacidade de função, ele poderá facilmente conceder a si mesmo acesso a cmdlets que permitem aumentar seus privilégios.

Para administradores que procuram restringir o acesso às capacidades de função, verifique se o Sistema Local tem acesso somente leitura aos arquivos de capacidades de função e aos módulos que os contêm.

Como as capacidades de funções são mescladas

Os usuários recebem acesso a todos os recursos de função correspondentes no arquivo de configuração de sessão quando inserem uma sessão JEA. O JEA tenta dar ao usuário o conjunto mais permissivo de comandos permitido por qualquer uma das funções.

VisibleCmdlets e VisibleFunctions

A lógica de mesclagem mais complexa afeta cmdlets e funções, que podem ter seus parâmetros e valores de parâmetro limitados no contexto do JEA.

As regras são as seguintes:

1. Se um cmdlet ficar visível apenas em uma função, ele ficará visível para o usuário com quaisquer restrições de parâmetro aplicáveis.
2. Se um cmdlet ficar visível em mais de uma função e cada função tiver as mesmas restrições no cmdlet, o cmdlet ficará visível para o usuário com essas restrições.
3. Se um cmdlet ficar visível em mais de uma função e cada função permitir um conjunto diferente de parâmetros, o cmdlet e todos os parâmetros definidos em cada função ficarão visíveis para o usuário. Se uma função não tiver restrições nos parâmetros, todos os parâmetros serão permitidos.
4. Se uma função definir ou validar um padrão de validação para um parâmetro de cmdlet e a outra função permitir o parâmetro, mas não restringir os valores de parâmetro, o conjunto de validação ou padrão será ignorado.
5. Se um conjunto de validação for definido para o mesmo parâmetro de cmdlet em mais de uma função, todos os valores de todos os conjuntos de validação serão permitidos.
6. Se um padrão de validação for definido para o mesmo parâmetro de cmdlet em mais de uma função, todos os valores que correspondem a qualquer um dos padrões serão permitidos.
7. Se um conjunto de validação for definido em uma ou mais funções e um padrão de validação for definido em outra função para o mesmo parâmetro de cmdlet, o conjunto de validação será ignorado e a regra (6) se aplicará aos padrões de validação restantes.

Veja abaixo um exemplo de como as funções são mescladas de acordo com estas regras:

# 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
# - The ValidateSets for Restart-Service are merged because both roles use
#   ValidateSet on the same parameter per rule #5
$mergedAandB = @{
    VisibleCmdlets = @(
        'Get-Service'
        @{
            Name = 'Restart-Service';
            Parameters = @{
                Name = 'DisplayName'
                ValidateSet = 'DNS Client', 'DNS Server'
            }
        }
    )
}

ComandosExternosVisíveis, AliasesVisíveis, ProvedoresVisíveis, ScriptsParaProcessar

Todos os outros campos no arquivo de capacidade de função são adicionados a um conjunto acumulativo de comandos externos permitidos, aliases, provedores e scripts de inicialização. Qualquer comando, alias, provedor ou script disponível em uma funcionalidade de função está disponível para o usuário JEA.

Tenha cuidado para garantir que o conjunto combinado de provedores de uma funcionalidade de função e cmdlets/funções/comandos de outro não permita aos usuários acesso não intencional aos recursos do sistema. Por exemplo, se uma função permitir o cmdlet Remove-Item e outra permitir o provedor FileSystem, há o risco de um usuário JEA excluir arquivos arbitrários em seu computador. Informações adicionais sobre como identificar as permissões efetivas dos usuários podem ser encontradas no artigo de auditoria JEA.

Próximas etapas

Criar um arquivo de configuração de sessão