Prise en charge des extensions pour la gestion d’une infrastructure avec Windows Defender Application Control (WDAC)

Article
06/30/2023

S'applique à : Windows Admin Center, Windows Admin Center Preview

Windows Admin Center prend en charge la gestion d’une infrastructure avec Windows Defender Application Control (WDAC) au niveau de la plateforme. Découvrez-en plus sur la gestion d’une infrastructure avec WDAC dans Windows Admin Center.

La prise en charge de cette gestion au niveau de la plateforme ne signifie pas que les extensions créées pour Windows Admin Center prennent également en charge la gestion de l’infrastructure avec WDAC par défaut. Ce guide décrit les exigences que doit respecter une extension pour prendre en charge la gestion d’une infrastructure avec WDAC.

Exigences relatives à la structure de l’extension

Pour gérer une infrastructure avec WDAC, Windows Admin Center doit ingérer et exécuter des scripts PowerShell d’une manière particulière pour respecter les bonnes pratiques de sécurité. Pour vérifier que les scripts de votre extension s’exécutent correctement, vérifiez que votre extension est conforme aux exigences suivantes.

Tous les scripts PowerShell doivent être stockés dans un fichier

Par le passé, les développeurs d’extensions WAC pouvaient choisir d’inclure du code PowerShell personnalisé sous la forme d’une chaîne dans leur fichier manifest.json d’extension. Par exemple, il est possible de définir les conditions de visibilité d’une extension d’outil en fournissant un script PowerShell dans la propriété « script ». Pour être compatibles avec WDAC, les scripts PowerShell doivent être signés. Les chaînes ne peuvent pas être signées.

Pour vérifier que cette exigence est satisfaite, effectuez les étapes suivantes :

Identifiez les scripts PowerShell dans votre fichier manifest.json.
Après avoir défini tout contenu de script dans votre fichier manifest.json, supprimez le contenu du script et stockez-le dans un fichier .ps1 du répertoire resources/scripts de votre extension. Le code de script dans le manifeste d’extension respecte désormais les mêmes règles que d’autres scripts PowerShell dans Windows Admin Center.
Mettez à jour la propriété conditions du manifeste d’extension avec le format suivant :
```
"conditions": [
    {
        "powerShell": {
            "command": "Script-File-Name",
            "module": "powerShellModuleName",
            "script": "Your script text goes here."
        }
    }
]
```
Le nom du module PowerShell existe déjà dans votre manifeste d’extension. Sa valeur dans le manifeste doit correspondre à celle dans le champ PowerShell.
Identifiez tous les autres endroits où des scripts PowerShell sont créés dynamiquement. La création dynamique d’un script PowerShell avec concaténation de chaînes peut permettre à un attaquant d’injecter un script PowerShell arbitraire et de l’exécuter. Cette méthode peut être utilisée pour contourner les limitations appliquées à un utilisateur distant qui utilise un espace d’exécution restreint. Elle peut également servir à obtenir une injection de commandes standard sur n’importe quelle application qui génère des scripts PowerShell avec une entrée utilisateur et les exécute.

Exemple de bloc de script créé avec concaténation de chaînes :

param($UserInputVar)
$DynamicScript = "Get-ChildItem $UserInputVar"
$ScriptBlock = [ScriptBlock]::Create($DynamicScript)
Invoke-Command $ScriptBlock

Exemple de ce même bloc de script construit sans concaténation de chaînes :

param($UserInputVar)
 [ScriptBlock]$ScriptBlock = {
Param($SafeUserInput)
Get-ChildItem $ SafeUserInput
 }
 Invoke-Command -ScriptBlock $ScriptBlock -ArgumentList @($UserInputVar)

# OR, alternatively
param($UserInputVar)
 Invoke-Command -ScriptBlock {
 param(
    [String] $SafeUserInput
 )
Get-ChildItem $SafeUserInput

} -ArgumentList $UserInputVar

Vous ne devez pas non plus utiliser la concaténation de chaînes pour construire des fichiers de script. Voici un exemple de ce qu’il ne faut pas faire lors de la construction de fichiers de script :

$Script=@'
    Get-ChildItem $UserInputVar
'@
$Script = '$ UserInputVar =' + "'$ UserInputVar;"+$Script 
$path = “C:\temp”
$Script | Out-File $path

Au lieu de cela, construisez vos fichiers de script comme ceci :

Function test {
    param(
        [String] $userInputVar
     )
    Get-ChildItem $UserInputVar
    }
   
    $path = “C:\temp”
    (Get-Command test).ScriptBlock | Set-Content -path $path

Tout le code PowerShell doit être signé et stocké à l’emplacement approprié

Dans le cadre des modifications apportées par Windows Admin Center pour prendre en charge la gestion d’une infrastructure avec WDAC, les scripts PowerShell signés pour une extension sont désormais transférés au nœud auquel Windows Admin Center est actuellement connecté avant d’être exécutés. Par ailleurs, comme mentionné dans l’exigence précédente, une infrastructure avec WDAC n’exécute que les scripts PowerShell signés. En raison de ces exigences, tout votre code PowerShell doit être signé. Tout votre code PowerShell doit également se trouver dans un emplacement cohérent afin que la plateforme Windows Admin Center puisse localiser de manière prévisible les modules signés d’une extension.

Si votre dépôt d’extensions ne contient pas de répertoire powershell-module comprenant le ou les modules PowerShell signés, la plateforme Windows Admin Center ne peut pas identifier le code transférable, ce qui entraîne l’échec des opérations dans un environnement avec WDAC.

La commande Windows Admin Center gulp build met à jour le dossier /dist dans votre dépôt, générant ainsi vos fichiers .psd1 et .psm1 non signés dans un dossier de module. Ces fichiers doivent être signés avec un certificat de signature qui correspond à un certificat figurant dans la liste verte de la stratégie WDAC.

Pour apporter cette modification, nous vous recommandons vivement de créer un pipeline de build qui intègre la signature PowerShell.

Vous pouvez vérifier que votre code PowerShell est au bon format de deux façons :

Quand votre extension est installée, vous pouvez voir le répertoire ProgramData\Server Management Experience\UX\modules sur votre ordinateur passerelle (celui sur lequel Windows Admin Center est en cours d’exécution). Ici, vous devez voir le dossier powershell-module et le ou les modules PowerShell signés
Extrayez le contenu de l’artefact .nupkg de votre extension. Le dossier powershell-module doit être présent et contenir le ou les modules PowerShell signés.

Dans les deux cas, vous pouvez vérifier que les fichiers .psd1 et .psm1 sont signés en exécutant la commande Get-AuthenticodeSignature sur un fichier ou en cliquant avec le bouton droit sur un fichier et en validant la signature numérique.

Les éléments de travail qui utilisent la propriété « powerShellScript » doivent être mis à jour pour utiliser la propriété « powerShellCommand »

La plateforme Windows Admin Center doit pouvoir déterminer à quel module appartient une commande PowerShell. En raison de cette exigence, les éléments de travail qui spécifient une commande PowerShell à l’aide de la propriété powerShellScript provoquent une erreur.

Pour atténuer ce comportement, utilisez la propriété powerShellCommand avec la méthode createCommand pour former un objet de commande valide.

Voici un exemple d’élément de travail utilisant l’ancienne méthode :

    const workItem : WorkItemSubmitRequest = {
      typeId: "SampleWorkItem",
      title: "Title",
      powerShellScript: PowerShellScripts.[scriptName],
      successMessage: "Success",
      errorMessage: "Error",
      progressMessage: "In progress..."
    }

Et voici le même élément de travail utilisant la nouvelle méthode :

    const workItem : WorkItemSubmitRequest = {
      typeId: "SampleWorkItem",
      title: "Title",
      powerShellCommand: PowerShell.createCommand(PowerShellScripts.[scriptName]),
      successMessage: "Success",
      errorMessage: "Error",
      progressMessage: "In progress..."
    }

Vérifier que les scripts PowerShell s’exécutent en mode Constrained-Language

De nombreuses stratégies WDAC forcent tous les scripts PowerShell à s’exécuter en mode Constrained-Language. Pour maintenir toutes les fonctionnalités dans Windows Admin Center, vous devez vérifier que tous les scripts de votre extension respectent les bonnes pratiques suivantes :

Si vos fichiers de script sont exportés avec des modules PowerShell, ils doivent exporter explicitement les fonctions par nom sans utiliser de caractères génériques. Cette exigence a pour but d’empêcher l’exposition involontaire de fonctions d’assistance qui ne sont peut-être pas destinées à une utilisation publique.
Le « dot sourcing » d’un fichier de script fait entrer l’ensemble des fonctions, variables et alias de ce script dans l’étendue actuelle. Cette fonctionnalité empêche le « dot sourcing » d’un script approuvé afin de le convertir en script non approuvé et d’exposer toutes ses fonctions internes. De même, il est impossible d’utiliser le « dot sourcing » pour convertir un script non approuvé en script approuvé et polluer l’étendue approuvée.
Nous vous recommandons d’éviter d’utiliser la commande Start-Job pour exécuter des blocs de script, sauf si ce bloc de script peut déjà être exécuté en mode Constrained-Language.

Suggestion de gestion des erreurs en cas d’échec de la prise en charge de la gestion d’infrastructure avec WDAC

Si vous ne prévoyez pas de prendre en charge l’exécution de votre extension sur des machines avec WDAC, nous vous suggérons d’ajouter une interface utilisateur qui explique que la gestion d’une infrastructure avec WDAC est un scénario non pris en charge dans votre extension afin d’éviter toute confusion chez les utilisateurs. Nous recommandons une mise en page semblable à celle des pages de nos services hybrides Azure, avec l’icône de l’extension et le texte centré sur l’iFrame de l’extension.

Pour le texte de cette page, nous vous suggérons la formulation suivante :

« À l’heure actuelle, vous ne pouvez pas exécuter cette extension sur des machines avec Windows Defender Application Control (WDAC). »

Ce texte n’est qu’une suggestion. Si vous n’êtes pas sûr de la formulation à employer, envoyez un e-mail à l’équipe Windows Admin Center à l’adresse wacextensionrequests@microsoft.com.

Détection de l’application de WDAC à partir de votre extension

Pour suivre les instructions de la section précédente, vous devez déterminer si WDAC est appliqué au nœud auquel vous êtes connecté. Windows Admin Center expose une méthode appelée getPsLanguageMode, définie dans le cadre des opérations WDAC de Windows Admin Center, pour déterminer l’application de WDAC.

Cette méthode a deux sorties :

Status – Type HTTPStatusCode
psLanguageMode – Type PsLanguageMode (enum)

Vous pouvez considérer que WDAC est appliqué si PowerShell s’exécute en mode Constrained Language, ce qui correspond à une valeur psLanguageMode de 3.

L’exemple de code TypeScript suivant illustre l’utilisation de cette méthode :

import { Component, OnInit } from '@angular/core';
import { AppContextService } from '@microsoft/windows-admin-center-sdk/angular';
import { WdacOperations } from '@microsoft/windows-admin-center-sdk/core';
import { PSLanguageMode, PsLanguageModeResult } from '@microsoft/windows-admin-center-sdk/core/data/wdac-operations';

@Component({
  selector: 'default-component',
  templateUrl: './default.component.html',
  styleUrls: ['./default.component.css']
})
export class DefaultComponent implements OnInit {
wdacEnforced: boolean;

  constructor(private appContextService: AppContextService) {
    //
  }

  public ngOnInit(): void {

  }

  public checkWDACEnforced(): void {
    const wdacOperations = new WdacOperations(this.appContextService);
    wdacOperations.getPsLanguageMode(this.appContextService.activeConnection.nodeName).subscribe(
      (response: PsLanguageModeResult) => {
          if (response.psLanguageMode.toString() === PSLanguageMode[PSLanguageMode.ConstrainedLanguage]) {
            this.wdacEnforced = true;
          }
          else {
            this.wdacEnforced = false;
          }
      }
    );
  }
}

Test de votre extension sur une infrastructure avec WDAC

Découvrez-en plus sur les exigences de la stratégie Windows Defender Application Control pour Windows Admin Center pour commencer à tester votre extension sur une infrastructure avec WDAC.