Ajout et gestion d’exclusions antivirus avec PowerShell 

La gestion des antivirus est un aspect essentiel de l’administration informatique, en particulier pour les fournisseurs de services gérés (MSP) et les professionnels de l’informatique chargés de superviser de grandes flottes d’appareils. Configurer ou remplacer efficacement les paramètres antivirus sur plusieurs terminaux permet de gagner du temps, de garantir la conformité et de maintenir la posture de sécurité. Le script PowerShell fourni offre une solution efficace pour définir les exclusions antivirus ou les supprimer de manière structurée et automatisée.

Contexte

Dans les environnements informatiques, les administrateurs sont souvent confrontés à des scénarios dans lesquels ils doivent standardiser les configurations antivirus sur les terminaux. Il peut s’agir de spécifier des versions, des statuts et des états d’antivirus afin de refléter l’état de sécurité réel des appareils ou de remplacer les informations rapportées pour des raisons de conformité. Le script sert d’outil pour ajouter ou mettre à jour les détails de l’antivirus ou pour supprimer complètement les exclusions. Il est particulièrement utile pour les entreprises MSP qui gèrent divers environnements clients à l’aide d’outils tels que NinjaOne.

En s’appuyant sur PowerShell, ce script rationalise les opérations, élimine les erreurs manuelles et garantit la cohérence de la gestion des antivirus. Sa capacité à gérer les exclusions de manière programmatique en fait un atout pour les professionnels de l’informatique qui gèrent de nombreux appareils ou qui cherchent à appliquer des normes de sécurité à l’échelle de l’entreprise.

Le script :

#Requires -Version 5.1

<#
.SYNOPSIS
    Add an antivirus to the device details or override the existing antivirus information.
.DESCRIPTION
    Add an antivirus to the device details or override the existing antivirus information.

    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).
.EXAMPLE
    -AntivirusName "My AV" -AntivirusVersion "1.0.1" -AntivirusStatus "Out-of-Date" -AntivirusState "ON"

    Creating customization folder.


        Directory: C:\ProgramData\NinjaRMMAgent


    Mode                 LastWriteTime         Length Name                                                                 
    ----                 -------------         ------ ----                                                                 
    d-----         6/19/2024   4:09 PM                Customization                                                        
    Successfully created customization folder.

    Applying override.
    Successfully applied override.

PARAMETER: -AntivirusName "ReplaceMeWithNameOfAnAntivirus"
    Name of the antivirus you would like to appear in the device details.

PARAMETER: -AntivirusVersion "1.0.2"
    Specify the version number of the antivirus.

PARAMETER: -AntivirusStatus "Up-to-Date"
    Specify whether the antivirus definitions are up-to-date, out-of-date, or unknown.

PARAMETER: -AntivirusState "ON"
    Specify the current status of the antivirus.

PARAMETER: -Append
    Append or update an existing override.
    
PARAMETER: -RemoveOverride
    Remove all existing overrides.

.NOTES
    Minimum OS Architecture Supported: Windows 10, Windows Server 2016
    Release Notes: Initial Release
#>

[CmdletBinding()]
param (
    [Parameter()]
    [String]$AntivirusName,
    [Parameter()]
    [String]$AntivirusVersion,
    [Parameter()]
    [String]$AntivirusStatus,
    [Parameter()]
    [String]$AntivirusState,
    [Parameter()]
    [Switch]$Append = [System.Convert]::ToBoolean($env:append),
    [Parameter()]
    [Switch]$RemoveOverride = [System.Convert]::ToBoolean($env:removeOverride)
)

begin {
    # Replace command line paramets with the form variables if used.
    if ($env:avName -and $env:avName -notlike "null") { $AntivirusName = $env:avName }
    if ($env:avVersion -and $env:avVersion -notlike "null") { $AntivirusVersion = $env:avVersion }
    if ($env:avStatus -and $env:avStatus -notlike "null") { $AntivirusStatus = $env:avStatus }
    if ($env:avState -and $env:avState -notlike "null") { $AntivirusState = $env:avState }

    # Check if RemoveOverride is set and any of the other parameters are also set
    if ($RemoveOverride -and ($AntivirusState -or $AntivirusStatus -or $AntivirusVersion -or $AntivirusName -or $Append)) {
        Write-Host -Object "[Error] Cannot remove an override and add an override at the same time."
        exit 1
    }

    # Check if AntivirusName is not provided and RemoveOverride is not set
    if (!$AntivirusName -and !$RemoveOverride) {
        Write-Host $RemoveOverride
        if ($Append) {
            Write-Host -Object "[Error] Antivirus name was not given. The antivirus name is required when updating or adding a new override!"
        }
        else {
            Write-Host -Object "[Error] Antivirus name was not given. Antivirus name, state, and status are required when adding a new override!"
        }

        exit 1
    }

    # Validate AntivirusVersion for invalid characters
    if ($AntivirusVersion -and $AntivirusVersion -match '[^0-9\.]') {
        Write-Host -Object "[Error] The antivirus version given contains an invalid character. Only the following characters are allowed: '0-9' and '.'"
        exit 1
    }

    # Check if AntivirusStatus is not provided and neither RemoveOverride nor Append is set
    if (!$AntivirusStatus -and !$RemoveOverride -and !$Append) {
        Write-Host -Object "[Error] Antivirus status was not given. Antivirus name, state, and status are required!"
        exit 1
    }

    # Define valid antivirus statuses
    $ValidStatus = "Up-to-Date", "Out-of-Date", "Unknown"
    # Check if the provided AntivirusStatus is valid
    if ($AntivirusStatus -and $ValidStatus -notcontains $AntivirusStatus) {
        Write-Host -Object "[Error] An invalid antivirus status was given. Only the following statuses are valid: 'Up-to-Date', 'Out-of-Date', and 'Unknown'."
        exit 1
    }

    # Check if AntivirusState is not provided and neither RemoveOverride nor Append is set
    if (!$AntivirusState -and !$RemoveOverride -and !$Append) {
        Write-Host -Object "[Error] Antivirus state was not given. Antivirus name, state, and status are required!"
        exit 1
    }

    # Define valid antivirus states
    $ValidState = "ON", "OFF", "EXPIRED", "SNOOZED", "UNKNOWN"
    # Check if the provided AntivirusState is valid
    if ($AntivirusState -and $ValidState -notcontains $AntivirusState) {
        Write-Host -Object "[Error] An invalid antivirus state was given. Only the following states are valid: 'ON', 'OFF', 'EXPIRED', 'SNOOZED', and 'UNKNOWN'."
        exit 1
    }

    # Check if the NinjaRMMAgent directory exists
    if (!(Test-Path -Path "$env:ProgramData\NinjaRMMAgent")) {
        Write-Host -Object "[Error] Ninja Agent is not present at '$env:ProgramData\NinjaRMMAgent'."
        exit 1
    }

    # Function to check if the script is running with elevated privileges
    function Test-IsElevated {
        $id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
        $p = New-Object System.Security.Principal.WindowsPrincipal($id)
        $p.IsInRole([System.Security.Principal.WindowsBuiltInRole]::Administrator)
    }

    # Set ExitCode to 0 if it is not already set
    if (!$ExitCode) {
        $ExitCode = 0
    }
}
process {
    # Check if the script is running with elevated privileges
    if (!(Test-IsElevated)) {
        Write-Host -Object "[Error] Access denied. Please run with administrator privileges."
        exit 1
    }

    # Check if RemoveOverride is set
    if ($RemoveOverride) {
        # Check if the antivirus override file exists
        if (Test-Path -Path "$env:ProgramData\NinjaRMMAgent\Customization\av_override.json" -ErrorAction SilentlyContinue) {
            Write-Host -Object "Removing $env:ProgramData\NinjaRMMAgent\Customization\av_override.json file."

            # Attempt to remove the antivirus override file
            try {
                Remove-Item -Path "$env:ProgramData\NinjaRMMAgent\Customization\av_override.json" -ErrorAction Stop
            }
            catch {
                Write-Host -Object "[Error] Failed to remove antivirus override."
                Write-Host -Object "[Error] $($_.Exception.Message)"
                exit 1
            }
        }
        else {
            Write-Host -Object "Antivirus override is not currently set."
        }

        exit $ExitCode
    }

    # Check if the Customization directory exists, if not, create it
    if (!(Test-Path -Path "$env:ProgramData\NinjaRMMAgent\Customization" -ErrorAction SilentlyContinue)) {
        try {
            Write-Host -Object "Creating customization folder."
            New-Item -Path "$env:ProgramData\NinjaRMMAgent\Customization" -ItemType Directory -Force -ErrorAction Stop
            Write-Host -Object "Successfully created customization folder.`n"
        }
        catch {
            Write-Host -Object "[Error] Unable to create customization folder."
            Write-Host -Object "[Error] $($_.Exception.Message)"
            exit 1
        }
    }

    # Initialize a list to hold antivirus overrides
    $AntivirusOverrides = New-Object System.Collections.Generic.List[Object]

    # If Append is set and the antivirus override file exists, retrieve current overrides
    if ($Append -and (Test-Path -Path "$env:ProgramData\NinjaRMMAgent\Customization\av_override.json" -ErrorAction SilentlyContinue)) {
        try {
            $CurrentOverrides = Get-Content -Path "$env:ProgramData\NinjaRMMAgent\Customization\av_override.json" -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop | Select-Object -ExpandProperty "av_override" -ErrorAction Stop
        }
        catch {
            Write-Host -Object "[Error] Failed to retrieve current overrides."
            Write-Host -Object "[Error] $($_.Exception.Message)"
            exit 1
        }

        # Iterate over current overrides to update or add new overrides
        $CurrentOverrides | ForEach-Object {
            if ($AntivirusName -notmatch [Regex]::Escape($_.av_name)) {
                $AntivirusOverrides.Add($_)
                return
            }

            Write-Host -Object "An existing antivirus with the same name was detected. Updating the existing entry.`n"

            $AntivirusOverrides.Add(
                [PSCustomObject]@{
                    av_name    = $AntivirusName
                    av_version = if ($AntivirusVersion) { $AntivirusVersion }else { $_.av_version }
                    av_status  = if ($AntivirusStatus) { $AntivirusStatus }else { $_.av_status }
                    av_state   = if ($AntivirusState) { $AntivirusState }else { $_.av_state }
                }
            )

            $UpdatedOverride = $True
        }
    }

    # If Append is set but no override was updated, check for required parameters
    if ($Append -and !$UpdatedOverride -and (!$AntivirusStatus -or !$AntivirusState)) {
        Write-Host -Object "[Error] Antivirus name, state, and status are required when adding a new override!"
        exit 1
    }
    elseif ($Append) {
        Write-Host -Object "Adding override to the existing list of overrides.`n"
    }

    # If no override was updated, add a new override
    if (!$UpdatedOverride) {
        $AntivirusOverrides.Add(
            [PSCustomObject]@{
                av_name    = $AntivirusName
                av_version = $AntivirusVersion
                av_status  = $AntivirusStatus
                av_state   = $AntivirusState
            }
        )
    }

    # Attempt to apply the override by writing to the override file
    try {
        Write-Host -Object "Applying override."
        $AntivirusOverrideJSON = [PSCustomObject]@{
            av_override = $AntivirusOverrides
        } | ConvertTo-Json -ErrorAction Stop

        $AntivirusOverrideJSON | Out-File -FilePath "$env:ProgramData\NinjaRMMAgent\Customization\av_override.json" -Encoding "utf8" -Force -ErrorAction Stop
        Write-Host -Object "Successfully applied override."
    }
    catch {
        Write-Host -Object "[Error] Unable to create override."
        Write-Host -Object "[Error] $($_.Exception.Message)"
        exit 1
    }

    exit $ExitCode
}
end {
    
    
    
}

 

Description détaillée du script d’exclusions antivirus

Validation initiale et paramètres

Le script commence par accepter plusieurs paramètres :

• AntivirusName : Nom de l’antivirus à afficher dans les détails de l’appareil.
• AntivirusVersion : Numéro de version de l’antivirus.
• AntivirusStatus : État de l’antivirus, tel que “Up-to-Date” (à jour) ou “Out-of-Date” (obsolète).
• AntivirusState : État opérationnel de l’antivirus, tel que “ON” (activé) ou “OFF” (désactivé).
• Append : Un commutateur pour ajouter ou mettre à jour une exception existante.
• RemoveOverride : Un commutateur pour supprimer toutes les exclusions.

Le script valide ces entrées, en s’assurant que la version de l’antivirus ne contient que des caractères numériques et des points et que le statut et l’état sont compris dans des valeurs valides prédéfinies.

Contrôle des privilèges

Pour éviter toute modification non autorisée, le script s’assure qu’il est exécuté avec des privilèges d’administrateur. Si ce n’est pas le cas, il se termine par un message d’erreur.

Gestion des exclusions

1. Supprimer les exclusions : Si RemoveOverride est spécifié, le script supprime tout fichier d’annulation existant (av_override.json) dans le répertoire NinjaRMMAgent.
2. Ajouter ou mettre à jour des exclusions : Pour les autres opérations, le script :
3. Vérifie l’existence du dossier de personnalisation et le crée si nécessaire.
4. Lit les exclusions existantes si Append est spécifié, les met à jour si le nom de l’antivirus correspond ou ajoute une nouvelle entrée si ce n’est pas le cas.
5. Enregistre les informations de remplacement nouvelles ou mises à jour au format JSON.

Gestion des erreurs et journalisation

Le script intègre une gestion efficace des erreurs, enregistrant tous les problèmes rencontrés lors des opérations sur les fichiers ou les répertoires et fournissant des messages d’erreur clairs pour guider les utilisateurs.

Cas d’utilisation potentiels

Scénario hypothétique

Un MSP gérant un parc de 500appareils remarque que certains terminaux signalent de manière incorrecte des définitions antivirus obsolètes en raison de problèmes de compatibilité. À l’aide de ce script, l’enteprise MSP peut :

• Remplacer l’état signalé par “Up-to-Date” (à jour) pour les appareils concernés.
• Veiller à ce que les rapports de conformité reflètent fidèlement la position de l’entreprise en matière de sécurité.
• Automatiser le processus en intégrant le script dans leurs flux de travail de gestion des appareils.

Cette approche permet d’économiser des heures de mises à jour manuelles tout en maintenant une configuration de sécurité standardisée.

Comparaisons avec d’autres méthodes

L’approche du script présente plusieurs avantages par rapport aux configurations manuelles ou basées sur l’interface graphique :

• Efficacité : Les modifications peuvent être appliquées à plusieurs appareils en quelques secondes.
• Répétabilité : Le script peut être réutilisé avec différents paramètres pour divers scénarios.
• Facile à automatiser : Contrairement aux méthodes manuelles, il peut être intégré dans des flux de travail plus larges de gestion des technologies de l’information.

Par rapport aux outils avancés de surveillance et de gestion à distance (RMM), le script offre une alternative légère qui ne nécessite pas de logiciel spécialisé pour les tâches de base d’exclusions de l’antivirus.

FAQ

1. Que se passe-t-il si je ne spécifie pas de nom d’antivirus ?
   Le script se terminera par une erreur, car le nom de l’antivirus est obligatoire, sauf si l’on supprime les exclusions.
2. Ce script peut-il être utilisé sur d’anciennes versions de Windows ?
   Non, le script est conçu pour Windows 10 et Windows Server 2016 ou ultérieur.
3. Que dois-je faire si je rencontre une erreur de permission de fichier ?
   Assurez-vous que le script est exécuté avec des privilèges d’administrateur.
4. L’exception est-elle permanente ?
   L’exception persiste jusqu’à ce qu’elle soit supprimée à l’aide du paramètre RemoveOverride ou qu’elle soit supprimée manuellement.

Implications des résultats du script

En gérant avec précision les détails de l’antivirus, ce script garantit que les états de sécurité de l’appareil sont signalés de manière cohérente. Il réduit le risque de non-conformité dû à des rapports d’état incorrects et aide les entreprises à maintenir une position de sécurité solide. Toutefois, une mauvaise utilisation des exclusions pourrait conduire à ce que des dispositifs soient signalés comme étant sécurisés alors qu’ils ne le sont pas, ce qui souligne la nécessité d’une utilisation prudente et informée.

Recommandations de bonnes pratiques

• Vérifiez toujours les informations relatives à l’antivirus avant d’appliquer des modifications.
• Utilisez Append avec prudence pour éviter d’écraser des détails importants par inadvertance.
• Exécutez le script dans un environnement contrôlé ou testez son impact sur un seul appareil avant de le déployer sur l’ensemble du parc.
• Réviser et mettre à jour régulièrement les exclusions pour qu’elles reflètent avec précision l’état actuel des appareils.

Conclusion

Ce script PowerShell fournit aux professionnels de l’informatique un outil pratique pour gérer les configurations antivirus sur les terminaux. Il est particulièrement utile pour les environnements gérés par NinjaOne, où la cohérence et l’efficacité sont primordiales. En intégrant ce script dans leurs flux de travail, les entreprises MSP et les administrateurs informatiques peuvent rationaliser les opérations, garantir la conformité et maintenir des rapports de sécurité précis.