PowerShell-scripts/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a collection of standalone PowerShell scripts for Windows Server administration, focused on Active Directory, Exchange Server (on-premises), and system maintenance tasks. Each script is self-contained and can be executed independently.

Project Structure

The repository is organized into three main directories:

• ActiveDirectory/ - Scripts for Active Directory management (group membership operations)
• Exchange/ - Scripts for Exchange Server administration (mailbox reporting, inventory, traffic analysis)
• Misc/ - System maintenance scripts (VSS backup recovery)

Script Architecture

Exchange Scripts

Exchange-Inventory.ps1 - The most complex script in this repository. Key architecture:

• Report Generation Engine: Dual-mode output system (Word COM automation with HTML fallback)

  • Word automation via COM (Word.Application) for professional reports
  • HTML fallback with StringBuilder when Word is unavailable
  • Abstraction layer: Add-Heading(), Add-Paragraph(), Add-Table() functions work for both modes

• Progress Tracking System: Multi-level progress reporting

  • Section-based progress ($sections array with 22 named sections)
  • Throttled progress updates ($ProgressThrottleMs parameter controls update frequency)
  • Prevents UI flooding during intensive loops (mailbox statistics, database copies)

• Data Collection Pipeline: Sequential inventory collection

  1. Organization config & servers
  2. Client access & virtual directories (OWA, ECP, EWS, MAPI, etc.)
  3. POP/IMAP settings
  4. Certificates (with expiry status calculation)
  5. Domains, policies, transport rules
  6. Databases, DAG configuration, database copies
  7. Mailbox enumeration (on-prem only, filters out Remote* types)
  8. Mailbox statistics (collected per-database to avoid prompts)
  9. Retention, compliance, mobile device policies
  10. Addressing (address lists, GAL, OAB)
  11. Public folders, throttling, hybrid/federation config
  12. Queue monitoring

• Storage Calculation: Computes actual mailbox space requirements

  • Parses TotalItemSize from mailbox statistics (handles KB/MB/GB/TB units)
  • Aggregates per-database and total storage (excludes whitespace)
  • Uses ToBytes() method when available, regex fallback for string parsing

• CSV Export: Optional detailed exports controlled by $IncludeCSVs parameter

Get-LargeMailboxes.ps1 - Simple filtering script

• Queries mailboxes > 100GB
• Uses pipeline: Get-Mailbox | Get-MailboxStatistics | Where-Object
• Converts bytes to GB with formatting

Get-MailboxesPerType.ps1 - Quick mailbox type inventory

• Single-liner using Group-Object for counting

Get-SMTPTraffic.ps1 - Log parsing utility

• Reads Exchange FrontEnd SMTP receive logs
• CSV parsing with quoted field handling (regex: split(',(?=(?:[^"]*"[^"]*")*[^"]*$)'))
• Filters by IP range (192.168.1.*)

System Maintenance Scripts

Fix-VSSBackup.ps1 - VSS recovery automation

• Event log analysis (Application/System logs for VSS/VolSnap errors)
• VSS writer status parsing via vssadmin list writers
• Service restart orchestration with dependency handling
• Configurable service list (VSS, SwPrv, EventSystem, SQLWriter, IISADMIN, vmicvss, etc.)
• Smart defaults when run without parameters (auto-creates C:\Temp, enables Force mode)
• State verification after service restart

Active Directory Scripts

CopyADgroups.ps1 - Group membership cloning

• Simple member enumeration and addition
• Duplicate checking before adding
• Error handling per-member

Common Patterns

Error Handling

Scripts use -ErrorAction SilentlyContinue extensively to gracefully handle missing cmdlets or unavailable features across different Exchange versions (2013/2016/2019).

Execution Environment

• Exchange scripts: Require Exchange Management Shell with appropriate RBAC permissions
• VSS script: Requires Administrator privileges
• AD scripts: Require Active Directory PowerShell module

Parameter Design

• CmdletBinding with typed parameters
• Configurable defaults (e.g., $TopMailboxCount = 30, $LookbackMinutes = 60)
• Boolean parameters for feature toggles ($IncludeCSVs, $RequireFailedWriter)

Localization

Some scripts contain Dutch language strings (comments, log messages) - Exchange-Inventory.ps1 and Fix-VSSBackup.ps1 use Dutch for output.

Testing Approach

These are operational scripts without formal test frameworks. When modifying:

1. Exchange scripts: Test in non-production Exchange Management Shell first
2. VSS script: Test service restart logic on non-critical systems
3. AD scripts: Use test groups before production deployment

AI-Generated Scripts (UNTESTED)

The following scripts were generated by Claude AI in 2025 and have NOT been tested in production environments. They should be thoroughly reviewed and tested in non-production environments before use:

Exchange Scripts (AI-Generated)

• Get-MailboxPermissions.ps1 - Audits SendAs, SendOnBehalf, and FullAccess permissions
• Get-InactiveMailboxes.ps1 - Identifies stale mailboxes based on LastLogonTime threshold
• Compare-MailboxDatabases.ps1 - Database health comparison with alerting (whitespace, backup age)
• Export-DistributionGroups.ps1 - Complete distribution group inventory with members
• Get-MailflowStats.ps1 - Transport log analysis for message flow patterns and anomalies

Active Directory Scripts (AI-Generated)

• Get-ADUserLastLogon.ps1 - True LastLogon query across all DCs (non-replicated attribute)
• Export-OUStructure.ps1 - OU hierarchy documentation with GPO links
• Compare-ADGroupMemberships.ps1 - Group membership comparison between two users

System Maintenance Scripts (AI-Generated)

• Get-ServerInventory.ps1 - Comprehensive hardware/software inventory with Word/HTML report
• Monitor-DiskSpace.ps1 - Disk space monitoring with alerting and optional email
• Backup-ExchangeCertificates.ps1 - Certificate export to PFX with expiry warnings
• Test-ExchangeHealth.ps1 - Aggregated Exchange health checks (services, replication, MAPI, databases)

AI-Generated Script Patterns

These scripts follow the established patterns from the original scripts:

• Similar report generation (Word COM with HTML fallback where applicable)
• Progress tracking for long-running operations
• CSV export capabilities
• -ErrorAction SilentlyContinue for graceful degradation
• Comprehensive parameter documentation and examples
• Prominent "⚠️ AI-GENERATED SCRIPT - UNTESTED" warnings in output

Testing Requirements: All AI-generated scripts include detailed .NOTES sections with testing guidance. Pay special attention to:

• Permission requirements (RBAC, AD rights, Administrator)
• Performance impact (LastLogon queries across DCs, log parsing)
• Environment-specific assumptions (paths, IP ranges, thresholds)

Important Constraints

• Scripts are environment-specific (hardcoded paths like C:\Program Files\Microsoft\Exchange Server\V15\...)
• Exchange-Inventory.ps1 assumes specific Exchange cmdlet availability
• Get-SMTPTraffic.ps1 filters for specific IP range (192.168.1.*) - modify for different networks
• AI-generated scripts have NOT been validated in production and require thorough testing