Aggiungere e gestire le eccezioni antivirus con PowerShell 

La gestione dell’antivirus è un aspetto critico dell’amministrazione IT, in particolare per i fornitori di servizi gestiti (MSP) e i professionisti IT incaricati di supervisionare un gran numero di dispositivi. Configurare le impostazioni degli antivirus o impostare eccezioni in modo efficiente su più endpoint può far risparmiare tempo, garantire la conformità e aiutare a mantenere la postura di sicurezza. Lo script PowerShell fornito offre una soluzione solida per gestire le eccezioni antivirus, aggiungendone o rimuovendo quelle esistenti in modo strutturato e automatizzato.

Contesto

Negli ambienti IT, gli amministratori si trovano spesso a dover standardizzare le configurazioni antivirus tra gli endpoint. Ciò può includere l’indicazione di versioni, aggiornamento e operatività dell’antivirus per riflettere l’effettiva situazione di sicurezza dei dispositivi o per ignorare le informazioni riportate per motivi di conformità. Lo script serve come strumento per aggiungere o aggiornare i dettagli dell’antivirus o per rimuovere del tutto le eccezioni. È particolarmente utile per gli MSP che gestiscono ambienti di clienti diversi attraverso strumenti come NinjaOne.

Sfruttando PowerShell, questo script semplifica le operazioni per gestire le eccezioni antivirus, elimina gli errori manuali e garantisce la coerenza della gestione antivirus. La capacità di gestire le eccezioni in modo sistematico lo rende una risorsa per i professionisti IT che gestiscono numerosi dispositivi o per coloro che cercano di applicare gli standard di sicurezza a livello aziendale.

Lo script per gestire le eccezioni antivirus:

#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 {
    
    
    
}

 

Descrizione dettagliata dello script per gestire le eccezioni antivirus

Convalida iniziale e parametri

Lo script per gestire le eccezioni antivirus inizia accettando diversi parametri:

• AntivirusName: Nome dell’antivirus da visualizzare nei dettagli del dispositivo.
• AntivirusVersion: Numero di versione dell’antivirus.
• AntivirusStatus: Stato dell’antivirus, per esempio “Aggiornato” o “Non aggiornato”.
• AntivirusState: Stato operativo dell’antivirus, ad esempio “Attivo” o “Non attivo”.
• Append: Uno switch per aggiungere un’eccezione o aggiornare un’eccezione esistente.
• RemoveOverride: Uno switch per rimuovere tutte le eccezioni.

Lo script per gestire le eccezioni antivirus convalida questi input, assicurandosi che la versione dell’antivirus contenga solo caratteri numerici e punti e che lo stato di aggiornamento e la condizione operativa rientrino in valori validi predefiniti.

Controllo dei privilegi

Per evitare modifiche non autorizzate, lo script per gestire le eccezioni antivirus deve essere eseguito con privilegi di amministratore. In caso contrario, termina con un messaggio di errore.

Gestione delle eccezioni

1. Rimuovere le eccezioni: Se viene specificato il parametro RemoveOverride, lo script per gestire le eccezioni antivirus elimina qualsiasi file di override esistente (av_override.json) nella directory NinjaRMMAgent.
2. Aggiungere o aggiornare le eccezioni: Per altre operazioni, lo script per gestire le eccezioni antivirus:
3. Controlla l’esistenza della cartella di personalizzazione e la crea se necessario.
4. Legge le eccezioni esistenti se è specificato il parametro Append, aggiornandole se il nome dell’antivirus corrisponde o aggiungendo una nuova voce in caso contrario.
5. Salva le informazioni sulle eccezioni nuove o aggiornate in formato JSON.

Gestione e registrazione degli errori

Lo script per gestire le eccezioni antivirus incorpora una solida gestione degli errori, registrando qualsiasi problema riscontrato durante le operazioni su file o directory e fornendo chiari messaggi di errore per guidare gli utenti.

Casi d’uso potenziali

Scenario ipotetico

Un MSP che gestisce un parco di 500 dispositivi nota che alcuni endpoint riportano erroneamente definizioni antivirus obsolete a causa di problemi di compatibilità. Utilizzando questo script per gestire le eccezioni antivirus, l’MSP può:

• Sostituire lo stato riportato a “Aggiornato” per i dispositivi interessati.
• Garantire che i rapporti di conformità riflettano accuratamente la posizione di sicurezza dell’organizzazione.
• Automatizzare il processo integrando lo script nei flussi di lavoro di gestione dei dispositivi.

Questo approccio consente di risparmiare ore di aggiornamenti manuali, mantenendo una configurazione di sicurezza standardizzata.

Confronto con altri metodi

L’approccio dello script per gestire le eccezioni antivirus offre diversi vantaggi rispetto alle configurazioni manuali o basate su GUI:

• Efficienza: Le modifiche possono essere applicate a più dispositivi in pochi secondi.
• Ripetibilità: Lo script può essere riutilizzato con parametri diversi per vari scenari.
• Facile da automatizzare: A differenza dei metodi manuali, può essere integrato in flussi di lavoro di gestione IT più ampi.

Rispetto agli strumenti avanzati di monitoraggio e gestione da remoto (RMM), lo script offre un’alternativa leggera per gestire le eccezioni antivirus, che non richiede software specializzato per le attività di base relative alle eccezioni dell’antivirus.

Domande frequenti

1. Cosa succede se non specifico il nome di un antivirus?
   Lo script per gestire le eccezioni antivirus terminerà con un errore, poiché il nome dell’antivirus è richiesto a meno che non si rimuovano le eccezioni.
2. Questo script per gestire le eccezioni antivirus può essere utilizzato su versioni precedenti di Windows?
   No, lo script per gestire le eccezioni antivirus è progettato per Windows 10 e Windows Server 2016 e versioni successive.
3. Cosa devo fare se riscontro un errore di autorizzazione di un file?
   Assicurati che lo script per gestire le eccezioni antivirus venga eseguito con privilegi di amministratore.
4. Le eccezioni impostate sono permanenti?
   L’eccezione persiste finché non viene rimossa utilizzando il parametro RemoveOverride o eliminata manualmente.

Implicazioni dei risultati dello script per gestire le eccezioni antivirus

Gestendo accuratamente i dettagli dell’antivirus, questo script assicura che gli stati di sicurezza del dispositivo siano segnalati in modo coerente. Riduce il rischio di fallimenti della conformità dovuti a un’errata segnalazione dello stato e aiuta le organizzazioni a mantenere una solida posizione di sicurezza. Tuttavia, un uso improprio delle eccezioni potrebbe far sì che i dispositivi vengano segnalati come sicuri quando non lo sono, evidenziando la necessità di un uso attento e consapevole.

Raccomandazioni e best practice

• Verifica sempre le informazioni generate dall’antivirus prima di applicare le eccezioni.
• Usa il parametro Append con cautela per evitare di sovrascrivere inavvertitamente dettagli importanti.
• Esegui lo script per gestire le eccezioni antivirus in un ambiente controllato o testane l’impatto su un singolo dispositivo prima di distribuirlo su tutto il parco dispositivi.
• Ricontrolla e aggiorna regolarmente le eccezioni per riflettere accuratamente lo stato attuale dei dispositivi.

Considerazioni finali

Questo script PowerShell fornisce ai professionisti IT uno strumento pratico per gestire le configurazioni antivirus sugli endpoint. È particolarmente utile per gli ambienti gestiti tramite NinjaOne, dove coerenza ed efficienza sono fondamentali. Integrando questo script nei flussi di lavoro, gli MSP e gli amministratori IT possono semplificare le operazioni, garantire la conformità e mantenere una reportistica di sicurezza accurata.