Merge pull request #13 from leonardokr/improve/code-quality-and-docs

leonardokr · web-flow · commit 41808180615a · 2026-02-18T20:35:00.000-03:00
Refactor: code quality improvements, documentation fixes, and Pester tests
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -19,10 +19,11 @@ jobs:
         Write-Host "PowerShell Version: $($PSVersionTable.PSVersion)"
         Write-Host "OS: $($PSVersionTable.OS)"
     
-    - name: Install PSScriptAnalyzer
+    - name: Install Modules
       shell: pwsh
       run: |
         Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser
+        Install-Module -Name Pester -Force -Scope CurrentUser -SkipPublisherCheck
     
     - name: Run PSScriptAnalyzer
       shell: pwsh
@@ -96,3 +97,12 @@ jobs:
         } else {
           Write-Host "All scripts have proper documentation!"
         }
+
+    - name: Run Pester Tests
+      shell: pwsh
+      run: |
+        $config = New-PesterConfiguration
+        $config.Run.Path = "Tests"
+        $config.Run.Exit = $true
+        $config.Output.Verbosity = "Detailed"
+        Invoke-Pester -Configuration $config
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -103,7 +103,8 @@ Organize scripts into appropriate categories:
 - **NetworkShares** - SMB shares and DFS management
 - **TaskScheduler** - Scheduled task management
 - **UserProfiles** - Windows user profile operations
-- **SystemMaintenance** - General system maintenance
+- **System** - System-level configuration and maintenance
+- **Registry** - Windows Registry configuration
 - **Monitoring** - System and service monitoring
 - **Security** - Security-related operations
 
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # PowerShell Scripts Collection
 
+[![PowerShell Script Validation](https://github.com/leonardokr/powershell-scripts/actions/workflows/validate.yml/badge.svg)](https://github.com/leonardokr/powershell-scripts/actions/workflows/validate.yml)
+
 A collection of PowerShell scripts for Windows system administration, Active Directory management, and IT automation tasks.
 
 ## 📁 Repository Structure
@@ -20,7 +22,7 @@ Scripts/
 ### Active Directory
 - **Get-DeletedUsers.ps1** - Exports deleted AD users within a specified date range
 - **Get-UserLastLogon.ps1** - Reports user last logon times and group memberships
-- **Send-PasswordExpiryNotification** - Password expiration notification for AD users.
+- **Send-PasswordExpiryNotification.ps1** - Password expiration notification for AD users
 
 ### File System
 - **Get-FolderPermissions.ps1** - Audits folder permissions across multiple servers
diff --git a/SECURITY.md b/SECURITY.md
@@ -15,7 +15,7 @@ This project supports the following PowerShell versions:
 If you discover a security vulnerability in any of these scripts, please follow these steps:
 
 1. **Do not** create a public GitHub issue
-2. Send an email to the repository maintainer with:
+2. Send an email to the repository maintainer via [GitHub profile](https://github.com/leonardokr) with:
    - Description of the vulnerability
    - Steps to reproduce
    - Potential impact
diff --git a/Scripts/ActiveDirectory/Get-DeletedUsers.ps1 b/Scripts/ActiveDirectory/Get-DeletedUsers.ps1
@@ -1,4 +1,6 @@
-﻿<#
+﻿#Requires -Modules ActiveDirectory
+
+<#
 .SYNOPSIS
     Exports deleted Active Directory users within a specified date range.
 
@@ -30,7 +32,8 @@
     Author         : Leonardo Klein Rezende
     Prerequisite   : Active Directory PowerShell module
     Creation Date  : 2025-09-04
-    
+    Version        : 1.0.0
+
     Requires Domain Admin or equivalent permissions to query deleted objects.
 
 .LINK
@@ -95,7 +98,3 @@ catch {
 
 Write-Information "Script execution completed." -InformationAction Continue
 
-
-
-
-
diff --git a/Scripts/ActiveDirectory/Get-UserLastLogon.ps1 b/Scripts/ActiveDirectory/Get-UserLastLogon.ps1
@@ -1,4 +1,6 @@
-﻿<#
+﻿#Requires -Modules ActiveDirectory
+
+<#
 .SYNOPSIS
     Reports Active Directory user last logon times and group memberships.
 
@@ -34,7 +36,8 @@
     Author         : Leonardo Klein Rezende
     Prerequisite   : Active Directory PowerShell module
     Creation Date  : 2025-09-04
-    
+    Version        : 1.0.0
+
     LastLogon attribute may not be accurate in multi-DC environments.
     Consider using lastLogonTimestamp for more accurate results across DCs.
 
@@ -98,6 +101,7 @@ try {
     @{Name = "Enabled"; Expression = { $_.Enabled } },
     @{Name = "GroupMemberships"; Expression = {
             if ($_.MemberOf) {
+                # Extract group common names from DN format (e.g., "CN=GroupName,OU=Groups,DC=..." -> "GroupName")
                 ($_.MemberOf -replace '^CN=|,(OU|CN).+') -join ";"
             }
             else {
@@ -124,7 +128,3 @@ catch {
 
 Write-Information "Script execution completed." -InformationAction Continue
 
-
-
-
-
diff --git a/Scripts/ActiveDirectory/README.md b/Scripts/ActiveDirectory/README.md
@@ -62,14 +62,12 @@ Automated password expiration notification system for Active Directory users.
 **Usage:**
 
 ```powershell
-# Run with default settings
-.\Send-PasswordExpiryNotification.ps1
+# Run with specified SMTP server and search base
+.\Send-PasswordExpiryNotification.ps1 -SmtpServer "mail.company.com" -FromAddress "noreply@company.com" -SearchBase "OU=Users,DC=domain,DC=com"
 
 # Run in test mode with logging enabled
-.\Send-PasswordExpiryNotification.ps1 -testMode -enableLogging
-
-# Specify custom search base
-.\Send-PasswordExpiryNotification.ps1 -searchBase "OU=CompanyUsers,DC=domain,DC=com"
+.\Send-PasswordExpiryNotification.ps1 -SmtpServer "mail.company.com" -FromAddress "noreply@company.com" -SearchBase "OU=Users,DC=domain,DC=com" -TestMode -EnableLogging
+```
 
 ## Prerequisites
 
@@ -85,4 +83,3 @@ Automated password expiration notification system for Active Directory users.
 - Always test in non-production environment first
 - Review and modify configuration variables before production use
 - Ensure SMTP server allows relay from execution host
-```
diff --git a/Scripts/ActiveDirectory/Send-PasswordExpiryNotification.ps1 b/Scripts/ActiveDirectory/Send-PasswordExpiryNotification.ps1
@@ -50,6 +50,7 @@
     Author         : Leonardo Klein Rezende
     Prerequisite   : PowerShell 5.1+, ActiveDirectory Module, SMTP Server Access
     Creation Date  : 2025-09-04
+    Version        : 1.0.0
 
 .LINK
     https://github.com/leonardokr/powershell-scripts
diff --git a/Scripts/FileSystem/Get-FolderPermissions.ps1 b/Scripts/FileSystem/Get-FolderPermissions.ps1
@@ -36,7 +36,8 @@
     Author         : Leonardo Klein Rezende
     Prerequisite   : PowerShell remoting and administrative access to target servers
     Creation Date  : 2025-09-04
-    
+    Version        : 1.0.0
+
     Requires administrative privileges on target servers.
     Large folder structures may take considerable time to process.
 
@@ -69,7 +70,7 @@ Write-Information "Starting folder permissions audit..." -InformationAction Cont
 Write-Information "Target servers: $($ServerList -join ', ')" -InformationAction Continue
 Write-Information "Base path: $BasePath" -InformationAction Continue
 
-$Report = @()
+$Report = [System.Collections.Generic.List[PSObject]]::new()
 $ProcessedServers = 0
 $TotalServers = $ServerList.Count
 
@@ -117,7 +118,7 @@ foreach ($Server in $ServerList) {
                         'Inherited'         = $Access.IsInherited
                         'ScanDate'          = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
                     }
-                    $Report += New-Object -TypeName PSObject -Property $Properties
+                    $Report.Add([PSCustomObject]$Properties)
                 }
             }
             catch {
@@ -153,7 +154,3 @@ else {
 
 Write-Information "Script execution completed." -InformationAction Continue
 
-
-
-
-
diff --git a/Scripts/NetworkShares/New-ShareAndDFS.ps1 b/Scripts/NetworkShares/New-ShareAndDFS.ps1
@@ -15,6 +15,10 @@
 .PARAMETER ServerName
     The server name for DFS targets. Default is current computer name.
 
+.PARAMETER ShareAccess
+    The identity to grant full access on created SMB shares. Default is "Everyone".
+    Modify to restrict access as needed (e.g., "Domain Users", "DOMAIN\ShareGroup").
+
 .PARAMETER LogPath
     Path for the log file. Default is "C:\Logs".
 
@@ -36,7 +40,8 @@
     Author         : Leonardo Klein Rezende
     Prerequisite   : DFSN PowerShell module, Administrative privileges
     Creation Date  : 2025-08-10
-    
+    Version        : 1.0.0
+
     Requires:
     - Administrative privileges
     - DFS Management features installed
@@ -47,8 +52,11 @@
     https://docs.microsoft.com/en-us/powershell/module/smbshare/
 #>
 
+[System.Diagnostics.CodeAnalysis.SuppressMessage('PSReviewUnusedParameter', 'ShareAccess',
+    Justification = 'Used in New-ShareFolder function scope')]
+[System.Diagnostics.CodeAnalysis.SuppressMessage('PSReviewUnusedParameter', 'EnableDebugMode',
+    Justification = 'Used in Write-ScriptLog function scope')]
 [CmdletBinding(SupportsShouldProcess)]
-[System.Diagnostics.CodeAnalysis.SuppressMessage('PSReviewUnusedParameter', 'EnableDebugMode', Justification = 'Used in Write-ScriptLog function scope')]
 param (
     [Parameter(Mandatory = $false)]
     [ValidateScript({ Test-Path $_ -PathType Container })]
@@ -60,6 +68,9 @@ param (
     [Parameter(Mandatory = $false)]
     [string]$ServerName = $env:COMPUTERNAME,
 
+    [Parameter(Mandatory = $false)]
+    [string]$ShareAccess = "Everyone",
+
     [Parameter(Mandatory = $false)]
     [string]$LogPath = "C:\Logs",
 
@@ -119,7 +130,7 @@ function New-SMBShareSafe {
         }
         
         if ($PSCmdlet.ShouldProcess($Name, "Create SMB share")) {
-            New-SmbShare -Name $Name -Path $Path -Description $Description -FullAccess "Everyone"
+            New-SmbShare -Name $Name -Path $Path -Description $Description -FullAccess $ShareAccess
             Write-ScriptLog "SMB share '$Name' created successfully" 'Info'
             return $true
         }
@@ -188,7 +199,7 @@ try {
     
     $successCount = 0
     $failureCount = 0
-    $results = @()
+    $results = [System.Collections.Generic.List[PSObject]]::new()
     
     foreach ($folder in $folders) {
         $folderName = $folder.Name
@@ -220,13 +231,13 @@ try {
             Write-ScriptLog "Failed to process folder '$folderName': $message" 'Error'
         }
         
-        $results += [PSCustomObject]@{
+        $results.Add([PSCustomObject]@{
             FolderName = $folderName
             ShareName  = $shareName
             FolderPath = $folderPath
             Status     = $status
             Message    = $message
-        }
+        })
     }
     
     Write-ScriptLog "Processing completed" 'Info'
diff --git a/Scripts/NetworkShares/README.md b/Scripts/NetworkShares/README.md
@@ -44,5 +44,5 @@ Creates SMB shares and corresponding DFS namespaces for all folders in a specifi
 
 - Script automatically handles existing shares/namespaces
 - DFS namespaces are created as DomainV2 type
-- All shares are created with "Everyone" full access (modify as needed)
+- Shares are created with "Everyone" full access by default; use `-ShareAccess` to restrict (e.g., `-ShareAccess "Domain Users"`)
 - Comprehensive logging available in debug mode
diff --git a/Scripts/Registry/Disable-LanmanCache.ps1 b/Scripts/Registry/Disable-LanmanCache.ps1
@@ -33,7 +33,8 @@
     Author         : Leonardo Klein Rezende
     Prerequisite   : Administrator privileges
     Creation Date  : 2025-09-05
-    
+    Version        : 1.0.0
+
     IMPORTANT: This script requires administrator privileges to modify registry settings.
     Restart may be required for changes to take effect.
 
@@ -115,5 +116,3 @@ catch {
     exit 1
 }
 
-
-
diff --git a/Scripts/System/Enable-FullDump.ps1 b/Scripts/System/Enable-FullDump.ps1
@@ -33,7 +33,8 @@
     Author         : Leonardo Klein Rezende
     Prerequisite   : Administrator privileges
     Creation Date  : 2025-09-05
-    
+    Version        : 1.0.0
+
     IMPORTANT: This script requires administrator privileges to modify registry settings.
     Full dumps can be very large and consume significant disk space.
 
diff --git a/Scripts/System/Invoke-WindowsUpdateMaintenance.ps1 b/Scripts/System/Invoke-WindowsUpdateMaintenance.ps1
@@ -13,7 +13,7 @@
 .PARAMETER Stage
     Execution stage: Check, Reboot, Recheck, or Finalize.
 
-.PARAMETER LogPath  
+.PARAMETER LogPath
     Directory path for log files. Default: C:\Logs\WindowsUpdates
 
 .PARAMETER RebootTimeoutMinutes
@@ -37,7 +37,8 @@
     Author         : Leonardo Klein Rezende
     Prerequisite   : Administrator privileges, PowerShell 5.1+, PSWindowsUpdate module
     Creation Date  : 2025-10-03
-    
+    Version        : 1.0.0
+
     MAINTENANCE WINDOW WORKFLOW:
     1. Initial update installation
     2. Server reboots and SQL Server update approval
@@ -150,8 +151,8 @@ function Get-SQLServerService {
     try {
         $sqlServices = Invoke-Command -ComputerName $ServerName -ScriptBlock {
             Get-Service | Where-Object {
-                $_.Name -like "MSSQL*" -or 
-                $_.Name -like "SQLServer*" -or 
+                $_.Name -like "MSSQL*" -or
+                $_.Name -like "SQLServer*" -or
                 $_.Name -eq "SQLSERVERAGENT" -or
                 $_.Name -like "SQL*Agent*"
             } | Select-Object Name, Status, StartType
diff --git a/Scripts/System/README.md b/Scripts/System/README.md
@@ -31,6 +31,9 @@ Manages Windows Updates across multiple servers during scheduled maintenance win
 .\Invoke-WindowsUpdateMaintenance.ps1 -ServerListPath "servers.csv" -Stage Finalize
 ```
 
+**Sample CSV:**
+A sample server list file (`sample-servers.csv`) is included in this directory for reference.
+
 ### Enable-FullDump.ps1
 Configures Windows Error Reporting to create full memory dumps when applications crash.
 
diff --git a/Scripts/TaskScheduler/Deploy-ScheduledTasks.ps1 b/Scripts/TaskScheduler/Deploy-ScheduledTasks.ps1
diff --git a/Scripts/UserProfiles/Remove-OrphanedProfiles.ps1 b/Scripts/UserProfiles/Remove-OrphanedProfiles.ps1
diff --git a/Tests/ScriptValidation.Tests.ps1 b/Tests/ScriptValidation.Tests.ps1
