Skip to content

Troubleshooting Guide

Jump to bottom
Ryan edited this page Mar 3, 2026 · 5 revisions

Troubleshooting Guide

Common issues and solutions for the Windows Security Audit Script.

Table of Contents

Execution Issues

Error: "Script cannot be loaded because running scripts is disabled"

Full Error:

.\Windows-Security-Audit.ps1 : File C:\Path\Windows-Security-Audit.ps1 cannot be loaded because running scripts is disabled on this system.

Cause: PowerShell execution policy is set to Restricted.

Solution:

# Check current policy
Get-ExecutionPolicy

# Set policy to allow local scripts
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Confirm change by typing: Y

# Verify
Get-ExecutionPolicy

Alternative (Temporary):

# Bypass for single execution
PowerShell.exe -ExecutionPolicy Bypass -File ".\Windows-Security-Audit.ps1"

Error: "Module not found" or "Cannot find path"

Full Error:

Import-Module : The specified module 'module-stig.ps1' was not loaded because no valid module file was found

Cause: Script cannot locate module files.

Solution 1: Verify Directory Structure

# Check that Modules folder exists
Test-Path ".\Modules"

# List module files
Get-ChildItem ".\modules\*.ps1"

# Should show:
# module-core.ps1
# module-stig.ps1
# module-nist.ps1
# etc.

Solution 2: Run from Correct Directory

# Navigate to script directory first
cd C:\Path\To\Windows-Security-Audit-Project

# Then run
.\Windows-Security-Audit.ps1

Solution 3: Use Full Paths

# If running from elsewhere, use full path
C:\SecurityAudit\Windows-Security-Audit.ps1

Script Starts But Immediately Exits

Symptoms:

  • PowerShell window opens and closes quickly
  • No output or reports generated

Solution: Run from PowerShell Console

# Don't double-click the .ps1 file
# Instead, open PowerShell as Administrator:
# 1. Search "PowerShell"
# 2. Right-click "Windows PowerShell"
# 3. Select "Run as administrator"
# 4. Navigate to script directory
cd C:\Path\To\Script
# 5. Run script
.\Windows-Security-Audit.ps1

Check for Syntax Errors:

# Validate script syntax
$null = [System.Management.Automation.PSParser]::Tokenize((Get-Content ".\Windows-Security-Audit.ps1" -Raw), [ref]$null)
# If no errors, script syntax is valid

Permission Errors

Error: "Access is denied" or "Administrative privileges required"

Full Error:

Get-BitLockerVolume : Access is denied
Get-MpComputerStatus : Access denied

Cause: Script requires administrator privileges for many checks.

Solution:

# Check if running as administrator
([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

# If returns False:
# 1. Close PowerShell
# 2. Right-click PowerShell
# 3. Select "Run as administrator"
# 4. Navigate back to script directory
# 5. Run script again

Note: Some checks will return "Error" status if not run as administrator, but script will continue.

Error: "Execution policy change was rejected"

Full Error:

Set-ExecutionPolicy : Access to the registry key 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell' is denied.

Cause: Group Policy or insufficient permissions.

Solution 1: Use CurrentUser Scope

# Try setting for current user only (doesn't require admin)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Solution 2: Use Bypass

# Run script with bypass (no permanent change)
PowerShell.exe -ExecutionPolicy Bypass -File ".\Windows-Security-Audit.ps1"

Solution 3: Check Group Policy

# Check if Group Policy enforces execution policy
Get-ExecutionPolicy -List

# If "LocalMachine" shows "RemoteSigned" or "Restricted" from MachinePolicy/UserPolicy,
# contact your IT department

Module Errors

Individual Module Fails But Script Continues

Symptoms:

[STIG] Module encountered an error: ...
[NIST] Starting NIST compliance checks...

Cause: One module failed, but orchestrator continues with others.

Solution:

  1. Note which module failed
  2. Review error message
  3. Run that module standalone for detailed error:
# Example: Test STIG module independently
Import-Module ".\modules\module-stig.ps1" -Force
# Check for import errors

Common Module-Specific Issues:

BitLocker Checks Fail:

Get-BitLockerVolume : BitLocker Drive Encryption is not supported on this edition
  • Cause: BitLocker not available (Home edition, VMs without TPM)
  • Impact: BitLocker-related checks will fail
  • Solution: Expected behavior on unsupported editions - not a problem

Windows Defender Checks Fail:

Get-MpComputerStatus : Operation failed with the following error: 0x800106ba
  • Cause: Third-party antivirus installed, Defender disabled
  • Impact: Defender checks return Error status
  • Solution: Expected if using alternative AV - review manually

Audit Policy Checks Return Null:

auditpol /get /subcategory:"..." returned no results
  • Cause: Advanced Audit Policy not configured
  • Impact: Some audit checks show as "Not Configured"
  • Solution: Not necessarily a problem - indicates default settings

Error: "Module took too long to execute"

Symptoms:

  • Script hangs on specific module
  • No progress for several minutes

Solution:

# Press Ctrl+C to cancel

# Try running problematic module standalone with verbose output
.\modules\module-stig.ps1 -Verbose

Common Causes:

  1. Windows Update checks - If Windows Update service is not responding
  2. Network checks - If network stack is malfunctioning
  3. Large audit logs - Reading very large event logs

Output Issues

No Reports Generated

Symptoms:

  • Script completes but no files in Reports folder
  • "Reports folder not found" error

Solution 1: Check Output Path

# Verify Reports folder exists
Test-Path ".\Reports"

# If False, create it
New-Item -ItemType Directory -Path ".\Reports" -Force

Solution 2: Check Permissions

# Verify write permissions
$acl = Get-Acl ".\Reports"
$acl.Access | Where-Object { $_.IdentityReference -like "*$env:USERNAME*" }
# Should show FullControl or Modify permissions

Solution 3: Specify Different Output Path

# Try writing to a different location
.\Windows-Security-Audit.ps1 -OutputPath "C:\Temp\SecurityAudit"

HTML Report Won't Open or Displays Incorrectly

Symptoms:

  • Double-clicking HTML file does nothing
  • Report opens but looks broken/unstyled

Solution 1: Specify Browser

# Open with specific browser
Start-Process "chrome.exe" ".\Reports\SecurityAudit_Report_*.html"
# or
Start-Process "msedge.exe" ".\Reports\SecurityAudit_Report_*.html"
# or
Start-Process "firefox.exe" ".\Reports\SecurityAudit_Report_*.html"

Solution 2: Check File Association

# Check .html file association
Get-ItemProperty "HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\FileExts\.html\UserChoice"

# Reset to default browser if needed

Solution 3: Security Warning

  • If browser shows security warning about "local file"
  • This is normal for HTML files opened from disk
  • Click "Allow" or "Trust" if prompted

CSV Opens in Notepad Instead of Excel

Solution:

# Open with Excel explicitly
Start-Process "excel.exe" ".\Reports\SecurityAudit_Report_*.csv"

# Or right-click file → Open With → Excel

JSON Appears as Plain Text

This is normal. JSON files are plain text.

To View Formatted:

# PowerShell
Get-Content ".\Reports\SecurityAudit_Report_*.json" | ConvertFrom-Json | ConvertTo-Json -Depth 10

# Or use online JSON viewer: https://jsonformatter.org/
# Or use VS Code with JSON extension

Performance Problems

Script Takes a Very Long Time (>10 minutes)

Normal Duration: 2-5 minutes for all modules

Potential Causes:

1. Windows Update Enumeration

# Check if Windows Update is stuck
Get-Service wuauserv
# If Status is "Running" for extended time, may be hung

# Restart Windows Update service
Restart-Service wuauserv

2. Large Event Logs

# Check Security log size
$log = Get-WinEvent -ListLog Security
[math]::Round($log.FileSize / 1MB, 2)  # Size in MB

# If > 2GB, log queries may be slow
# Consider reducing log size or be patient

3. Network Timeouts

  • Script may be waiting for network-dependent checks
  • Especially on systems with network issues

Solution: Run Fewer Modules

# Run quick assessment first
.\Windows-Security-Audit.ps1 -Modules Core

Script Consumes High CPU/Memory

Expected Behavior:

  • CPU spikes during execution are normal
  • Memory usage up to 500MB is normal

If Excessive (>80% CPU for >5 minutes):

# Cancel execution
Press Ctrl+C

# Run with reduced scope
.\Windows-Security-Audit.ps1 -Modules Core,STIG

Multiple Runs Don't Complete

Symptom: Second or third run hangs

Cause: PowerShell module caching

Solution:

# Close PowerShell window completely
# Open new PowerShell window as Administrator
# Try again

# Or force module reload
Remove-Module Module-* -Force -ErrorAction SilentlyContinue
.\Windows-Security-Audit.ps1

Results Interpretation

Many "Error" Status Results

Is this a problem?

It depends. "Error" means the check couldn't complete, not necessarily a security issue.

Common Causes:

  1. Feature not available - BitLocker on Home edition
  2. Service not running - Third-party AV instead of Defender
  3. Insufficient permissions - Check requires specific privilege
  4. System state - Service disabled by design

Review each Error:

  • Read the error message
  • Determine if it's expected for your environment
  • Focus on "Fail" status items for actual security issues

"Info" vs "Warning" vs "Fail"

Understanding Status Levels:

Status Meaning Action Required
Pass Meets requirement None
Fail Does NOT meet requirement Fix
Warning Potential issue, or environment-specific Review
Info For your awareness only Note
Error Could not check Investigate why

Example Scenarios:

Info Status:

Remote Desktop is enabled
  • Not necessarily bad
  • Just informing you it's on
  • Ensure it's intentional and secured

Warning Status:

Built-in Administrator account is enabled
  • Could be OK if renamed and secured
  • Could be a problem if using default settings
  • Review your specific situation

Fail Status:

Guest account is ENABLED
  • Clear security issue
  • Should be fixed
  • No ambiguity

Conflicting Recommendations Between Frameworks

Example:

  • STIG requires 60-day password expiration
  • Some organizations prefer longer (90-day) or no expiration with MFA

Resolution:

  1. Understand your compliance requirements
  2. Risk-based decision making
  3. Document exceptions
  4. Compensating controls

Remember: This tool identifies deviations from standards. You decide which standards to follow based on your risk tolerance and requirements.

Known Limitations

1. Point-in-Time Assessment

The audit represents configuration at the moment of execution. Changes made after the audit won't be reflected.

Solution: Run regularly to detect drift.

2. Local System Only

Script audits the local system, not:

  • Remote systems
  • Domain-wide policies
  • Network infrastructure
  • Cloud resources

Solution: Run on each system individually or use remote execution (see Usage Guide).

3. Read-Only

Script doesn't:

  • Fix issues automatically
  • Apply configurations
  • Modify system settings

Solution: Use remediation commands provided in reports.

4. Context-Unaware

Script doesn't know:

  • Your business requirements
  • Approved exceptions
  • Compensating controls
  • Environment-specific needs

Solution: Review results with qualified security personnel.

5. Not a Security Guarantee

Passing all checks doesn't mean system is 100% secure.

Remember:

  • ✅ Configuration compliance ≠ Complete security
  • ✅ Use as one tool in defense-in-depth strategy
  • ✅ Combine with vulnerability scanning, penetration testing, monitoring

Getting Help

Before Asking for Help

  1. Check this troubleshooting guide
  2. Review error messages carefully
  3. Try running with -Verbose flag
  4. Search existing GitHub issues

Gathering Information

When reporting issues, please include:

# System information
$PSVersionTable
[System.Environment]::OSVersion

# Script version (from script file header)
Get-Content ".\Windows-Security-Audit.ps1" -TotalCount 10

# Error message (full text)
# Screenshot of error if helpful

# Steps to reproduce
# 1. ...
# 2. ...

Reporting Issues

GitHub Issues: https://github.com/Sandler73/Windows-Security-Audit-Project/issues

What to include:

  • Windows version (10/11, Server 2016/2019/2022)
  • PowerShell version
  • Administrator rights (yes/no)
  • Full error message
  • Steps to reproduce
  • What you've already tried

Community Support

  • GitHub Discussions: For questions and usage help
  • Wiki: Documentation and examples
  • Issues: For bugs and feature requests

Commercial Support

This is an open-source project maintained by volunteers. For commercial support or custom development, please contact the maintainers directly.

Still having issues? Open an issue on GitHub

Standalone Module Execution Issues

Issue: Module runs but shows empty or incomplete SharedData

Cause: When running a module directly (e.g., .\modules\module-cis.ps1), the standalone block auto-initializes SharedData but some fields may be limited without the orchestrator.

Solution:

# Ensure you run from the project root directory
cd C:\Path\To\Windows-Security-Audit
.\modules\module-cis.ps1

# If cache-related warnings appear, the shared_components library is optional
# The module will function correctly without it

Issue: Cache warnings during standalone execution

Cause: The cache helper looks for shared_components\audit-common.ps1 which may not exist yet.

Solution: This is expected behavior. Standalone mode gracefully falls back to direct registry queries when cache is unavailable. No action needed.

Clone this wiki locally