Hinzufügen und Verwalten von Antivirus-Überschreibungen mit PowerShell

Die Virenschutzverwaltung ist ein wichtiger Aspekt der IT-Verwaltung, insbesondere für Managed Service Provider (MSPs) und IT-Experten, die mit der Überwachung großer Geräteflotten betraut sind. Die effiziente Konfiguration oder das Außerkraftsetzen von Antiviren-Einstellungen auf mehreren Endgeräten kann Zeit sparen, die Einhaltung von Vorschriften gewährleisten und die Sicherheit aufrechterhalten. Das mitgelieferte PowerShell-Skript bietet eine robuste Lösung für das strukturierte und automatisierte Festlegen von Antiviren-Überschreibungen oder das Entfernen vorhandener Überschreibungen.

Kontext

In IT-Umgebungen sind Administratoren häufig mit Szenarien konfrontiert, in denen sie Antiviren-Konfigurationen für alle Endgeräte standardisieren müssen. Dies kann die Angabe von Antiviren-Versionen, -Status und -Stand umfassen, um den tatsächlichen Sicherheitsstatus von Geräten wiederzugeben oder um gemeldete Informationen aus Gründen der Compliance zu überschreiben. Das Skript dient als Werkzeug, um entweder Antiviren-Details hinzuzufügen oder zu aktualisieren oder Überschreibungen ganz zu entfernen. Es ist besonders nützlich für MSPs, die verschiedene Kundenumgebungen mit Tools wie NinjaOne verwalten.

Durch die Nutzung von PowerShell optimiert dieses Skript die Abläufe, beseitigt manuelle Fehler und sorgt für Konsistenz bei der Virenschutzverwaltung. Seine Fähigkeit, Überschreibungen programmatisch zu verarbeiten, macht es zu einem Vorteil für IT-Experten, die zahlreiche Geräte verwalten oder unternehmensweite Sicherheitsstandards durchsetzen wollen.

Das Skript zur Optimierung der Hintergrund-Verwaltung

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

Sparen Sie Zeit mit über 300+ Skripten aus dem NinjaOne Dojo.

→ Erhalten Sie noch heute Zugang.

Detaillierte Aufschlüsselung des Skripts

Erste Validierung und Parameter

Das Skript beginnt mit der Übergabe mehrerer Parameter:

AntivirusName: Name des Antivirus, der in den Gerätedetails angezeigt werden soll.
AntivirusVersion: Versionsnummer des Antivirusprogramms.
AntivirusStatus: Status des Virenschutzes, z. B. “Up-to-Date” oder “Out-of-Date”.
AntivirusState: Betriebszustand des Antivirenprogramms, z. B. “EIN” oder “AUS”.
Anhängen: Ein Schalter zum Hinzufügen oder Aktualisieren einer bestehenden Außerkraftsetzung.
RemoveOverride: Ein Schalter zum Entfernen aller Überschreibungen.

Das Skript validiert diese Eingaben, indem es sicherstellt, dass die Antivirenversion nur numerische Zeichen und Punkte enthält und dass Status und Zustand innerhalb der vordefinierten gültigen Werte liegen.

Privilegienkontrollen

Um unbefugte Änderungen zu verhindern, stellt das Skript sicher, dass es mit Administratorrechten ausgeführt wird. Ist dies nicht der Fall, bricht es mit einer Fehlermeldung ab.

Übersteuerungsmanagement

Überschreibungen entfernen: Wenn RemoveOverride angegeben ist, löscht das Skript alle vorhandenen Überschreibungsdateien (av_override.json) im NinjaRMMAgent-Verzeichnis.
Überschreibungen hinzufügen oder aktualisieren: Für andere Vorgänge wird das Skript verwendet:
Überprüft, ob der Anpassungsordner vorhanden ist, und erstellt ihn gegebenenfalls.
Liest vorhandene Überschreibungen, wenn Append angegeben ist, und aktualisiert sie, wenn der Name des Antivirus übereinstimmt, oder fügt einen neuen Eintrag hinzu, wenn dies nicht der Fall ist.
Speichert die neuen oder aktualisierten Überschreibungsinformationen im JSON-Format.

Fehlerbehandlung und Protokollierung

Das Skript enthält eine robuste Fehlerbehandlung, protokolliert alle Probleme, die bei Datei- oder Verzeichnisoperationen auftreten, und gibt klare Fehlermeldungen aus, um die Benutzer anzuleiten.

Potenzielle Anwendungsfälle

Hypothetisches Szenario

Ein MSP, der eine Flotte von 500 Geräten verwaltet, stellt fest, dass einige Endgeräte aufgrund von Kompatibilitätsproblemen veraltete Antivirendefinitionen falsch melden. Mit diesem Skript kann der MSP:

Setzen Sie den gemeldeten Status für die betroffenen Geräte auf “Up-to-Date” um.
Sicherstellen, dass die Konformitätsberichte die Sicherheitslage des Unternehmens genau wiedergeben.
Automatisieren Sie den Prozess, indem Sie das Skript in die Arbeitsabläufe der Geräteverwaltung integrieren.

Dieser Ansatz erspart stundenlange manuelle Aktualisierungen und gewährleistet gleichzeitig eine standardisierte Sicherheitskonfiguration.

Vergleiche mit anderen Methoden

Der Ansatz des Skripts bietet mehrere Vorteile gegenüber manuellen oder GUI-basierten Konfigurationen:

Wirkungsgrad: Änderungen können in Sekundenschnelle auf mehrere Geräte übertragen werden.
Reproduzierbarkeit: Das Skript kann mit unterschiedlichen Parametern für verschiedene Szenarien wiederverwendet werden.
Automatisierungsfreundlich: Im Gegensatz zu manuellen Methoden kann es in umfassendere IT-Management-Workflows integriert werden.

Im Vergleich zu fortschrittlichen Tools für die Fernüberwachung und -verwaltung (RMM) bietet das Skript eine leichtgewichtige Alternative, die keine spezielle Software für grundlegende Antiviren-Überbrückungsaufgaben erfordert.

FAQs

Was passiert, wenn ich keinen Namen für das Antivirusprogramm angebe?
Das Skript bricht mit einem Fehler ab, da der Name des Antivirus erforderlich ist, es sei denn, Sie entfernen die Überschreibungen.
Kann dieses Skript auch unter älteren Windows-Versionen verwendet werden?
Nein, das Skript ist für Windows 10 und Windows Server 2016 oder neuer konzipiert.
Was sollte ich tun, wenn ein Fehler bei der Dateiberechtigung auftritt?
Stellen Sie sicher, dass das Skript mit Administratorrechten ausgeführt wird.
Ist die Außerkraftsetzung dauerhaft?
Die Außerkraftsetzung bleibt bestehen, bis sie mit dem Parameter RemoveOverride entfernt oder manuell gelöscht wird.

Auswirkungen der Ergebnisse des Skripts

Durch die genaue Verwaltung von Antiviren-Details stellt dieses Skript sicher, dass der Sicherheitsstatus des Geräts konsistent gemeldet wird. Es mindert das Risiko von Konformitätsfehlern aufgrund falscher Statusmeldungen und unterstützt Unternehmen bei der Aufrechterhaltung einer starken Sicherheitslage. Der Missbrauch von Überschreibungen könnte jedoch dazu führen, dass Geräte als sicher gemeldet werden, obwohl sie es nicht sind, was die Notwendigkeit einer sorgfältigen und sachkundigen Nutzung unterstreicht.

Empfehlungen für bewährte Praktiken

Überprüfen Sie immer die Antivireninformationen, bevor Sie Überschreibungen anwenden.
Verwenden Sie Append mit Bedacht, um ein versehentliches Überschreiben wichtiger Details zu vermeiden.
Führen Sie das Skript in einer kontrollierten Umgebung aus oder testen Sie seine Auswirkungen auf ein einzelnes Gerät, bevor Sie es in der gesamten Flotte einsetzen.
Überprüfen und aktualisieren Sie die Überschreibungen regelmäßig, um den aktuellen Zustand der Geräte korrekt wiederzugeben.

Abschließende Überlegungen

Dieses PowerShell-Skript bietet IT-Experten ein praktisches Tool für die Verwaltung von Antivirus-Konfigurationen auf Endgeräten. Es ist besonders wertvoll für Umgebungen, die über NinjaOne verwaltet werden, wo Konsistenz und Effizienz von größter Bedeutung sind. Durch die Integration dieses Skripts in ihre Arbeitsabläufe können MSPs und IT-Administratoren ihre Abläufe optimieren, die Einhaltung von Vorschriften gewährleisten und genaue Sicherheitsberichte erstellen.