Usage Guide

Usage Guide

Comprehensive guide to using the Windows Security Audit Script for security assessment, compliance validation, and remediation across the 16 supported frameworks.

Version: 6.1.2 Last Updated: 2026-04-25

Table of Contents

1. Quick Reference
2. Command-Line Parameters
3. Module Selection
4. Output Configuration
5. Performance and Caching
6. Logging
7. Help System
8. Remediation Features
9. Baseline Drift Comparison
10. Group Policy Export
11. v6.1 Cross-Cutting Capabilities
12. Common Use Cases
13. Standalone Module Execution
14. Automation and Scheduling
15. Best Practices

---

Quick Reference

# Default: run all 16 modules, generate HTML + JSON
.\Windows-Security-Audit.ps1

# Targeted modules with parallel execution
.\Windows-Security-Audit.ps1 -Modules CIS,STIG,NIST -Parallel -Workers 8

# Multi-format output to specific location
.\Windows-Security-Audit.ps1 -OutputFormat All -OutputPath .\audits\Q2-2026

# Audit with all v6.1 enrichments
.\Windows-Security-Audit.ps1 -ShowRiskPriority -ShowCorrelations -ShowCompensatingControls

# Apply remediation bundle
.\Windows-Security-Audit.ps1 -RemediationBundle EssentialEightLevel1 -AutoRemediate -RollbackPath .\rollback.ps1

# Show comprehensive help
.\Windows-Security-Audit.ps1 -Help

---

Command-Line Parameters

Full Parameter Reference

The orchestrator accepts 25 named parameters plus support for free-form help invocation forms.

Core Parameters

Parameter	Type	Default	Description
-Modules	String[]	All	Modules to execute. Valid: acsc, cis, cisa, cmmc, core, enisa, gdpr, hipaa, iso27001, ms, ms-defenderatp, nist, nsa, pcidss, soc2, stig, All. Case-insensitive.
-OutputPath	String	.\reports\audit-yyyyMMdd-HHmmss	Path/base name for output files (extension auto-appended).
-OutputFormat	String	HTML	One of: HTML, JSON, CSV, XML, Console, All.
-ListModules	Switch	False	Print list of available modules and exit.

Help Parameters

Parameter	Type	Description
-Help	Switch	Display comprehensive 10-section help screen.
-H	Switch	Alias for -Help.
-?	Switch	Alias for -Help.
-ShowHelp	Switch	Alias for -Help.

Plus help can be invoked as help, -help, --help, --h, /?, /help, /h via [Parameter(ValueFromRemainingArguments=$true)].

Performance Parameters

Parameter	Type	Default	Description
-Parallel	Switch	False	Execute modules concurrently via RunspacePool.
-Workers	Int	4	Number of parallel workers (1-16). Auto-clamped to module count.
-NoCache	Switch	False	Disable shared data cache (debugging only; ~3-5× slower).
-ShowProfile	Switch	False	Print per-module execution timing summary.

Logging Parameters

Parameter	Type	Default	Description
-LogFile	String	auto-generated	Path to log file. Auto-creates .\logs\audit-yyyyMMdd-HHmmss.log if omitted.
-LogLevel	String	INFO	One of: DEBUG, INFO, WARNING, ERROR, CRITICAL.
-JsonLog	Switch	False	Emit log entries as JSON (for SIEM ingestion).
-Quiet	Switch	False	Suppress console output (file logging continues).
-Verbose	Switch	False	Standard PowerShell verbose output (also bumps log level).

Remediation Parameters

Parameter	Type	Default	Description
-RemediateIssues	Switch	False	Interactively remediate ALL findings (Fail + Warning + Info).
-RemediateIssues_Fail	Switch	False	Remediate only Fail-status findings.
-RemediateIssues_Warning	Switch	False	Remediate only Warning-status findings.
-RemediateIssues_Info	Switch	False	Remediate only Info-status findings.
-AutoRemediate	Switch	False	Apply remediations without per-item prompting (still requires YES confirmation).
-RemediationFile	String	(none)	JSON file containing specific issues to remediate (typically exported from HTML report).
-RemediationBundle	String	(none)	Predefined bundle: DisableLegacyProtocols, HardenAuthentication, EnableAuditLogging, LockDownRDP, EssentialEightLevel1.
-RollbackPath	String	(none)	Path to write inverse-operation rollback script.
-ExportGPO	String	(none)	Path to write Group Policy .pol file from registry remediations.

v6.1 Enrichment Parameters

Parameter	Type	Default	Description
-Baseline	String	(none)	Path to previous JSON audit for drift comparison.
-ShowRiskPriority	Switch	False	Add 1-100 risk priority score to each finding.
-ShowCorrelations	Switch	False	Group findings testing the same underlying control across modules.
-ShowCompensatingControls	Switch	False	Flag failed checks where a passing related control mitigates risk.

Full Syntax

.\Windows-Security-Audit.ps1
    [-Modules <String[]>]
    [-OutputPath <String>]
    [-OutputFormat <String>]
    [-ListModules]
    [-Help] [-H] [-?] [-ShowHelp]
    [-Parallel] [-Workers <Int>]
    [-NoCache] [-ShowProfile]
    [-LogFile <String>]
    [-LogLevel <String>]
    [-JsonLog] [-Quiet]
    [-RemediateIssues]
    [-RemediateIssues_Fail]
    [-RemediateIssues_Warning]
    [-RemediateIssues_Info]
    [-AutoRemediate]
    [-RemediationFile <String>]
    [-RemediationBundle <String>]
    [-RollbackPath <String>]
    [-ExportGPO <String>]
    [-Baseline <String>]
    [-ShowRiskPriority]
    [-ShowCorrelations]
    [-ShowCompensatingControls]
    [-Verbose]

---

Module Selection

All 16 Available Modules

Module	Framework Focus	Checks
acsc	ACSC Essential Eight + ISM/PSPF	170
cis	CIS Controls v8 + IG2/IG3 + Companion Guides	260
cisa	CISA Best Practices + KEV + ZTMM + CPGs	289
cmmc	CMMC 2.0 L1/L2/L3 + DFARS + 800-172	145
core	Foundational Windows Security Baseline	243
enisa	ENISA + NIS2 + DORA + CRA	248
gdpr	GDPR + ePrivacy + Schrems II	183
hipaa	HIPAA + 405(d) HICP + HITECH + 800-66 R2	237
iso27001	ISO 27001:2022 + 27002/27017/27018/27701	286
ms	Microsoft Security Baseline (Win11 24H2 / Server 2025)	367
ms-defenderatp	Microsoft Defender for Endpoint	155
nist	NIST SP 800-53 R5 + CSF 2.0 + 800-171 + 800-207	520
nsa	NSA Cybersecurity + AD hardening + Top 10	225
pcidss	PCI DSS v4.0/v4.0.1 + PIN Security + 3DS	279
soc2	SOC 2 Trust Service Criteria	162
stig	DISA STIGs + SRG cross-mapping	225
TOTAL	16 frameworks	3,994

Module Selection Examples

Run all modules (default):

.\Windows-Security-Audit.ps1
.\Windows-Security-Audit.ps1 -Modules All

Single module:

.\Windows-Security-Audit.ps1 -Modules core

Multiple modules:

.\Windows-Security-Audit.ps1 -Modules cis,stig,nist

Government / Federal compliance:

.\Windows-Security-Audit.ps1 -Modules stig,nist,cisa,cmmc

Healthcare:

.\Windows-Security-Audit.ps1 -Modules hipaa,nist,iso27001

Financial services / payment processing:

.\Windows-Security-Audit.ps1 -Modules pcidss,nist,iso27001,soc2

Privacy compliance:

.\Windows-Security-Audit.ps1 -Modules gdpr,iso27001,soc2

Australian government / defence:

.\Windows-Security-Audit.ps1 -Modules acsc,iso27001

EU / NIS2 alignment:

.\Windows-Security-Audit.ps1 -Modules enisa,iso27001,gdpr

Microsoft / endpoint protection:

.\Windows-Security-Audit.ps1 -Modules ms,ms-defenderatp,core

List available modules and exit:

.\Windows-Security-Audit.ps1 -ListModules

---

Output Configuration

Native Output Formats

Format	Switch	Use Case
HTML (default)	-OutputFormat HTML	Interactive review with filters, sortable tables, export modal
JSON	-OutputFormat JSON	Programmatic access, automation, SIEM ingestion
CSV	-OutputFormat CSV	Spreadsheet analysis, ticket creation
XML	-OutputFormat XML	XSL-styled workbook (renders in browser); SIEM systems expecting XML
Console	-OutputFormat Console	Terminal-only; no file output
All	-OutputFormat All	Generate HTML + JSON + CSV + XML simultaneously

Output Examples

# Default HTML output (a JSON companion is always generated alongside HTML)
.\Windows-Security-Audit.ps1

# JSON only with custom path
.\Windows-Security-Audit.ps1 -OutputFormat JSON -OutputPath .\audits\Q2-baseline.json

# All four file formats with shared base name
.\Windows-Security-Audit.ps1 -OutputFormat All -OutputPath .\audits\Q2-2026

# Console-only (good for piping or quick review)
.\Windows-Security-Audit.ps1 -Modules core -OutputFormat Console

Browser-Based Exports (from HTML report)

The HTML report's Export toolbar offers six additional formats:

1. CSV — flat tabular export
2. Excel (.xls) — opens directly in Microsoft Excel
3. JSON — same shape as native JSON
4. XML Workbook — XSL-styled XML
5. SIEM XML — SIEM-compatible structured XML
6. Plain Text (.txt) — human-readable text dump

Selective export by checking individual rows or filtering by module/category before clicking Export.

---

Performance and Caching

Default: Sequential Execution with Cache

.\Windows-Security-Audit.ps1

Modules run one at a time; the shared data cache pre-populates registry, services, audit policy, and password policy queries during warmup, eliminating redundant queries (~3.3× speedup over uncached execution).

Parallel Execution

# Default 4 workers
.\Windows-Security-Audit.ps1 -Parallel

# Specify worker count (1-16)
.\Windows-Security-Audit.ps1 -Parallel -Workers 8

# Combined with profiling
.\Windows-Security-Audit.ps1 -Parallel -Workers 8 -ShowProfile

The orchestrator uses RunspacePool concurrency. Worker count is automatically clamped to min($Workers, $modulesToRun.Count, 16).

Performance Profiling

.\Windows-Security-Audit.ps1 -ShowProfile

Sample output:

=== Module Performance Profile ===
  acsc            5.32s (170 checks)
  cis             6.46s (260 checks)
  cisa            8.71s (289 checks)
  ...
  Total wall time: 77.94s

Cache Control

# Disable cache (debugging only)
.\Windows-Security-Audit.ps1 -NoCache

---

Logging

Default Behavior (v6.1.2+)

Without specifying -LogFile, the script automatically generates a timestamped log file:

.\logs\audit-yyyyMMdd-HHmmss.log

Console output is mirrored to this file with color-coded format.

Log Levels

Level	Use
DEBUG	Deep diagnostic trace (invocation, module timings, parameter values)
INFO (default)	Standard progress messages
WARNING	Non-fatal issues
ERROR	Module failures or critical errors
CRITICAL	Audit-aborting failures

Logging Examples

# Default INFO level
.\Windows-Security-Audit.ps1

# Deep debugging
.\Windows-Security-Audit.ps1 -LogLevel Debug -Verbose

# Custom log file path
.\Windows-Security-Audit.ps1 -LogFile .\diagnostic-2026-04-25.log

# JSON-formatted log for SIEM
.\Windows-Security-Audit.ps1 -JsonLog -LogFile .\siem-audit.json

# Suppress console output (file logging only)
.\Windows-Security-Audit.ps1 -Quiet

---

Help System

Comprehensive Help

# Multiple equivalent invocations
.\Windows-Security-Audit.ps1 -Help
.\Windows-Security-Audit.ps1 -H
.\Windows-Security-Audit.ps1 -?
.\Windows-Security-Audit.ps1 -ShowHelp
.\Windows-Security-Audit.ps1 help
.\Windows-Security-Audit.ps1 -help
.\Windows-Security-Audit.ps1 --help
.\Windows-Security-Audit.ps1 --h
.\Windows-Security-Audit.ps1 /?
.\Windows-Security-Audit.ps1 /help
.\Windows-Security-Audit.ps1 /h

The help screen has 10 sections: Banner, Synopsis, Description, Frameworks, Parameters by Group, Examples, Bundles, Quick Reference, Requirements, More Information.

Get-Help Integration

# Standard PowerShell comment-based help
Get-Help .\Windows-Security-Audit.ps1
Get-Help .\Windows-Security-Audit.ps1 -Detailed
Get-Help .\Windows-Security-Audit.ps1 -Examples
Get-Help .\Windows-Security-Audit.ps1 -Full

---

Remediation Features

Audit-Only Mode (Default)

Without any remediation switches, the script performs only read-only checks. Safe to run on production:

.\Windows-Security-Audit.ps1
# No system changes

Interactive Remediation

# Interactive prompt for every Fail/Warning/Info finding
.\Windows-Security-Audit.ps1 -RemediateIssues

# Filter by status
.\Windows-Security-Audit.ps1 -RemediateIssues_Fail
.\Windows-Security-Audit.ps1 -RemediateIssues_Warning
.\Windows-Security-Audit.ps1 -RemediateIssues_Info

# Combine
.\Windows-Security-Audit.ps1 -RemediateIssues_Fail -RemediateIssues_Warning

For each finding, you'll see:

[Issue 1 of 31]
  Module:     CIS
  Category:   CIS - Account Policy
  Severity:   High
  Status:     Fail
  Message:    Maximum password age exceeds policy (current: 0 days)
  Remediation: net accounts /maxpwage:90

  Apply this remediation? (Y/N/A=All/S=Skip Remaining/Q=Quit):

Automated Remediation

# Apply all qualifying remediations after summary confirmation
.\Windows-Security-Audit.ps1 -RemediateIssues_Fail -AutoRemediate

Pre-confirmation summary:

=== Remediation Plan ===
  Total remediations:      31
  Critical:                4
  High:                    18
  Medium:                  9
  Reboot required:         3
  Logoff required:         2
  Service restart:         5
  Network impact:          1
  Destructive:             0

Type YES to proceed, or anything else to cancel:

Remediation Bundles (v6.1.0+)

Bundle	Coverage
DisableLegacyProtocols	SMBv1, TLS 1.0/1.1, SSLv2/3, LLMNR, NetBIOS, LM hash, NTLMv1, RC4, 3DES
HardenAuthentication	UAC, LSA Protection, Credential Guard, NTLM levels, Anonymous, Cached Logons, Password Policy, WDigest
EnableAuditLogging	Process Creation, ScriptBlockLogging, ModuleLogging, Transcription, Audit Policy, Event Log Size
LockDownRDP	RDP enable, NLA, MinEncryption, SecurityLayer, IdleTimeout, MaxIdleTime
EssentialEightLevel1	ACSC E1-E8: AppControl, Patch Apps, Macros, App Hardening, Admin Privs, Patch OS, MFA, Backups

# Legacy protocol hardening
.\Windows-Security-Audit.ps1 -RemediationBundle DisableLegacyProtocols -AutoRemediate

# Essential Eight L1 with rollback
.\Windows-Security-Audit.ps1 -RemediationBundle EssentialEightLevel1 -AutoRemediate -RollbackPath .\e8-rollback.ps1

Targeted Remediation from HTML Report

# Step 1: Run audit, open HTML report, check boxes for issues to fix
.\Windows-Security-Audit.ps1

# Step 2: In HTML report, click "Export Selected (JSON)" → save as .\selected.json

# Step 3: Apply only the selected items
.\Windows-Security-Audit.ps1 -RemediationFile .\selected.json -AutoRemediate

Rollback Script Generation

# Apply remediations and capture rollback
.\Windows-Security-Audit.ps1 -RemediateIssues_Fail -AutoRemediate -RollbackPath .\rollback.ps1

# Later: reverse the changes
.\rollback.ps1

The generated rollback script contains:

• Original registry values (read before modification)
• Original service states (Running/Stopped, StartupType)
• Inverse auditpol commands
• Comments documenting what each line reverses

---

Baseline Drift Comparison

Step 1: Capture Baseline

.\Windows-Security-Audit.ps1 -OutputFormat JSON -OutputPath .\baselines\golden-2026-04-25.json

Step 2: Compare Against Baseline

.\Windows-Security-Audit.ps1 -Baseline .\baselines\golden-2026-04-25.json

The HTML report's Drift Analysis panel shows:

=== Baseline Drift ===
  New failures (regressions):       7
  Resolved findings (improvements): 12
  Stable findings:                  3,892
  Newly introduced:                 83
  Removed:                          0

Use Cases

• Quarterly audits — capture Q1 baseline, compare Q2/Q3/Q4
• Pre/post change validation — capture before patch deployment, compare after
• Compliance evidence — show regulators "we maintained X% compliance from Date A to Date B"

---

Group Policy Export

# Generate GPO from failing checks
.\Windows-Security-Audit.ps1 -RemediateIssues_Fail -ExportGPO .\Hardening-Q2-2026.pol

Import the .pol file into a Group Policy Object:

1. Open Group Policy Management Console (gpmc.msc)
2. Edit the target GPO
3. Navigate to Computer Configuration → Preferences → Windows Settings → Registry
4. Right-click → Import → select the generated .pol file

Note: only registry-modifying remediations are exported.

---

v6.1 Cross-Cutting Capabilities

Risk Priority Scoring

.\Windows-Security-Audit.ps1 -ShowRiskPriority

Adds 1-100 score to each finding:

• 80-100 — Critical priority (Critical/High severity + high exploitability + internet-facing)
• 60-79 — High priority
• 40-59 — Medium priority
• 20-39 — Low priority
• 1-19 — Informational

Cross-Framework Correlations

.\Windows-Security-Audit.ps1 -ShowCorrelations

Groups findings testing the same underlying control:

[Correlation: SMBv1 Disabled]
  Tested by 7 modules — all PASS
  Modules: core, stig, ms, nsa, cisa, hipaa, enisa

[Correlation: BitLocker Active on System Drive]
  Tested by 10 modules — 8 PASS, 2 FAIL
  PASS: core, stig, ms, nist, hipaa, gdpr, iso27001, pcidss
  FAIL: cmmc, acsc

Compensating Controls

.\Windows-Security-Audit.ps1 -ShowCompensatingControls

Flags Fail findings where related controls compensate:

[Compensating Control Detected]
  Failed check:    LSA Protection (RunAsPPL) — Fail
  Compensated by:  Credential Guard active (passes)
  Mitigation:     Credential Guard provides VBS-isolated credential storage

Combined Enrichment

.\Windows-Security-Audit.ps1 -ShowRiskPriority -ShowCorrelations -ShowCompensatingControls

---

Common Use Cases

Quick Security Posture Check

.\Windows-Security-Audit.ps1 -Modules core -OutputFormat HTML

Comprehensive Compliance Audit

.\Windows-Security-Audit.ps1 -Parallel -Workers 8 -OutputFormat All -ShowRiskPriority -ShowCorrelations

CI/CD Pipeline Audit (Compliance Gate)

.\Windows-Security-Audit.ps1 -OutputFormat JSON -OutputPath .\ci-audit.json -Quiet
$results = Get-Content .\ci-audit.json | ConvertFrom-Json
if ($results.ExecutionInfo.ComplianceScore -lt 85) {
    Write-Error "Compliance below threshold"
    exit 1
}

Pre-Patch Validation

# Before patch
.\Windows-Security-Audit.ps1 -OutputFormat JSON -OutputPath .\baselines\pre-patch.json

# Apply patch...

# After patch
.\Windows-Security-Audit.ps1 -Baseline .\baselines\pre-patch.json

Defense Industrial Base (DIB) Compliance

.\Windows-Security-Audit.ps1 -Modules cmmc,nist,stig,cisa -OutputFormat All

European Privacy / NIS2 Compliance

.\Windows-Security-Audit.ps1 -Modules gdpr,enisa,iso27001 -OutputFormat HTML

---

Standalone Module Execution

Any module can run directly without the orchestrator:

# Run CIS module standalone
.\modules\module-cis.ps1

# Filter results inline
.\modules\module-stig.ps1 | Where-Object { $_.Status -eq 'Fail' -and $_.Severity -in 'Critical','High' }

# Group by category
.\modules\module-nist.ps1 | Group-Object Category | Format-Table Name,Count

# Export single-module results
.\modules\module-acsc.ps1 | Export-Csv .\acsc-quick.csv -NoTypeInformation

Useful for:

• Quick targeted testing during module development
• CI/CD pipelines testing specific compliance requirements
• Embedding individual checks in larger automation

---

Automation and Scheduling

Task Scheduler (Daily Audit)

$action = New-ScheduledTaskAction `
    -Execute 'powershell.exe' `
    -Argument '-NoProfile -ExecutionPolicy Bypass -File "C:\WinSecAudit\Windows-Security-Audit.ps1" -OutputFormat All -OutputPath "C:\WinSecAudit\reports\daily" -Quiet'

$trigger = New-ScheduledTaskTrigger -Daily -At 3am

Register-ScheduledTask `
    -TaskName "Windows Security Audit Daily" `
    -Action $action `
    -Trigger $trigger `
    -RunLevel Highest `
    -User "SYSTEM"

Multi-Environment Comparison

# On each system
.\Windows-Security-Audit.ps1 -OutputFormat JSON -OutputPath ".\$env:COMPUTERNAME-baseline.json"

# Centrally aggregate
$results = @{}
Get-ChildItem .\baselines\*.json | ForEach-Object {
    $results[$_.BaseName] = Get-Content $_.FullName | ConvertFrom-Json
}

SIEM Integration (Splunk Example)

.\Windows-Security-Audit.ps1 -JsonLog -LogFile C:\Splunk\inputs\winsec-audit.json

Splunk forwarder config (inputs.conf):

[monitor://C:\Splunk\inputs\winsec-audit.json]
disabled = false
sourcetype = winsec_audit_json
index = security

---

Best Practices

For Initial Audits

1. Start with core module for baseline assessment
2. Run as Administrator for full results
3. Review HTML report carefully before remediation
4. Capture a baseline JSON for future comparison

For Production Systems

1. Always test in non-production first
2. Use -Parallel -Workers 8 for faster execution on multi-core systems
3. Schedule regular audits (daily/weekly)
4. Preserve baselines for trend analysis
5. Use -RollbackPath whenever applying remediations
6. Monitor for compliance drift via -Baseline comparisons

For Compliance Evidence

1. Generate both HTML (human review) and JSON (automation) outputs
2. Archive reports with timestamps in version control
3. Use cross-framework correlations to demonstrate single-system multi-standard compliance
4. Capture system info (hostname, OS version, patch level) alongside reports

For Remediation

1. Always start with interactive mode (-RemediateIssues_Fail) to understand changes
2. Use -RollbackPath for every auto-remediation run
3. Test rollback scripts before relying on them
4. Apply bundles only after reviewing their full impact
5. Document remediations in change management systems

For Performance

1. Enable parallel execution: -Parallel -Workers 8
2. Keep cache enabled (default; never use -NoCache in production)
3. For repeated audits, the cache warming dominates total time — use -ShowProfile to identify slow modules
4. Use -Modules to scope audits when full coverage isn't needed

---

See also:

• USAGE_GUIDE.md (top-level) — extended usage walkthrough
• Quick Start Guide — 5-minute setup
• Module Documentation — per-module details
• Output Reference — full output schema
• Architecture and Design — internal architecture
• Troubleshooting Guide — problem resolution