GitHub - dan-damit/TechToolbox: A PowerShell automation framework for IT Professionals' day-to-day ops.

Modular. Worker-Driven. PowerShell Automation at Scale.

TechToolbox unifies practical admin tooling into a single, predictable, portable module with shared configuration, logging, worker patterns, and a clean development model. It targets real-world enterprise operations: Active Directory lifecycle, Exchange Online / Purview workflows, remote diagnostics, browser cleanup, subnet tooling, and AI-assisted automation. The TechAgent runtime supports provider-based LLM routing (Ollama, OpenAI, OpenAI-compatible, Azure OpenAI) with quality controls and telemetry-backed reporting.

Modular. Worker-Driven. PowerShell Automation at Scale.
Contents
Quick Start
- One-Liner Demos
Architecture Overview
Configuration
Invoke-TechAgent Prompt Example
Command Reference
Common Workflows
Developer & Contributor Guide
Security Notes
Troubleshooting
Metadata
- v0.5.70 - "Provider Routing & Quality Controls"
  - Highlights
- v0.5.0 - "AI & Metadata Milestone"
  - Highlights

Quick Start

# Import the module (PowerShell 7+ recommended)
Install-Module TechToolbox -Force
Import-Module TechToolbox -Force

# Browse all exported commands
Get-Command -Module TechToolbox | Sort-Object Name

# Get the built-in help catalog
Get-ToolboxHelp
Get-ToolboxHelp -List          # Commands grouped by verb
Get-ToolboxHelp Invoke-SubnetScan   # Help for one command

One-Liner Demos

Disable-User -Identity 'jdoe' -Credential (Get-Credential)
Clear-BrowserProfileData -WhatIf
Get-SystemSnapshot
Invoke-PurviewPurge -UserPrincipalName admin@company.com -CaseName Case-001 -SearchName Custodian-01 -WhatIf

Architecture Overview

TechToolbox follows a loader-driven, one-function-per-file pattern with deep internal helpers.

Module Layers

TechToolbox/
├── TechToolbox.psd1          # Module manifest (metadata + declared exports)
├── TechToolbox.psm1          # Bootstrap/loader (runtime path resolution, dot-sourcing, export wiring)
├── Public/                   # Exported command scripts + export helper
│   ├── ActiveDirectory/      # AD lifecycle and identity operations
│   ├── AI/                   # AI assistant and agent bridge commands
│   ├── Get/                  # Read/query commands
│   ├── Invoke/               # Action/orchestration commands
│   ├── Set/                  # Configuration/change commands
│   ├── Start_Stop/           # Session/service start-stop commands
│   ├── System/               # Local system and endpoint operations
│   ├── Test/                 # Validation/diagnostic test commands
│   └── Export-ToolboxFunctions.ps1  # Canonical export discovery helper
├── Private/                  # Internal helpers (dot-sourced, not exported)
│   ├── AADSync/              # AAD Connect internals
│   ├── ActiveDirectory/      # AD internal helper functions
│   ├── AI/                   # Agent/prompt helper internals
│   ├── Browser/              # Browser cleanup internals
│   ├── Exchange/             # Exchange helper internals
│   ├── Input/                # Prompt/input utility internals
│   ├── Loader/               # Module home/bootstrap initialization
│   ├── Logging/              # Logging engine internals
│   ├── M365/                 # Microsoft 365 helper internals
│   ├── Network/              # Network helper internals
│   ├── Purview/              # Purview/compliance helper internals
│   ├── Security/             # Security helper internals
│   └── System/               # Shared system helper internals
├── Workers/                  # Remote / background task workers
├── Config/                   # Runtime configuration (config.json, secrets)
│   ├── config.json           # Base settings (git-tracked)
│   └── config.secrets.json   # Tenant secrets (git-ignored)
├── AgentRuntime/             # Packaged C# TechToolbox agent runtime for PSGallery installs
└── commands.md               # Full command catalog with examples

How the Loader Works

Manifest loads first -- TechToolbox.psd1 points to TechToolbox.psm1 and provides module metadata/declared exports.
Bootstrap establishes module state -- TechToolbox.psm1 sets module/home paths and resolves runtime roots without first-import home copy.
Private helpers are dot-sourced -- all .ps1 files under Private/ are loaded recursively into module scope.
Public scripts are dot-sourced -- all .ps1 files under Public/ are loaded (excluding Export-ToolboxFunctions.ps1 in that pass).
Exports are discovered and published -- at import time, Export-ToolboxFunctions discovers public function names, then Export-ModuleMember exports those functions.
Runtime init remains lazy -- Initialize-TechToolboxRuntime initializes config/logging/interop/environment only when needed.

Path Tokens

Portable path tokens replace absolute paths for roaming safety:

Token	Resolves To	Use For
`%TT_ModuleRoot%`	`C:\...\TechToolbox\`	Module-owned files (Config, Workers, Private)
`%TT_Home%`	Module root by default (or override)	Operational data root (logs, exports, prompt templates, history)
`%TT_LogsRoot%`	Resolved logs root	Log file output paths
`%TT_ExportsRoot%`	Resolved exports root	Exported reports / files

Configuration

All configuration flows through Get-TechToolboxConfig. The effective config is the deep merge of:

Config/config.json -- base settings (tracked in source control)
Config/config.secrets.json -- tenant-specific and sensitive overrides (git-ignored)

Keep config.json limited to portable defaults, placeholders, and non-sensitive behavior settings. Put any environment-specific values there only if they are safe to share across every copy of the repo.

Move anything that identifies your environment into config.secrets.json, including:

Domain controllers and search bases
Tenant identifiers and org-specific UPN suffixes
Internal hostnames, servers, and UNC paths
Credential-related values or other machine-specific overrides

Environment Variables

Variable	Purpose
`TT_ConfigSecretsPath`	Override the secrets file location
`TT_DisableConfigSecretsMerge=1`	Skip merge for troubleshooting
`TT_AGENT_LLM_API_KEY`	Optional runtime API key source for cloud providers
`TT_AGENT_SEARCH_WEB_API_KEY`	Optional runtime API key source for SEARCH-WEB provider API

For cloud providers, Invoke-TechAgent also supports secure DPAPI-backed key storage in Config\config.secrets.json (settings.agent.apiKeyEncrypted) via Set-TechAgentApiKey. SEARCH-WEB uses the same pattern through settings.agent.searchWebApiKeyEncrypted via Set-TechAgentSearchWebApiKey.

Configuring Secrets

Use the ignored overlay for site-specific values. Start from Config/config.secrets.example.json, copy it to Config/config.secrets.json, then fill in your local values:

{
  "settings": {
    "tenant": {
      "organizationName": "yourdomain.onmicrosoft.com",
      "upnSuffix": "yourdomain.local",
      "tenantId": "0000-0000-0000-0000"
    },
    "ad": {
      "domainController": "DC01.yourdomain.local",
      "searchBase": "DC=yourdomain,DC=local"
    }
  }
}

Baseline Settings (config.json)

{
  "schemaVersion": 1,
  "settings": {
    "defaults": {
      "promptForHostname": true,
      "promptForCredentials": true,
      "promptForDateRanges": true,
      "showProgress": true,
      "configPath": "%TT_ModuleRoot%\\Config\\config.json"
    },
    "logging": {
      "enableConsole": true,
      "enableFileLogging": true,
      "minimumLevel": "Info",
      "logPath": "%TT_LogsRoot%",
      "logFileNameFormat": "TechToolbox_{yyyyMMdd}.log"
    }
  }
}

Invoke-TechAgent Prompt Example

Preferred prompt workflow

Invoke-TechAgent now defaults to AI\Tasks\CurrentTask.txt when no -Prompt or -PromptFile is supplied.
Use-TechAgentTaskTemplate can stage a reusable prompt template into that file before you run the agent.
-Prompt can still be used for inline prompt text, and -PromptFile can still target any other file when needed.
Provider routing supports ollama (default), openai, openai-compatible, and azure-openai.
Quality controls support -ExecutionMode (execute, analyze, plan), -OutputContract (markdown, plain-text, json), -StrictPromptPreflight, and -QualityProfile.

Example: provider and quality controls

# Cloud provider examples
Invoke-TechAgent -Prompt "Summarize these logs" -Provider openai -Model gpt-4o-mini
Invoke-TechAgent -Prompt "Plan migration steps" -ExecutionMode plan -Provider azure-openai -Endpoint https://your-resource.openai.azure.com -Deployment gpt-4o-mini

# Quality guardrails and output contract examples
Invoke-TechAgent -Prompt "Investigate repeated login failures" -ExecutionMode analyze -OutputContract plain-text -StrictPromptPreflight
Invoke-TechAgent -Prompt "Return remediation checklist as JSON" -OutputContract json -QualityProfile balanced

# Quality telemetry summary for recent runs
Get-TechAgentQualitySummary -Window 20
Get-TechAgentQualitySummary -Window 30 -IncludeRecent 10 -AsJson

Example: stage a task, then run it

Use-TechAgentTaskTemplate -Pick
Invoke-TechAgent

Example: Creating an Online Help Markdown File

The TechAgent uses a structured JSON decision schema and will have an easier time writing files when the prompt clearly specifies the required WRITE-FILE action. A new tool has been created for the agent to use when modifying existing files. REPLACE-IN-FILE should be preferred for localized edits.

Use a prompt similar to the following for consistent results:

Read this file:
C:\repos\TechToolbox\src\TechToolbox.Agent\Agent\AgentOrchestrator.cs

Task: 
Add or improve XML documentation comments for every public type, public
constructor, and public method in this file.

Requirements:
- Modify the existing file in place at this exact path:
  C:\repos\TechToolbox\src\TechToolbox.Agent\Agent\AgentOrchestrator.cs
- Preserve all existing code and behavior.
- Only add or improve XML documentation comments.
- Prefer REPLACE-IN-FILE for localized edits to this existing file.
- Use WRITE-FILE only if a localized replacement is not practical.
- Do not stop after analysis.
- Do not summarize your plan before editing.
- Do not return a final answer until the file update has succeeded.

You can place that prompt directly into AI\Tasks\CurrentTask.txt, or use a template as a starting point:

Use-TechAgentTaskTemplate -List -Category CSharp
Use-TechAgentTaskTemplate -Template CSharp-XmlDocs-InPlace -Show
Use-TechAgentTaskTemplate -Template CSharp-XmlDocs-InPlace
Invoke-TechAgent

Command Reference

The full catalog is at COMMANDS.md. Below is a categorized summary organized by domain.

Active Directory & Identity Management

Function	Purpose
`Disable-User`	Disables an AD user account (destructive)
`Reset-ADPassword`	Resets an AD user password
`New-OnPremUserFromTemplate`	Creates an on-prem user from a template
`Search-User`	Searches for AD users by criteria
`Get-AllUsers`	Enumerates all AD users (with filters)
`Get-LocalAdminMembers`	Lists members of the local Administrators group
`Initialize-TTWordList`	Initializes word list for Password generator

Exchange Online & Compliance

Function	Purpose
`Get-MessageTrace`	Traces an email message through Exchange / EOP
`Invoke-PurviewPurge`	Purges content via Purview compliance portal (destructive)
`Get-AuditSharedMailboxDeletions`	Audits deleted shared mailboxes
`Get-SharedMailboxPermissions`	Lists permissions on shared mailboxes
`Get-AutodiscoverXmlInteractive`	Interactive Autodiscover XML viewer
`Set-EmailAlias`	Sets or adds an email alias for a mailbox user
`Set-ProxyAddress`	Sets the proxy address (SMTP) for a mailbox user
`Test-MailHeaderAuth`	Tests email header authentication results

System Diagnostics & Health

Function	Purpose
`Get-SystemSnapshot`	Captures key system state information
`Get-ErrorEvents`	Queries Windows Event Logs for errors
`Get-BatteryHealth`	Reads battery health / cycle count from powercfg
`Get-SystemUptime`	Reports system uptime
`Get-WindowsProductKey`	Retrieves the installed Windows product key
`Get-PDQDiagLogs`	Retrieves PDQ diagnostics logs
`Get-SystemTrustDiagnostic`	Runs a system trust diagnostic

Endpoint & Infrastructure Operations

Function	Purpose
`Invoke-SystemRepair`	Runs Windows system repair / SFC DISM operations
`Reset-WindowsUpdateComponents`	Resets the Windows Update stack
`Enable-NetFx3`	Enables the .NET Framework 3.5 feature
`Set-PageFileSize`	Configures pagefile size (initial and maximum)
`Set-OneTimeReboot`	Schedules a one-time reboot at a given time
`Get-InstalledPrinters` / `Remove-Printers`	Manage installed printers (destructive on remove)

Remote Execution & Worker Patterns

Function	Purpose
`Invoke-AADSyncRemote`	Runs an AAD Connect synchronization remotely
`Start-NewPSRemoteSession` / `Stop-PSRemoteSession`	Manage PSRemoting sessions (destructive stop)
`Get-RemoteInstalledSoftware`	Inventory software on remote computers
`Copy-Directory`	Copies directory contents (robocopy wrapper)

Browser Cleanup

Function	Purpose
`Clear-BrowserProfileData`	Deletes browser profile data (destructive)
`Invoke-DownloadsCleanup`	Cleans the Downloads folder (destructive)

Networking & Connectivity

Function	Purpose
`Invoke-SubnetScan`	Scans a subnet for active hosts / services
`Start-DnsQueryLogger`	Starts DNS query logging for analysis
`Watch-ISPConnection`	Monitors ISP connection health over time

Credential Management

Function	Purpose
`Get-DomainAdminCredential`	Retrieves domain admin credentials from secure store
`Get-CUCredentialManagerContents`	Lists entries in the Credential Manager

AI-Assisted Workflows

Function	Purpose
`Invoke-TechAgent`	Orchestrates the agent-driven workflow engine with provider routing, execution modes, output contracts, and prompt preflight controls
`Use-TechAgentTaskTemplate`	Stages reusable prompt templates to `AI\Tasks\CurrentTask.txt` for repeatable runs
`Test-TechAgentProvider`	Validates provider configuration and optionally probes live connectivity/auth
`Set-TechAgentApiKey`	Sets/rotates/clears DPAPI-encrypted API keys used by cloud providers
`Set-TechAgentSearchWebApiKey`	Sets/rotates/clears DPAPI-encrypted SEARCH-WEB API keys used by the search tool
`Get-TechAgentQualitySummary`	Summarizes recent run quality metrics from persisted memory history

Export & Packaging

Function	Purpose
`Export-ToolboxFunctions`	Exports all module functions as metadata for the agent
`Get-ToolboxHelp`	Displays the built-in help catalog
`Get-TechToolboxConfig`	Retrieves or updates configuration

Common Workflows

Browser profile cleanup

Clear-BrowserProfileData -WhatIf                          # Dry run
Clear-BrowserProfileData -Browser Chrome                  # Target one browser
Clear-BrowserProfileData -Browser All -IncludeCache:$true  # Full clean

Remote software inventory

Get-RemoteInstalledSoftware -ComputerName srv01,srv02 -Consolidated
Get-RemoteInstalledSoftware -ComputerName laptop01 -IncludeAppx -Credential (Get-Credential)

Purview purge flow

# Always preview first
Invoke-PurviewPurge -UserPrincipalName admin@company.com -CaseName Case-001 -SearchName Search-001 -WhatIf

# Execute when confirmed
Invoke-PurviewPurge -UserPrincipalName admin@company.com -CaseName Case-001 -SearchName Search-001

Exchange Online message trace

Get-MessageTrace -MessageId '<abc123@company.com>'
Get-MessageTrace -MessageId '<abc123@company.com>' -StartDate (Get-Date).AddHours(-12) -EndDate (Get-Date)

AAD Connect remote sync

Invoke-AADSyncRemote -ComputerName 'aadconnect01' -PolicyType Delta
Invoke-AADSyncRemote -ComputerName 'aadconnect01' -PolicyType Initial -UseKerberos -WhatIf

Developer & Contributor Guide

Creating a New Command

Create a new .ps1 file in Public/<Category>/<FunctionName>.ps1.
Use the standard template (see below).
Add the function name to FunctionsToExport in TechToolbox.psd1.
Run Invoke-ScriptAnalyzer -Path .\TechToolbox -Recurse -Severity Error,Warning to validate.
Test with -WhatIf and real data.

<#
.SYNOPSIS
    Short description.

.DESCRIPTION
    Longer description explaining what the function does and when to use it.

.EXAMPLE
    New-MyCommand -Name 'test'
      Does something useful.

.PARAMETER Name
    Description of the Name parameter.

.INPUTS
    None. You cannot pipe objects to this cmdlet.

.OUTPUTS
    System.String (or whatever is returned).

.NOTES
    Requires: Admin rights, network access, etc.
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory = $true)]
    [ValidateNotNullOrEmpty()]
    [string]$Name
)

begin {}
process { Write-Host "$Name" }
end {}

Module Architecture Rules

One function per file -- every .ps1 in Public/ maps to one exported command.
Private helpers stay private -- nothing in Private/ is exported; use them only from other module functions.
No side effects on import -- the .psm1 bootstrap should not run user-facing code; lazy-init everything.
All paths use tokens -- never hardcode absolute paths; resolve via %TT_ModuleRoot% or %TT_Home%.
Module-root first import -- by default, first import does not stage/copy module content to a separate home path. Set TT_Home only when you intentionally want runtime data outside module root.
WhatIf support -- every destructive function must respect $PSCmdlet.ShouldProcess().

Testing Conventions

# Always run WhatIf before real execution
Clear-BrowserProfileData -WhatIf
Invoke-PurviewPurge -UserPrincipalName you@company.com -CaseName Case-001 -SearchName Search-001 -WhatIf
Get-RemoteInstalledSoftware -ComputerName srv01 -WhatIf

# ScriptAnalyzer on every PR
Invoke-ScriptAnalyzer -Path .\TechToolbox -Recurse -Severity Error,Warning

Security Notes

Destructive actions -- functions marked destructive include Disable-User, Clear-BrowserProfileData, Invoke-PurviewPurge, Remove-EpicorEdgeAgent, Remove-Printers, Stop-PSRemoteSession, and others. Always use -WhatIf first.
Credentials -- sensitive credentials are stored in secure config files (git-ignored) or the Credential Manager. Never commit secrets.
CredSSP / Kerberos -- remote execution may require CredSSP delegation or Kerberos auth; configure remoting.credSSPDelegateComputers accordingly.

Troubleshooting

Issue	Resolution
Module import fails	Use PowerShell 7+ and `Import-Module .\TechToolbox.psd1 -Force`
Command not found	Check that it is listed in `FunctionsToExport` in the manifest
Config errors	Verify both `config.json` and `config.secrets.json` are valid JSON; use `TT_DisableConfigSecretsMerge=1` to isolate issues
OpenAI/Azure OpenAI auth fails	Run `Test-TechAgentProvider -Provider <name>` and set a key via `Set-TechAgentApiKey` or `TT_AGENT_LLM_API_KEY`
Path token resolution fails	Run `Test-TTPathRoots -EnsureDirectories` to validate paths
Remoting failures	Verify WinRM is running, auth method matches server config, and credentials have appropriate privileges
Purview / EXO errors	Confirm required roles (Compliance Administrator, etc.) and Exchange Online module installed
Battery report fails	Run elevated if `powercfg` is blocked by group policy
Logging silent	Ensure log directories exist; check `logging.enableFileLogging` setting

Metadata

Author: Dan Damit
License: MIT License
Module version: 0.5.70
PowerShell requirement: 7+ (Core)
Repository: GitHub

v0.5.70 - "Provider Routing & Quality Controls"

Highlights

Provider-based LLM routing in TechAgent (ollama, openai, openai-compatible, azure-openai)
Cloud API key support with environment variable fallback and DPAPI-backed local secret storage
Prompt quality preflight scoring with strict-gate mode for higher-confidence runs
Execution mode contracts (execute, analyze, plan) and output contracts (markdown, plain-text, json)
Persisted run telemetry in agent memory plus quick quality rollups via Get-TechAgentQualitySummary

v0.5.0 - "AI & Metadata Milestone"

Highlights

AI-assisted workflow improvements (Export-ToolboxFunctions, Invoke-TechAgent enhancements)
Full help text capture in agent metadata export
Config system refinements and path token stabilization
Release Template

Name		Name	Last commit message	Last commit date
Latest commit History 1,111 Commits
.github		.github
.vscode		.vscode
AI		AI
Config		Config
Private		Private
Public		Public
Tests		Tests
Workers		Workers
assets		assets
en-US		en-US
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.ready		.ready
Build.ps1		Build.ps1
CHANGELOG.md		CHANGELOG.md
COMMANDS.md		COMMANDS.md
LICENSE.md		LICENSE.md
PSScriptAnalyzerSettings.psd1		PSScriptAnalyzerSettings.psd1
README.md		README.md
TechToolbox.code-workspace		TechToolbox.code-workspace
TechToolbox.psd1		TechToolbox.psd1
TechToolbox.psm1		TechToolbox.psm1
VERSIONING.md		VERSIONING.md
dotnet-tools.json		dotnet-tools.json

Folders and files

Latest commit

History

Repository files navigation

Modular. Worker-Driven. PowerShell Automation at Scale.

Contents

Quick Start

One-Liner Demos

Architecture Overview

Module Layers

How the Loader Works

Path Tokens

Configuration

Environment Variables

Configuring Secrets

Baseline Settings (config.json)

Invoke-TechAgent Prompt Example

Preferred prompt workflow

Example: provider and quality controls

Example: stage a task, then run it

Example: Creating an Online Help Markdown File

Command Reference

Active Directory & Identity Management

Exchange Online & Compliance

System Diagnostics & Health

Endpoint & Infrastructure Operations

Remote Execution & Worker Patterns

Browser Cleanup

Networking & Connectivity

Credential Management

AI-Assisted Workflows

Export & Packaging

Common Workflows

Browser profile cleanup

Remote software inventory

Purview purge flow

Exchange Online message trace

AAD Connect remote sync

Developer & Contributor Guide

Creating a New Command

Module Architecture Rules

Testing Conventions

Security Notes

Troubleshooting

Metadata

v0.5.70 - "Provider Routing & Quality Controls"

Highlights

v0.5.0 - "AI & Metadata Milestone"

Highlights

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages