Skip to content

usage.md

Latest commit

 

History

History
272 lines (202 loc) · 6.67 KB

usage.md

File metadata and controls

272 lines (202 loc) · 6.67 KB
Raw

Usage Guide

This guide gives the common operating patterns for all scripts. For the deepest per-script details, use the dedicated manuals:

Setup for All Scripts

Run from a domain-joined administrative workstation or management server.

Required baseline:

  • RSAT Active Directory module installed
  • A credential with the delegated rights required by the task
  • Local output paths unless a trusted UNC output path is explicitly allowed
  • PowerShell execution policy and script signing controls aligned with your environment

PowerShell version requirements:

  • Scan-ADComputers.ps1: PowerShell 7+
  • Get-ADAdminActivity.ps1: Windows PowerShell 5.1+
  • Manage-ADUserAccounts.ps1: Windows PowerShell 5.1+

Baseline checks:

Get-Module -ListAvailable ActiveDirectory
Get-ADDomain

Reusing Credentials Securely

All three AD tools accept one credential source at a time:

  • -Credential for an explicit PSCredential object.
  • -CredentialSecretName for a Microsoft.PowerShell.SecretManagement secret containing a PSCredential.
  • -CredentialPath for a Windows DPAPI-protected credential exported with Export-Clixml.

SecretManagement is preferred for interactive administrator workstations:

Install-Module Microsoft.PowerShell.SecretManagement, Microsoft.PowerShell.SecretStore -Scope CurrentUser
Register-SecretVault -Name AdminToolsVault -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
Set-Secret -Name ExampleADCredential -Secret (Get-Credential)

.\Scan-ADComputers.ps1 -ComputerType Server -Mode Full -CredentialSecretName ExampleADCredential

A local CLIXML credential file is useful for single-user, single-machine runs:

$credentialPath = Join-Path $env:USERPROFILE ".admintools\ad-reporting.credential.xml"
New-Item -ItemType Directory -Force -Path (Split-Path $credentialPath) | Out-Null
Get-Credential | Export-Clixml -LiteralPath $credentialPath

.\Get-ADAdminActivity.ps1 -DaysBack 7 -CredentialPath $credentialPath

Credential files must be outside the repository directory. UNC credential paths are blocked unless -AllowNetworkInputPath is supplied. On Windows, Export-Clixml protects PSCredential secrets with DPAPI for the same user on the same computer; do not treat those files as portable credentials.

Quick Start for All Scripts

Computer inventory:

.\Scan-ADComputers.ps1 -ComputerType Server -Mode Full

Admin activity audit:

.\Get-ADAdminActivity.ps1 -DaysBack 7

User account password age report:

.\Manage-ADUserAccounts.ps1 `
  -Mode Report `
  -ReportType PasswordAge `
  -ExportFormat Csv,Html

Locked-out account details:

.\Manage-ADUserAccounts.ps1 `
  -Mode LockedOut `
  -IncludeEvents `
  -DaysBack 7 `
  -ExportFormat Csv,Html

Preview a reset action:

.\Manage-ADUserAccounts.ps1 `
  -Mode Reset `
  -Identity jsmith `
  -Unlock `
  -WhatIf

Scan-ADComputers.ps1 Usage

Run a full scan:

.\Scan-ADComputers.ps1 -ComputerType Workstation -Mode Full

Run a targeted scan:

.\Scan-ADComputers.ps1 `
  -ComputerType Server `
  -Mode Targeted `
  -ComputerListPath ".\serverlist.txt"

Use OU scope controls:

.\Scan-ADComputers.ps1 `
  -ComputerType Server `
  -Mode Full `
  -SearchBase "OU=Servers,DC=domain,DC=local" `
  -ExcludeOU "OU=Decommissioned,OU=Servers,DC=domain,DC=local"

Add operational validation:

.\Scan-ADComputers.ps1 `
  -ComputerType Server `
  -Mode Targeted `
  -ComputerListPath ".\serverlist.txt" `
  -TestMethod WinRM `
  -ResolveDns `
  -TestPorts 445,5985,5986 `
  -SeparateStatusExports

Use a JSON config file. Start from the committed sample, then keep your local runtime file ignored by git:

Copy-Item config/server_config.sample.json config/server_config.json
.\Scan-ADComputers.ps1 -ConfigPath ".\config\server_config.json"

Scan-ADComputers.ps1 is the only current script with native -ConfigPath support.

Get-ADAdminActivity.ps1 Usage

Run a default audit:

.\Get-ADAdminActivity.ps1 -DaysBack 7

Limit results to privileged admins:

.\Get-ADAdminActivity.ps1 `
  -DaysBack 30 `
  -AdminOnly

Query specific Domain Controllers and allow partial results:

.\Get-ADAdminActivity.ps1 `
  -DaysBack 14 `
  -DomainControllers "dc01.domain.local","dc02.domain.local" `
  -AllowPartialResults

Write to a specific CSV:

.\Get-ADAdminActivity.ps1 `
  -DaysBack 7 `
  -OutputCsv ".\reports\ad-admin-activity\AD_Admin_Activity_Custom.csv"

This script does not currently support JSON config files.

Manage-ADUserAccounts.ps1 Usage

Generate multiple user reports:

.\Manage-ADUserAccounts.ps1 `
  -Mode Report `
  -ReportType UserSummary,PasswordAge,PrivilegedUsers `
  -SearchBase "OU=Users,DC=domain,DC=local" `
  -ExportFormat Csv,Html

Audit one user:

.\Manage-ADUserAccounts.ps1 `
  -Mode UserAudit `
  -Identity jsmith `
  -IncludeEvents `
  -DaysBack 30 `
  -ExportFormat Csv,Json

Report lockouts with event details:

.\Manage-ADUserAccounts.ps1 `
  -Mode LockedOut `
  -IncludeEvents `
  -DaysBack 7 `
  -AllowPartialResults `
  -ExportFormat Csv,Html

Reset a password using a generated temporary password:

.\Manage-ADUserAccounts.ps1 `
  -Mode Reset `
  -Identity jsmith `
  -ResetPassword `
  -GenerateTemporaryPassword `
  -ShowGeneratedPassword `
  -ChangePasswordAtLogon

This script does not currently support JSON config files.

WhatIf Support

Scan-ADComputers.ps1 supports -WhatIf for report and log creation behavior:

.\Scan-ADComputers.ps1 `
  -ComputerType Server `
  -Mode Full `
  -ExportFormat Csv,Html `
  -WhatIf

Manage-ADUserAccounts.ps1 supports -WhatIf for account-changing reset actions:

.\Manage-ADUserAccounts.ps1 `
  -Mode Reset `
  -Identity jsmith `
  -Unlock `
  -WhatIf

Get-ADAdminActivity.ps1 is read-only against AD and event logs. It does not modify AD objects.

Common Safety Defaults

  • CSV exports are sanitized by default.
  • Existing outputs are not overwritten unless -ForceOverwrite is supplied.
  • Network output paths are rejected unless -AllowNetworkOutputPath is supplied.
  • Network input paths are rejected unless the relevant script supports -AllowNetworkInputPath and it is supplied.
  • Domain Controller names are validated before event-log queries.
  • Generated temporary passwords are displayed only when -ShowGeneratedPassword is explicitly supplied.