Script PowerShell pour le contrôle de l’intégrité d’Active Directory : le guide complet 

Introduction

Le maintien de l’intégrité de votre environnement Active Directory (AD) est crucial pour la stabilité et la sécurité des systèmes informatiques. Un AD malsain peut entraîner des échecs d’authentification, des problèmes de réplication et des perturbations plus importantes sur le réseau d’une entreprise. Ce script PowerShell est conçu pour rationaliser le processus d’évaluation et de dépannage des contrôles d’intégrité d’Active Directory, offrant une méthode structurée et automatisée pour les professionnels de l’informatique et les fournisseurs de services gérés (MSP).

Contexte

Active Directory est la clé de voûte de nombreux environnements informatiques d’entreprise, gérant l’authentification des utilisateurs, les stratégies de groupe et les services d’annuaire. Toutefois, garantir son bon fonctionnement peut s’avérer complexe, compte tenu du nombre de points de défaillance potentiels. Ce script utilise l’utilitaire de ligne de commande DCDiag pour analyser l’état d’un contrôleur de domaine, identifier les problèmes potentiels et rapporter les résultats. Pour les MSP et les administrateurs informatiques, cet outil est inestimable, car il fournit un aperçu clair de l’intégrité d’AD et facilite une maintenance proactive.

Le script :

#Requires -Version 5.1

<#
.SYNOPSIS
    Analyzes the state of a domain controller and reports any problems to help with troubleshooting. Optionally, set a WYSIWYG custom field.
    By using this script, you indicate your acceptance of the following legal terms as well as our Terms of Use at https://www.ninjaone.com/terms-of-use.
    Ownership Rights: NinjaOne owns and will continue to own all right, title, and interest in and to the script (including the copyright). NinjaOne is giving you a limited license to use the script in accordance with these legal terms. 
    Use Limitation: You may only use the script for your legitimate personal or internal business purposes, and you may not share the script with another party. 
    Republication Prohibition: Under no circumstances are you permitted to re-publish the script in any script library or website belonging to or under the control of any other software provider. 
    Warranty Disclaimer: The script is provided “as is” and “as available”, without warranty of any kind. NinjaOne makes no promise or guarantee that the script will be free from defects or that it will meet your specific needs or expectations. 
    Assumption of Risk: Your use of the script is at your own risk. You acknowledge that there are certain inherent risks in using the script, and you understand and assume each of those risks. 
    Waiver and Release: You will not hold NinjaOne responsible for any adverse or unintended consequences resulting from your use of the script, and you waive any legal or equitable rights or remedies you may have against NinjaOne relating to your use of the script. 
    EULA: If you are a NinjaOne customer, your use of the script is subject to the End User License Agreement applicable to you (EULA).
.DESCRIPTION
    Analyzes the state of a domain controller and reports any problems to help with troubleshooting. Optionally, set a WYSIWYG custom field.
.EXAMPLE
    (No Parameters)
    
Retrieving Directory Server Diagnosis Test Results.

Passing Tests: CheckSDRefDom, Connectivity, CrossRefValidation, DFSREvent, FrsEvent, Intersite, KccEvent, KnowsOfRoleHolders, MachineAccount, NCSecDesc, NetLogons, ObjectsReplicated, Replications, RidManager, Services, SystemLog, SysVolCheck, VerifyReferences

[Alert] Failed Tests Detected!
Failed Tests: Advertising, LocatorCheck

### Detailed Output ###

Directory Server Diagnosis
Performing initial setup:
   Trying to find home server...
   Home Server = SRV16-DC2-TEST
   * Identified AD Forest. 
   Done gathering initial info.
Doing initial required tests
   Testing server: Default-First-Site-Name\SRV16-DC2-TEST
      Starting test: Connectivity
         ......................... SRV16-DC2-TEST passed test Connectivity
Doing primary tests
   Testing server: Default-First-Site-Name\SRV16-DC2-TEST
      Starting test: Advertising
         Warning: SRV16-DC2-TEST is not advertising as a time server.
         ......................... SRV16-DC2-TEST failed test Advertising
   Running partition tests on : ForestDnsZones
   Running partition tests on : DomainDnsZones
   Running partition tests on : Schema
   Running partition tests on : Configuration
   Running partition tests on : test
   Running enterprise tests on : test.lan

Directory Server Diagnosis
Performing initial setup:
   Trying to find home server...
   Home Server = SRV16-DC2-TEST
   * Identified AD Forest. 
   Done gathering initial info.
Doing initial required tests
   Testing server: Default-First-Site-Name\SRV16-DC2-TEST
      Starting test: Connectivity
         ......................... SRV16-DC2-TEST passed test Connectivity
Doing primary tests
   Testing server: Default-First-Site-Name\SRV16-DC2-TEST
   Running partition tests on : ForestDnsZones
   Running partition tests on : DomainDnsZones
   Running partition tests on : Schema
   Running partition tests on : Configuration
   Running partition tests on : test
   Running enterprise tests on : test.lan
      Starting test: LocatorCheck
         Warning: DcGetDcName(TIME_SERVER) call failed, error 1355
         A Time Server could not be located.
         The server holding the PDC role is down.
         Warning: DcGetDcName(GOOD_TIME_SERVER_PREFERRED) call failed, error
         1355
         A Good Time Server could not be located.
         ......................... test.lan failed test LocatorCheck

PARAMETER: -wysiwygCustomField "ReplaceMeWithaWYSIWYGcustomField"
    Name of a WYSIWYG custom field to optionally save the results to.
.NOTES
    Minimum OS Architecture Supported: Windows 10, Windows Server 2016
    Release Notes: Initial Release
#>

[CmdletBinding()]
param (
    [Parameter()]
    [String]$wysiwygCustomField
)

begin {
    # If script form variables are used, replace command line parameters with their value. 
    if ($env:wysiwygCustomFieldName -and $env:wysiwygCustomFieldName -notlike "null") { $wysiwygCustomField = $env:wysiwygCustomFieldName }

    # Function to test if the current machine is a domain controller
    function Test-IsDomainController {
        $OS = if ($PSVersionTable.PSVersion.Major -lt 5) {
            Get-WmiObject -Class Win32_OperatingSystem
        }
        else {
            Get-CimInstance -ClassName Win32_OperatingSystem
        }

        # Check if the OS is a domain controller (ProductType 2)
        if ($OS.ProductType -eq "2") {
            return $true
        }
    }

    function Get-DCDiagResults {
        # Define the list of DCDiag tests to run
        $DCDiagTestsToRun = "Connectivity", "Advertising", "FrsEvent", "DFSREvent", "SysVolCheck", "KccEvent", "KnowsOfRoleHolders", "MachineAccount", "NCSecDesc", "NetLogons", "ObjectsReplicated", "Replications", "RidManager", "Services", "SystemLog", "VerifyReferences", "CheckSDRefDom", "CrossRefValidation", "LocatorCheck", "Intersite"
    
        foreach ($DCTest in $DCDiagTestsToRun) {
            # Run DCDiag for the current test and save the output to a file
            $DCDiag = Start-Process -FilePath "DCDiag.exe" -ArgumentList "/test:$DCTest", "/f:$env:TEMP\dc-diag-$DCTest.txt" -PassThru -Wait -NoNewWindow

            # Check if the DCDiag test failed
            if ($DCDiag.ExitCode -ne 0) {
                Write-Host "[Error] Running $DCTest!"
                exit 1
            }

            # Read the raw results from the output file and filter out empty lines
            $RawResult = Get-Content -Path "$env:TEMP\dc-diag-$DCTest.txt" | Where-Object { $_.Trim() }
            
            # Find the status line indicating whether the test passed or failed
            $StatusLine = $RawResult | Where-Object { $_ -match "\. .* test $DCTest" }

            # Extract the status (passed or failed) from the status line
            $Status = $StatusLine -split ' ' | Where-Object { $_ -like "passed" -or $_ -like "failed" }

            # Create a custom object to store the test results
            [PSCustomObject]@{
                Test   = $DCTest
                Status = $Status
                Result = $RawResult
            }

            # Remove the temporary output file
            Remove-Item -Path "$env:TEMP\dc-diag-$DCTest.txt"
        }
    }

    function Set-NinjaProperty {
        [CmdletBinding()]
        Param(
            [Parameter(Mandatory = $True)]
            [String]$Name,
            [Parameter()]
            [String]$Type,
            [Parameter(Mandatory = $True, ValueFromPipeline = $True)]
            $Value,
            [Parameter()]
            [String]$DocumentName
        )
    
        $Characters = $Value | Out-String | Measure-Object -Character | Select-Object -ExpandProperty Characters
        if ($Characters -ge 200000) {
            throw [System.ArgumentOutOfRangeException]::New("Character limit exceeded: the value is greater than or equal to 200,000 characters.")
        }
        
        # If requested to set the field value for a Ninja document, specify it here.
        $DocumentationParams = @{}
        if ($DocumentName) { $DocumentationParams["DocumentName"] = $DocumentName }
        
        # This is a list of valid fields that can be set. If no type is specified, assume that the input does not need to be changed.
        $ValidFields = "Attachment", "Checkbox", "Date", "Date or Date Time", "Decimal", "Dropdown", "Email", "Integer", "IP Address", "MultiLine", "MultiSelect", "Phone", "Secure", "Text", "Time", "URL", "WYSIWYG"
        if ($Type -and $ValidFields -notcontains $Type) { Write-Warning "$Type is an invalid type. Please check here for valid types: https://ninjarmm.zendesk.com/hc/en-us/articles/16973443979789-Command-Line-Interface-CLI-Supported-Fields-and-Functionality" }
        
        # The field below requires additional information to set.
        $NeedsOptions = "Dropdown"
        if ($DocumentName) {
            if ($NeedsOptions -contains $Type) {
                # Redirect error output to the success stream to handle errors more easily if nothing is found or something else goes wrong.
                $NinjaPropertyOptions = Ninja-Property-Docs-Options -AttributeName $Name @DocumentationParams 2>&1
            }
        }
        else {
            if ($NeedsOptions -contains $Type) {
                $NinjaPropertyOptions = Ninja-Property-Options -Name $Name 2>&1
            }
        }
        
        # If an error is received with an exception property, exit the function with that error information.
        if ($NinjaPropertyOptions.Exception) { throw $NinjaPropertyOptions }
        
        # The types below require values not typically given to be set. The code below will convert whatever we're given into a format ninjarmm-cli supports.
        switch ($Type) {
            "Checkbox" {
                # Although it's highly likely we were given a value like "True" or a boolean data type, it's better to be safe than sorry.
                $NinjaValue = [System.Convert]::ToBoolean($Value)
            }
            "Date or Date Time" {
                # Ninjarmm-cli expects the GUID of the option to be selected. Therefore, match the given value with a GUID.
                $Date = (Get-Date $Value).ToUniversalTime()
                $TimeSpan = New-TimeSpan (Get-Date "1970-01-01 00:00:00") $Date
                $NinjaValue = $TimeSpan.TotalSeconds
            }
            "Dropdown" {
                # Ninjarmm-cli expects the GUID of the option we're trying to select, so match the value we were given with a GUID.
                $Options = $NinjaPropertyOptions -replace '=', ',' | ConvertFrom-Csv -Header "GUID", "Name"
                $Selection = $Options | Where-Object { $_.Name -eq $Value } | Select-Object -ExpandProperty GUID
        
                if (-not $Selection) {
                    throw [System.ArgumentOutOfRangeException]::New("Value is not present in dropdown options.")
                }
        
                $NinjaValue = $Selection
            }
            default {
                # All the other types shouldn't require additional work on the input.
                $NinjaValue = $Value
            }
        }
        
        # Set the field differently depending on whether it's a field in a Ninja Document or not.
        if ($DocumentName) {
            $CustomField = Ninja-Property-Docs-Set -AttributeName $Name -AttributeValue $NinjaValue @DocumentationParams 2>&1
        }
        else {
            $CustomField = $NinjaValue | Ninja-Property-Set-Piped -Name $Name 2>&1
        }
        
        if ($CustomField.Exception) {
            throw $CustomField
        }
    }
   
    function Test-IsElevated {
        $id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
        $p = New-Object System.Security.Principal.WindowsPrincipal($id)
        $p.IsInRole([System.Security.Principal.WindowsBuiltInRole]::Administrator)
    }

    if (!$ExitCode) {
        $ExitCode = 0
    }
}
process {
    # Check if the script is run with Administrator privileges
    if (!(Test-IsElevated)) {
        Write-Host -Object "[Error] Access Denied. Please run with Administrator privileges."
        exit 1
    }

    # Check if the script is run on a Domain Controller
    if (!(Test-IsDomainController)) {
        Write-Host -Object "[Error] This script needs to be run on a Domain Controller."
        exit 1
    }

    # Initialize lists to store passing and failing tests
    $PassingTests = New-Object System.Collections.Generic.List[object]
    $FailedTests = New-Object System.Collections.Generic.List[object]

    # Notify the user that the tests are being retrieved
    Write-Host -Object "`nRetrieving Directory Server Diagnosis Test Results."
    $TestResults = Get-DCDiagResults

    # Process each test result
    foreach ($Result in $TestResults) {
        $TestFailed = $False

        # Check if any status in the result indicates a failure
        $Result.Status | ForEach-Object {
            if ($_ -notmatch "pass") {
                $TestFailed = $True
            }
        }

        # Add the result to the appropriate list
        if ($TestFailed) {
            $FailedTests.Add($Result)
        }
        else {
            $PassingTests.Add($Result)
        }
    }

    # Optionally set a WYSIWYG custom field if specified
    if ($wysiwygCustomField) {
        try {
            Write-Host -Object "`nBuilding HTML for Custom Field."

            # Create an HTML report for the custom field
            $HTML = New-Object System.Collections.Generic.List[object]

            $HTML.Add("<h1 style='text-align: center'>Directory Server Diagnosis Test Results (DCDiag.exe)</h1>")
            $FailedPercentage = $([math]::Round((($FailedTests.Count / ($FailedTests.Count + $PassingTests.Count)) * 100), 2))
            $SuccessPercentage = 100 - $FailedPercentage
            $HTML.Add(
                @"
<div class='p-3 linechart'>
    <div style='width: $FailedPercentage%; background-color: #C6313A;'></div>
    <div style='width: $SuccessPercentage%; background-color: #007644;'></div>
        </div>
        <ul class='unstyled p-3' style='display: flex; justify-content: space-between; '>
            <li><span class='chart-key' style='background-color: #C6313A;'></span><span>Failed ($($FailedTests.Count))</span></li>
            <li><span class='chart-key' style='background-color: #007644;'></span><span>Passed ($($PassingTests.Count))</span></li>
        </ul>
"@
            )

            # Add failed tests to the HTML report
            $FailedTests | Sort-Object Test | ForEach-Object {
                $HTML.Add(
                    @"
<div class='info-card error'>
    <i class='info-icon fa-solid fa-circle-exclamation'></i>
    <div class='info-text'>
        <div class='info-title'>$($_.Test)</div>
        <div class='info-description'>
            $($_.Result | Out-String)
        </div>
    </div>
</div>
"@
                )
            }

            # Add passing tests to the HTML report
            $PassingTests | Sort-Object Test | ForEach-Object {
                $HTML.Add(
                    @"
<div class='info-card success'>
    <i class='info-icon fa-solid fa-circle-check'></i>
    <div class='info-text'>
        <div class='info-title'>$($_.Test)</div>
        <div class='info-description'>
            Test passed.
        </div>
    </div>
</div>
"@
                )
            }

            # Set the custom field with the HTML report
            Write-Host -Object "Attempting to set Custom Field '$wysiwygCustomField'."
            Set-NinjaProperty -Name $wysiwygCustomField -Value $HTML
            Write-Host -Object "Successfully set Custom Field '$wysiwygCustomField'!"
        }
        catch {
            Write-Host -Object "[Error] $($_.Exception.Message)"
            $ExitCode = 1
        }
    }

    # Display the list of passing tests
    if ($PassingTests.Count -gt 0) {
        Write-Host -Object ""
        Write-Host -Object "Passing Tests: " -NoNewline
        Write-Host -Object ($PassingTests.Test | Sort-Object) -Separator ", "
        Write-Host -Object ""
    }

    # Display the list of failed tests with detailed output
    if ($FailedTests.Count -gt 0) {
        Write-Host -Object "[Alert] Failed Tests Detected!"
        Write-Host -Object "Failed Tests: " -NoNewline
        Write-Host -Object ($FailedTests.Test | Sort-Object) -Separator ", "

        Write-Host -Object "`n### Detailed Output ###"
        $FailedTests | Sort-Object Test | ForEach-Object {
            Write-Host -Object ""
            Write-Host -Object ($_.Result | Out-String)
            Write-Host -Object ""
        }
    }
    else {
        Write-Host -Object "All Directory Server Diagnosis Tests Pass!"
    }

    exit $ExitCode
}
end {
    
    
    
}

 

Description détaillée

Caractéristiques du script

1. Vérification des privilèges administrateur
   Le script commence par vérifier qu’il s’exécute avec des privilèges élevés, en s’assurant qu’il dispose des autorisations nécessaires pour exécuter les commandes de diagnostic.
2. Validation du contrôleur de domaine
   Il vérifie si le script est exécuté sur un contrôleur de domaine. Si ce n’est pas le cas, il se termine de manière élégante avec un message d’erreur approprié.
3. Exécution des tests DCDiag
   Une série de tests DCDiag critiques sont effectués, y compris des contrôles de connectivité, de publicité, de réplication, de journaux système, etc. Les résultats sont analysés pour séparer les tests réussis de ceux qui échouent.
4. Catégorisation des résultats
   Les résultats sont divisés en catégories de réussite et d’échec, avec des résultats détaillés pour tous les tests échoués. Cela permet aux administrateurs de se concentrer sur les problèmes qui nécessitent une attention immédiate.
5. Rapports facultatifs sur les champs personnalisés
   Le script prend en charge un paramètre facultatif permettant d’afficher les résultats dans un champ personnalisé WYSIWYG (What You See Is What You Get), utile pour l’intégration avec des outils tels que NinjaOne.
6. Génération de rapports HTML
   Pour une meilleure lisibilité, le script génère un rapport HTML qui résume les résultats des tests dans un format visuellement intuitif, y compris les pourcentages de réussite et d’échec.

Résumé du flux de travail

1. Valider les conditions préalables : Privilèges administrateur et environnement du contrôleur de domaine.
2. Exécuter les tests DCDiag et saisir les résultats.
3. Classer et afficher les résultats.
4. Générer un rapport HTML optionnel pour l’intégration de champs personnalisés.

Cas d’utilisation potentiels

Scénario concret

Prenons l’exemple d’un administrateur informatique chargé de gérer un environnement AD multi-site. L’un des contrôleurs de domaine commence à rencontrer des échecs d’authentification intermittents. L’administrateur exécute ce script sur le serveur concerné pour diagnostiquer le problème. Le résultat met en évidence les échecs des tests Advertising et LocatorCheck , ce qui indique des problèmes de synchronisation temporelle et de disponibilité des rôles PDC. Les résultats détaillés permettent à l’administrateur d’identifier et de résoudre rapidement l’origine du problème et de rétablir le fonctionnement normal de l’entreprise.

Comparaisons

Contrôles manuels de l’intégrité d’AD

L’exécution manuelle des tests DCDiag nécessite un investissement en temps important, notamment pour l’analyse et l’interprétation des résultats. Ce script automatise l’ensemble du processus, en fournissant des résultats structurés et des options d’intégration.

Outils basés sur une interface graphique

Si les outils GUI comme AD Manager ou RSAT offrent une interface conviviale pour les contrôles d’intégrité d’AD, ils manquent souvent de la flexibilité et des capacités d’automatisation des scripts PowerShell. Ce script est particulièrement avantageux pour les MSP qui gèrent plusieurs environnements clients.

FAQ

1. Ce script peut-il être exécuté sur n’importe quel serveur ?
   Non, il doit être exécuté sur un contrôleur de domaine. Les environnements non-DC déclencheront une erreur.
2. Quelles sont les autorisations requises ?
   Les privilèges d’administrateur sont obligatoires pour exécuter le script avec succès.
3. Les résultats peuvent-ils être exportés vers un fichier ?
   Oui, le script comprend une option permettant de générer un rapport HTML pour l’intégration des champs personnalisés.
4. Comment les tests échoués sont-ils mis en évidence ?
   Les tests qui ont échoué sont répertoriés séparément avec des messages de diagnostic détaillés, ce qui permet de hiérarchiser les efforts de dépannage.

Implications

Les résultats de ce script peuvent révéler des vulnérabilités critiques dans votre environnement AD, telles que des échecs de réplication ou des rôles mal configurés. Si elles ne sont pas résolues, ces questions peuvent entraîner des problèmes d’authentification généralisés, des applications erronées des politiques et des risques pour la sécurité.

Recommandations

• Exécutez-le régulièrement : planifiez l’exécution périodique du script afin d’assurer une surveillance continue de l’intégrité d’AD.
• Analysez les tendances : Comparez les résultats dans le temps pour identifier les problèmes récurrents.
• Intégration avec les outils de surveillance : Utilisez l’option de champ personnalisé pour intégrer les résultats dans des outils tels que NinjaOne pour un suivi centralisé.

Conclusion

Ce script PowerShell offre une solution rationalisée et automatisée pour effectuer des contrôles de santé AD, réduisant ainsi le temps et les efforts requis pour les diagnostics manuels. En identifiant les problèmes à un stade précoce, les professionnels de l’informatique peuvent traiter de manière proactive les perturbations potentielles, garantissant ainsi un environnement Active Directory stable et sécurisé. Pour les MSP, des outils comme NinjaOne complètent ce script en fournissant une plateforme centralisée pour la gestion et le contrôle des opérations informatiques. Ensemble, ils constituent une stratégie solide pour maintenir l’intégrité informatique de l’entreprise.