Wie man die Existenz von Dateien oder Ordnern unter Windows mit einem PowerShell-Skript überprüft

In der modernen IT-Welt kann die Verwaltung und Pflege von Dateisystemen auf zahlreichen Servern und Workstations eine Herausforderung darstellen. IT-Experten und Managed Service Provider (MSPs) müssen häufig bestimmte Dateien und Verzeichnisse überwachen, um die Compliance, Sicherheit und betriebliche Effizienz zu gewährleisten.

Eine zuverlässige Methode zur Bewältigung dieser Aufgabe ist die Verwendung von PowerShell-Skripten, die Automatisierung und detaillierte Kontrolle über Windows-Umgebungen bietet. Das mitgelieferte PowerShell-Skript wurde entwickelt, um Benutzer:innen zu benachrichtigen, wenn eine bestimmte Datei oder ein bestimmter Ordner innerhalb eines bestimmten Verzeichnisses oder Unterverzeichnisses gefunden wird, was es zu einem wertvollen Tool für IT-Experten macht.

Kontext

Die Überwachung des Vorhandenseins und des Speicherorts von Dateien ist aus mehreren Gründen wichtig. Dieser Prozess hilft bei der Aufrechterhaltung der Sicherheit, indem er sicherstellt, dass keine unautorisierten Dateien vorhanden sind, unterstützt die Compliance, indem es überprüft, ob die erforderlichen Dateien zur Verfügung stehen, und hilft bei der betrieblichen Effizienz durch die Automatisierung von Routineprüfungen. Dieses Skript ist besonders nützlich für IT-Experten, die große Netzwerke oder mehrere Kundenumgebungen verwalten müssen. Durch die Automatisierung des Such- und Warnprozesses wird Zeit gespart und das Risiko menschlichen Versagens verringert.

Das Skript zur Überprüfung der Existenz von Dateien oder Ordnern unter Windows

#Requires -Version 5.1

<#
.SYNOPSIS
    Alert if a specified file or folder is found in a directory or subdirectory you specify.
.DESCRIPTION
    Alert if a specified file or folder is found in a directory or subdirectory you specify.

.EXAMPLE
    -SearchPath "C:" -FileOrFolder "autounattend"

    WARNING: Backslash missing from the search path. Changing it to C:\.
    [Alert] File Found.
    C:\Users\Administrator\Desktop\ExampleFolder\Test Folder 1\autounattend.xml
    C:\Users\Administrator\Desktop\ExampleFolder\Test Folder 2\autounattend.xml
    C:\Users\Administrator\Desktop\ExampleFolder\TestFolder1\Test Folder 1\autounattend.xml
    C:\Users\Administrator\Desktop\ExampleFolder\TestFolder1\Test Folder 2\autounattend.xml
    C:\Users\Administrator\Desktop\ExampleFolder\TestFolder2\Test Folder 1\TestFolder1\autounattend.xml
    Attempting to set Custom Field 'multiline'.
    Successfully set Custom Field 'multiline'!

PARAMETER: -SeachPath "C:\ReplaceMeWithAvalidPath"
    Enter the starting directories for the search, separated by commas. This will include all subdirectories as well.

PARAMETER: -FileOrFolder "ReplaceMeWithNameToSearchFor"
    Specify the full or partial name of a file or folder to find. E.g., 'config' or '.exe'.

PARAMETER: -SearchType "Files and Folders"
    Limit the search to either files, folders, or both.

PARAMETER: -Timeout "30"
    Maximum search time in minutes, halts search if exceeded.

PARAMETER: -CustomField "ReplaceMeWithNameOfMultilineCustomField"
    Optional multiline field to record search results. Leave blank if unused.

.NOTES
    Minimum OS Architecture Supported: Windows 10, Windows Server 2016
    Release Notes: Initial Release
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).
#>

[CmdletBinding()]
param (
    [Parameter()]
    [String]$SearchPath = "C:\Windows,C:\Program Files",
    [Parameter()]
    [String]$FileOrFolder,
    [Parameter()]
    [String]$SearchType = "Files and Folders",
    [Parameter()]
    [Int]$Timeout = 30,
    [Parameter()]
    [String]$CustomField
)

begin {
    # Set parameters using dynamic script variables.
    if ($env:searchPath -and $env:searchPath -notlike "null") { $SearchPath = $env:searchPath }
    if ($env:fileNameOrFolderNameToSearchFor -and $env:fileNameOrFolderNameToSearchFor -notlike "null") { $FileOrFolder = $env:fileNameOrFolderNameToSearchFor }
    if ($env:searchType -and $env:searchType -notlike "null") { $SearchType = $env:searchType }
    if ($env:timeoutInMinutes -and $env:timeoutInMinutes -notlike "null") { $Timeout = $env:timeoutInMinutes }
    if ($env:customFieldName -and $env:customFieldName -notlike "null") { $CustomField = $env:customFieldName }

    # Error out if no search path was given.
    if (-not $SearchPath) {
        Write-Host "[Error] No search path given!"
        exit 1
    }

    # If given a comma-separated list, split the paths.
    $PathsToSearch = New-Object System.Collections.Generic.List[String]
    if ($SearchPath -match ",") {
        $SearchPath -split "," | ForEach-Object { $PathsToSearch.Add($_.Trim()) }
    }
    else {
        $PathsToSearch.Add($SearchPath)
    }

    # Initialize a generic list for paths to remove or replace.
    $ReplacementPaths = New-Object System.Collections.Generic.List[Object]
    $PathsToRemove = New-Object System.Collections.Generic.List[String]

    # If given a drive without the backslash add it in.
    $PathsToSearch | ForEach-Object {
        if ($_ -notmatch '^[A-Z]:\\$' -and $_ -match '^[A-Z]:$') {
            $NewPath = "$_\"
            $ReplacementPaths.Add(
                [PSCustomObject]@{
                    Index   = $PathsToSearch.IndexOf("$_")
                    NewPath = $NewPath
                }
            )
                
            Write-Warning "Backslash missing from the search path. Changing it to $NewPath."
        }
    }

    # Apply replacements.
    $ReplacementPaths | ForEach-Object {
        $PathsToSearch[$_.index] = $_.NewPath 
    }

    # Check if the search path is valid.
    $PathsToSearch | ForEach-Object {
        if (-not (Test-Path $_)) {
            Write-Host -Object "[Error] $_ does not exist!"
            $PathsToRemove.Add($_)
            $ExitCode = 1
        }
    }

    # Remove Paths that do not exist.
    $PathsToRemove | ForEach-Object {
        $PathsToSearch.Remove($_) | Out-Null
    }

    # Error out if no valid paths to search.
    if ($($PathsToSearch).Count -eq 0) {
        Write-Host "[Error] No valid paths to search!"
        exit 1
    }

    # If we're not given a file or folder error out.
    if (-not $FileOrFolder) {
        Write-Host -Object "[Error] No file or folder given to search for!"
        exit 1
    }

    # Timeout must be within a given range in minutes.
    if ($Timeout -lt 1 -or $Timeout -gt 120) {
        Write-Host -Object "[Error] Timeout is greater than 120 minutes or less than 1 minute."
        exit 1
    }

    # Scope the search to either files only or folders only.
    $ValidSearchTypes = "Files and Folders", "Files Only", "Folders Only"
    if ($ValidSearchTypes -notcontains $SearchType) {
        Write-Host -Object "[Error] Invalid search type."
        exit 1
    }

    # Test for local administrator rights.
    function Test-IsElevated {
        $id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
        $p = New-Object System.Security.Principal.WindowsPrincipal($id)
        $p.IsInRole([System.Security.Principal.WindowsBuiltInRole]::Administrator)
    }

    # Handy function to set a custom field.
    function Set-NinjaProperty {
        [CmdletBinding()]
        Param(
            [Parameter(Mandatory = $True)]
            [String]$Name,
            [Parameter()]
            [String]$Type,
            [Parameter(Mandatory = $True, ValueFromPipeline = $True)]
            $Value,
            [Parameter()]
            [String]$DocumentName
        )
    
        $Characters = $Value | Measure-Object -Character | Select-Object -ExpandProperty Characters
        if ($Characters -ge 10000) {
            throw [System.ArgumentOutOfRangeException]::New("Character limit exceeded, value is greater than 10,000 characters.")
        }
        
        # If we're requested to set the field value for a Ninja document we'll specify it here.
        $DocumentationParams = @{}
        if ($DocumentName) { $DocumentationParams["DocumentName"] = $DocumentName }
        
        # This is a list of valid fields that can be set. If no type is given, it will be assumed that the input doesn't 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 be set
        $NeedsOptions = "Dropdown"
        if ($DocumentName) {
            if ($NeedsOptions -contains $Type) {
                # We'll redirect the error output to the success stream to make it easier to error out if nothing was found or something else went 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 it will have an exception property, the function will exit with that error information.
        if ($NinjaPropertyOptions.Exception) { throw $NinjaPropertyOptions }
        
        # The below type's require values not typically given in order to be set. The below code will convert whatever we're given into a format ninjarmm-cli supports.
        switch ($Type) {
            "Checkbox" {
                # While it's highly likely we were given a value like "True" or a boolean datatype it's better to be safe than sorry.
                $NinjaValue = [System.Convert]::ToBoolean($Value)
            }
            "Date or Date Time" {
                # Ninjarmm-cli expects the  Date-Time to be in Unix Epoch time so we'll convert it here.
                $Date = (Get-Date $Value).ToUniversalTime()
                $TimeSpan = New-TimeSpan (Get-Date "1970-01-01 00:00:00") $Date
                $NinjaValue = $TimeSpan.TotalSeconds
            }
            "Dropdown" {
                # Ninjarmm-cli is expecting the guid of the option we're trying to select. So we'll match up 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")
                }
        
                $NinjaValue = $Selection
            }
            default {
                # All the other types shouldn't require additional work on the input.
                $NinjaValue = $Value
            }
        }
        
        # We'll need to set the field differently depending on if its a field in a Ninja Document or not.
        if ($DocumentName) {
            $CustomField = Ninja-Property-Docs-Set -AttributeName $Name -AttributeValue $NinjaValue @DocumentationParams 2>&1
        }
        else {
            $CustomField = Ninja-Property-Set -Name $Name -Value $NinjaValue 2>&1
        }
        
        if ($CustomField.Exception) {
            throw $CustomField
        }
    }

    $ExitCode = 0
}
process {
    # Error out if local administrator rights are not present.
    if (-not (Test-IsElevated)) {
        Write-Host "[Error] Access Denied. Please run with Administrator privileges."
        exit 1
    }

    # Initialize generic lists.
    $SearchJobs = New-Object System.Collections.Generic.List[object]
    $CustomFieldValue = New-Object System.Collections.Generic.List[string]

    # For each given path to search, create a PowerShell job with the provided parameters.
    $PathsToSearch | ForEach-Object {
        $SearchJobs.Add(
            (
                Start-Job -ScriptBlock {
                    param($SearchPath, $FileOrFolder, $SearchType)
                    # We're going to wildcard search either files or folders depending on the parameters given.
                    switch ($SearchType) {
                        "Files and Folders" {
                            Get-ChildItem -Path $SearchPath -Filter "*$FileOrFolder*" -Recurse | Select-Object -Property FullName, Attributes | ConvertTo-Csv
                        }
                        "Folders Only" {
                            Get-ChildItem -Path $SearchPath -Filter "*$FileOrFolder*" -Recurse -Directory | Select-Object -Property FullName, Attributes | ConvertTo-Csv
                        }
                        "Files Only" { 
                            Get-ChildItem -Path $SearchPath -Filter "*$FileOrFolder*" -Recurse -File | Select-Object FullName, Attributes | ConvertTo-Csv
                        }
                    }
                } -ArgumentList $_, $FileOrFolder, $SearchType
            )
        )
    }

    # Convert timeout to seconds as Wait-Job requires seconds.
    $TimeoutInSeconds = $Timeout * 60
    $StartTime = Get-Date

    # Wait for all jobs to complete or timeout.
    foreach ($SearchJob in $SearchJobs) {
        # Calculate the remaining time.
        $TimeElapsed = (Get-Date) - $StartTime
        $RemainingTime = $TimeoutInSeconds - $TimeElapsed.TotalSeconds
    
        # If there is no remaining time, break the loop.
        if ($RemainingTime -le 0) {
            break
        }
    
        # Wait for the current job with the remaining time as the timeout.
        $SearchJob | Wait-Job -Timeout $RemainingTime | Out-Null
    }

    # Output a warning if the job fails to complete.
    $IncompleteJobs = $SearchJobs | Get-Job | Where-Object { $_.State -eq "Running" }
    if ($IncompleteJobs) {
        Write-Host "[Error] The timeout period of $Timeout minutes has been reached, but not all files or directories have been searched!"
        $CustomFieldValue.Add("[Error] The timeout period of $Timeout minutes has been reached, but not all files or directories have been searched!")
        $ExitCode = 1
    }

    # Our PowerShell Job outputs in CSV format; we'll convert it here.
    $MatchingItems = $SearchJobs | ForEach-Object {
        $_ | Get-Job | Receive-Job -ErrorAction SilentlyContinue -ErrorVariable JobErrors | ConvertFrom-Csv
    }

    # Identify whether or not we have a match for a file or folder here.
    $FileMatch = $MatchingItems | Where-Object { $_.Attributes -ne "Directory" }
    $FolderMatch = $MatchingItems | Where-Object { $_.Attributes -eq "Directory" }

    # If we have a match for a file we'll output that here.
    if ($FileMatch) { 
        Write-Host -Object "[Alert] File Found."
        $CustomFieldValue.Add("[Alert] File Found.")
    }

    # If we have a match for a folder we'll output that here.
    if ($FolderMatch) { 
        Write-Host -Object "[Alert] Folder Found." 
        $CustomFieldValue.Add("[Alert] Folder Found.")
    }

    # If we have no matches we'll output that here.
    if (-not $FileMatch -and -not $FolderMatch) {
        Write-Host -Object "Unable to find $FileOrFolder."
        $CustomFieldValue.Add("Unable to find $FileOrFolder.")
    }

    # For each matching file we'll output their full path.
    $MatchingItems | ForEach-Object { 
        Write-Host "$($_.FullName)"
        $CustomFieldValue.Add("$($_.FullName)") 
    }

    # Output any failures or errors received.
    $FailedJobs = $SearchJobs | Get-Job | Where-Object { $_.State -ne "Completed" -and $_.State -ne "Running" }
    if ($FailedJobs -or $JobErrors) {
        Write-Host ""
        Write-Host "[Error] Failed to search certain files or directories due to an error."

        $CustomFieldValue.Add("")
        $CustomFieldValue.Add("[Error] Failed to search certain files or directories due to an error.")
        if ($JobErrors) {
            Write-Host ""
            $CustomFieldValue.Add("")

            $JobErrors | ForEach-Object { 
                Write-Host "[Error] $($_.Exception.Message)" 
                $CustomFieldValue.Add("[Error] $($_.Exception.Message)")
            }
        }
        $ExitCode = 1
    }

    $SearchJobs | Get-Job | Remove-Job -Force

    # Attempt to set the custom field using the Set-NinjaProperty function, if provided.
    if ($CustomField) {
        try {
            Write-Host "Attempting to set Custom Field '$CustomField'."
            Set-NinjaProperty -Name $CustomField -Value ($CustomFieldValue | Out-String)
            Write-Host "Successfully set Custom Field '$CustomField'!"
        }
        catch {
            if (-not $_.Exception.Message) {
                Write-Host "[Error] $($_.Message)"
            }
            else {
                Write-Host "[Error] $($_.Exception.Message)"
            }
            $ExitCode = 1
        }
    }

    exit $ExitCode
}
end {
    
    
    
}

 

Detailansicht

Das Skript arbeitet in mehreren Stufen, die alle zur Gesamtfunktionalität beitragen. Hier ist eine schrittweise Aufschlüsselung:

1. Initialisierung der Parameter: Das Skript beginnt mit der Definition mehrerer Parameter:

• SearchPath: Die zu durchsuchenden Verzeichnisse.

• FileOrFolder: Der Name der Datei oder des Ordners, nach dem gesucht werden soll.

• SearchType: Ob nach Dateien, Ordnern oder beidem gesucht werden soll.

• Timeout: Die maximale Dauer für die Suche.

• CustomField: Ein optionales Feld zur Erfassung von Suchergebnissen.

2. Überschreibung durch Umgebungsvariablen: Das Skript prüft, ob Umgebungsvariablen gesetzt sind, die die Eingabeparameter überschreiben sollen. Dies ermöglicht eine dynamische Anpassung an unterschiedliche Umgebungen.

3. Validierung: Das Skript führt mehrere Validierungsprüfungen durch:

• Stellt sicher, dass ein Suchpfad angegeben wird.

• Validiert und formatiert den Suchpfad.

• Überprüft die Existenz der angegebenen Pfade.

• Validiert den Datei- oder Ordnernamen.

• Gewährleistet, dass der Timeout-Wert innerhalb eines akzeptablen Bereichs liegt.

• Bestätigt, dass der Suchtyp gültig ist.

4. Prüfung auf Administratorrechte: Das Skript enthält eine Funktion, die überprüft, ob es mit Administratorrechten ausgeführt wird, was für bestimmte Dateioperationen erforderlich ist.

5. Ausführung der Suche: Die Kernfunktionalität umfasst die Erstellung von PowerShell-Jobs für jeden zu durchsuchenden Pfad. Diese jobs führen rekursive Suchen auf der Grundlage der angegebenen Parameter durch und geben die Ergebnisse im CSV-Format zurück.

6. Handhabung der Ergebnisse: Das Skript sammelt und verarbeitet die Suchergebnisse:

• Identifiziert Übereinstimmungen mit Dateien und Ordnern.

• Gibt die vollständigen Pfade aller übereinstimmenden Elemente aus.

• Protokolliert Fehler oder unvollständige Suchen.

7. Einstellung der benutzerdefinierten Felder: Wenn ein benutzerdefiniertes Feld angegeben ist, versucht das Skript, es mit den Suchergebnissen auszufüllen, wobei eine Hilfsfunktion verwendet wird, um mit verschiedenen Feldtypen umzugehen.

8. Fehlerbehandlung und Bereinigung: Das Skript sorgt dafür, dass alle Fehler protokolliert und alle Jobs ordnungsgemäß bereinigt werden, bevor es mit einem entsprechenden Exit-Code beendet wird.

Potenzielle Anwendungsfälle

Stellen Sie sich ein Szenario vor, in dem ein IT-Experte ein Netzwerk von Workstations für einen Firmenkunden verwaltet. Er muss im Rahmen einer Sicherheitsüberprüfung gewährleisten, dass sich in den Benutzerverzeichnissen keine nicht autorisierten ausführbaren Dateien befinden. Durch den Einsatz dieses Skripts kann die Suche auf allen Workstations automatisiert werden, sodass alle nicht autorisierten Dateien schnell identifiziert und bei Bedarf Maßnahmen ergriffen werden können. Diese Automatisierung erhöht nicht nur die Sicherheit, sondern verschafft dem IT-Team auch wertvolle Zeit, um sich auf strategischere Aufgaben zu konzentrieren.

Vergleiche

Dieses Skript bietet einen umfassenden und automatisierten Ansatz für die Datei- und Ordnersuche im Vergleich zu manuellen Methoden oder einfachen Batch-Skripten. Herkömmliche Methoden bestehen häufig in dem manuellen Navigieren in Verzeichnissen oder in der Verwendung einfacher Skripte, denen fortgeschrittene Funktionen wie die Behandlung von Zeitüberschreitungen, die Erfassung in benutzerdefinierten Feldern und die Ausführung von Multi-Threaded-Jobs fehlen. Die Fähigkeit des PowerShell-Skripts, komplexe Umgebungen zu handhaben und detaillierte Ausgaben zu liefern, macht es zu einer hervorragenden Wahl für IT-Experten.

FAQs

1) Wie kann ich mehrere Verzeichnisse für die Suche angeben?

Verwenden Sie eine durch Komma getrennte Liste für den Parameter ‘SearchPath’, z. B. ‘C:\Path1,C:\Path2’.

2) Kann ich die Suche nur auf Dateien oder nur auf Ordner beschränken?

Ja, verwenden Sie den Parameter ‘SearchType’ mit den Werten ‘Files Only’ oder ‘Folders Only’.

3) Was passiert, wenn die Suche das angegebene Timeout überschreitet?

Das Skript bricht alle unvollständigen Suchvorgänge ab und gibt eine Fehlermeldung aus.

4) Benötige ich Administratorrechte, um dieses Skript auszuführen?

Ja, das Skript prüft, ob Sie über Administratorrechte verfügen, und wird beendet, wenn es nicht mit ausreichenden Rechten ausgeführt wird.

Folgen

Die Ergebnisse dieses Skripts haben erhebliche Auswirkungen auf die IT-Sicherheit. Durch die Identifizierung nicht autorisierter oder verlegter Dateien und Ordner können IT-Experten sofort Maßnahmen ergreifen, um potenzielle Sicherheitsrisiken zu minimieren. Die regelmäßige Ausführung dieses Skripts als Teil einer Wartungsroutine kann dazu beitragen, die Einhaltung von Unternehmensrichtlinien und gesetzlichen Vorschriften zu gewährleisten und damit die allgemeine Sicherheitslage zu verbessern.

Empfehlungen

Beachten Sie bei der Verwendung dieses Skripts die folgenden Best Practices:

• Aktualisieren Sie das Skript regelmäßig, um es an Änderungen in Ihrer Umgebung anzupassen.

• Integrieren Sie das Skript in automatisierte Wartungsroutinen.

• Überprüfen Sie die Suchergebnisse und handeln Sie umgehend, um die Sicherheit zu garantieren.

• Passen Sie die Skriptparameter an spezifische Anforderungen und Umgebungen an.

Abschließende Überlegungen

Dieses PowerShell-Skript ist ein leistungsstarkes Tool für IT-Experten, das automatisierte und effiziente Datei- und Ordnersuchfunktionen bietet. Durch den Einsatz dieses Skripts können IT-Teams ihre betriebliche Effizienz steigern, die Sicherheit aufrechterhalten und für die Einhaltung von Unternehmensrichtlinien sorgen. Die Integration des Skripts in NinjaOne kann die Verwaltungsaufgaben weiter rationalisieren und eine zentrale Steuerung und Überwachung über mehrere Endpunkte hinweg ermöglichen.