directory_size_analyze.ps1

directory_size_analyze.ps1

Runs a command-line disk usage analysis on a specified directory using gdu (Go Disk Usage analyzer).

Overview

This script is designed for unattended RMM execution. It downloads the gdu utility from GitHub releases if not already present, extracts it to a local cache directory, and executes it against the target path in non-interactive mode to return text or JSON output.

Purpose

Provides fast and reliable disk usage analysis for Windows systems through RMM platforms. The script eliminates package manager dependencies by directly downloading the gdu executable, caching it locally for performance, and executing scans with configurable timeout protection and output formats.

Prerequisites

• PowerShell 5.1 or later
• Internet access to reach github.com for initial download
• Write permissions to the cache directory (uses Windows TEMP)

Configuration

Required Inputs

• $ScanPath - The target directory to scan

  • Example: "C:\Users"
  • Must be a valid directory path

• $ScanDepth - The number of levels deep to report sizes for

  • Controls top N items shown
  • Default: 1
  • Must be 1 or greater

• $ScanTimeout - Maximum seconds to allow for the scan operation

  • Default: 600 (10 minutes)
  • Set to 0 to disable timeout

• $OutputFormat - Output format

  • Options: 'text' or 'json'
  • Default: 'text'

• $GduVersion - The GitHub release version to download

  • Default: 'v5.31.0'

• $GduDownloadUrl - Direct download URL for the gdu Windows executable zip

  • Default: 'https://github.com/dundee/gdu/releases/download/v5.31.0/gdu_windows_amd64.exe.zip'

• $GduCacheDir - Local directory to cache the gdu executable

  • Default: Uses $env:TEMP for automatic OS cleanup
  • Dynamic based on Windows TEMP directory

• $CleanupAfterRun - Whether to delete the gdu cache directory after execution

  • Default: $true
  • Set to $false to keep gdu cached for future runs

Settings

• Downloads and extracts gdu to a cache directory if not present
• No package manager dependencies (winget, chocolatey, etc.)
• Includes timeout protection for long-running scans
• Supports multiple output formats (text or JSON)
• Optional cleanup of downloaded files after completion

Behavior

This script is all-or-nothing. If any step fails (e.g., download, extract, or scan), the script will stop and report an error.

1. Validates all hardcoded inputs
2. Ensures cache directory exists
3. Checks for existing gdu executable
4. Downloads gdu from GitHub releases if needed
5. Extracts and renames executable
6. Executes disk usage scan with configured parameters
7. Returns output in specified format (text or JSON)
8. Optionally cleans up cached files

Security Notes

• No secrets are printed to the console
• Downloads from official GitHub releases
• Consider verifying SHA256 checksums in production environments
• Uses TLS 1.2 for secure downloads

Exit Codes

• 0: Success - Scan completed successfully
• 1: Failure - Validation error, download failure, or scan error

Example Output

[ INPUT VALIDATION ]
--------------------------------------------------------------
ScanPath        : C:\Users
ScanDepth       : 1
ScanTimeout     : 600 seconds
OutputFormat    : text
GduVersion      : v5.31.0
GduCacheDir     : C:\Users\username\AppData\Local\Temp\gdu_rmm_cache
CleanupAfterRun : True

[ OPERATION ]
--------------------------------------------------------------
Checking cache directory: C:\Users\username\AppData\Local\Temp\gdu_rmm_cache
Cache directory exists.
Checking for gdu executable: C:\Users\username\AppData\Local\Temp\gdu_rmm_cache\gdu.exe
gdu executable already present.
Preparing to execute gdu scan...
Executing: C:\Users\username\AppData\Local\Temp\gdu_rmm_cache\gdu.exe -n -p -c -a -t 50 C:\Users
Timeout protection enabled: 600 seconds
Scan finished successfully.

[ RESULT ]
--------------------------------------------------------------
Status : Success

[ FINAL STATUS ]
--------------------------------------------------------------
Directory scan complete. Output:
[gdu output appears here]

[ CLEANUP ]
--------------------------------------------------------------
Cleaning up gdu cache directory: C:\Users\username\AppData\Local\Temp\gdu_rmm_cache
Cleanup complete. Cache directory removed.

[ SCRIPT COMPLETED ]
--------------------------------------------------------------

Version History

• 2025-10-30 v2.0.0 - Complete rewrite using direct gdu download:
  • Removed all package manager dependencies (no winget/PSGallery)
  • Direct download from GitHub releases
  • Local caching of executable in Windows TEMP directory
  • Simpler, faster, more reliable deployment
  • No PATH manipulation needed
  • JSON output support for structured data
  • Optional cleanup after execution (enabled by default)
  • Timeout protection for long-running scans
  • Proper gdu flags for non-interactive output (-t for top items)
  • Uses $env:TEMP for cache (automatic OS cleanup of leftover files)

Links

• View Script Source
• gdu GitHub Repository
• Scripts - Back to script index