ConnectWiseAutomateAgent.psd1
|
@{ # Script module or binary module file associated with this manifest. RootModule = 'ConnectWiseAutomateAgent.psm1' # Version number of this module. ModuleVersion = '2.2.0' # ID used to uniquely identify this module GUID = '37424fc5-48d4-4d15-8b19-e1c2bf4bab67' # Author of this module Author = 'Chris Taylor' # Company or vendor of this module CompanyName = 'Chris Taylor' # Copyright statement for this module Copyright = '(c) 2026 Chris Taylor. All rights reserved.' # Description of the functionality provided by this module Description = 'PowerShell module for working with the ConnectWise Automate Agent.' # Minimum version of the Windows PowerShell engine required by this module PowerShellVersion = '3.0' # Functions to export from this module # ModuleBuilder overwrites this list at build time FunctionsToExport = @('Hide-CWAAAddRemove','Rename-CWAAAddRemove','Show-CWAAAddRemove','Install-CWAA','Redo-CWAA','Uninstall-CWAA','Update-CWAA','Get-CWAAError','Get-CWAALogLevel','Get-CWAAProbeError','Set-CWAALogLevel','Get-CWAAProxy','Set-CWAAProxy','ConvertTo-CWAAScriptOutput','Initialize-CWAAScriptLog','Invoke-CWAAPwsh','Invoke-CWAAScript','New-CWAARemoteMonitor','New-CWAAScriptOutput','Write-CWAAScriptLog','Register-CWAAHealthCheckTask','Repair-CWAA','Restart-CWAA','Start-CWAA','Stop-CWAA','Test-CWAAHealth','Unregister-CWAAHealthCheckTask','Get-CWAAInfo','Get-CWAAInfoBackup','Get-CWAASettings','New-CWAABackup','Reset-CWAA','ConvertFrom-CWAASecurity','ConvertTo-CWAASecurity','Invoke-CWAACommand','Test-CWAAPort','Test-CWAAServerConnectivity') # Cmdlets to export from this module CmdletsToExport = @() # Variables to export from this module VariablesToExport = @() # Aliases to export from this module # ModuleBuilder discovers [Alias()] attributes at build time AliasesToExport = @('ConvertFrom-LTSecurity','ConvertTo-AutomateOutput','ConvertTo-LTSecurity','Get-LTErrors','Get-LTLogging','Get-LTProbeErrors','Get-LTProxy','Get-LTServiceInfo','Get-LTServiceInfoBackup','Get-LTServiceSettings','Hide-LTAddRemove','Initialize-AutomateLogging','Install-LTService','Invoke-CWAScript','Invoke-LTPwsh','Invoke-LTServiceCommand','New-AutomateOutput','New-CWARemoteMonitor','New-LTServiceBackup','Redo-LTService','Register-LTHealthCheckTask','Reinstall-CWAA','Reinstall-LTService','Rename-LTAddRemove','Repair-LTService','Reset-LTService','Restart-LTService','Set-LTLogging','Set-LTProxy','Show-LTAddRemove','Start-LTService','Stop-LTService','Test-LTHealth','Test-LTPorts','Test-LTServerConnectivity','Uninstall-LTService','Unregister-LTHealthCheckTask','Update-LTService','Write-AutomateLog') # Private data to pass to the module specified in RootModule/ModuleToProcess PrivateData = @{ PSData = @{ # Tags applied to this module Tags = @('ChrisTaylorCodes', 'ConnectWise', 'Automate', 'LabTech', 'RMM') # A URL to the license for this module LicenseUri = 'https://github.com/christaylorcodes/ConnectWiseAutomateAgent/blob/main/LICENSE' # A URL to the main website for this project ProjectUri = 'https://github.com/christaylorcodes/ConnectWiseAutomateAgent' # A URL to an icon representing this module IconUri = 'https://raw.githubusercontent.com/christaylorcodes/ConnectWiseAutomateAgent/main/Media/connectwise-automate.png' # ReleaseNotes populated at build time from CHANGELOG.md ReleaseNotes = '## [2.2.0-alpha0010] - 2026-11-14 ### Added - **Script helpers** for scripts run from ConnectWise Automate: `Initialize-CWAAScriptLog`, `Write-CWAAScriptLog`, `New-CWAAScriptOutput`, `ConvertTo-CWAAScriptOutput`, `Invoke-CWAAScript`, `Invoke-CWAAPwsh`, and `New-CWAARemoteMonitor`. See `Examples/ScriptHelper-*.ps1`. Output values are kept to one line (line breaks become ` / `, pipes become `/`). `Invoke-CWAAPwsh` only runs pwsh.exe from Program Files, the PowerShellCore registry install locations, or `-PwshPath`, never from PATH; it reports stderr output as `Status=Error`. - Aliases for the Script helpers that keep the names from the legacy `CW-Automate-ScriptHelper.ps1`: `Initialize-AutomateLogging`, `Write-AutomateLog`, `New-AutomateOutput`, `ConvertTo-AutomateOutput`, `Invoke-CWAScript`, `Invoke-LTPwsh`, and `New-CWARemoteMonitor`. Scripts that still dot-source the old helper file after importing the module will replace these names with the old definitions. - Event ID 4023, written by `Register-CWAAHealthCheckTask` when the scheduled task is missing right after it was created. ### Security - `Invoke-CWAAScript -URL` only accepts `https://` URLs. TLS 1.2 is added for the download when the process setting lacks it, and the previous setting is restored afterwards. - `Initialize-CWAAScriptLog` refuses a log directory whose path passes through a junction or symbolic link, and creates each log file exclusively instead of appending to an existing file. The default log directory is `%windir%\LTSVC\logs`. - `Invoke-CWAAPwsh` never searches `PATH` for pwsh.exe (see Added). Parameter values passed with `-Parameters` are visible on the pwsh.exe command line, so do not pass secrets that way. - `ConvertTo-CWAASecurity` and `ConvertFrom-CWAASecurity` no longer write the encryption key (or, when encoding, the plain text) to the debug stream. `-Debug` output shows a short hash instead. ### Changed - `Register-CWAAHealthCheckTask -Force` on a task that already exists now returns `Updated = $true` (and logs "updated") instead of `Created = $true`. `Created` is only true when no task existed before. - `Register-CWAAHealthCheckTask` writes the task definition to a uniquely named temporary file instead of a fixed `CWAAHealthCheckTask.xml`, because the file holds the installer token. - Dependabot pull requests now target `develop`, the pre-commit hook (`.githooks/pre-commit`) works on Windows and runs `Invoke-QuickTest.ps1`, and `Tests/Invoke-AllTests.ps1` uses the pinned Pester in both modes and fails when the build fails. - Build and test tooling synced with the GitHub-Template (Nov 2026): Pester 6, Sampler 0.120, PSResourceGet dependency resolution with version ranges in `RequiredModules.psd1`, and a new `Assert_RequiredModule_Versions` build task. Build tooling now requires PowerShell 7.6+; the module itself still supports PowerShell 3.0+. - Markdown command help is now generated with Microsoft.PowerShell.PlatyPS 1.x (`./build.ps1 -Tasks docs`) into `Docs/Help/ConnectWiseAutomateAgent/`. `Docs/Help/ConnectWiseAutomateAgent.md` remains the hand-written function index. The per-function pages moved from `Docs/Help/<Function>.md` to `Docs/Help/ConnectWiseAutomateAgent/<Function>.md`, so links to the old paths no longer resolve. - CI hardening: actions pinned to commit SHAs (checkout v7, upload-artifact v7, download-artifact v8) and kept current by Dependabot, read-only default permissions, no `${{ }}` interpolation inside scripts, publish concurrency, `Publish-PSResource`, and builds on `fix/`, `chore/`, `docs/` and `feature/` branches. Publishing now fails on a duplicate PSGallery version instead of silently skipping (re-runs still skip). - `Invoke-QuickTest.ps1` now uses the pinned modules in `output/RequiredModules`, always tests `source/`, fails on failed blocks/containers or zero tests, and always emits JSON in `-OutputFormat Structured`. - `test-local.ps1` now runs tests through the build pipeline (same configuration as CI), also checks tooling scripts for analyzer errors, and restores `PSModulePath` afterwards. ### Removed - The `publish` build workflow (`./build.ps1 -Tasks publish`). Publishing to the PowerShell Gallery happens only in CI. - The `Pester_if_Code_Coverage_Under_Threshold` build task. - The stale MAML help file (`en-US/ConnectWiseAutomateAgent-help.xml`) and the manifest''s `HelpInfoURI`. Nothing generated the file any more and it did not cover the Script helpers. `Get-Help` is unchanged: it reads the comment-based help in each function. ### Fixed - The example deployment scripts could not run on PowerShell 2.0: the module bootstrap used `*>$null` (a parse error there) and a TLS 1.2 line that does nothing on .NET 3.5, and the GPO example used `Get-CimInstance`. The README now gives a direct download form that works on Windows 7 / Server 2008 R2. - Module source is now ASCII only. The single-file module has no byte order mark, so Windows PowerShell decoded its em dashes as characters that include a double quote when it was loaded by direct download. They were all in comments, so nothing broke, but one inside a string would have stopped the module loading. - `Install-CWAA` could not install on PowerShell versions before 5.0 when using an InstallerToken against a current Automate server, because it unpacked the installer with `Expand-Archive`. It now falls back to .NET 4.5''s ZIP support, then to the Windows shell''s. It also used the `-in` operator, which stopped the whole module from loading on PowerShell 2.0. - On PowerShell 2.0, server resolution and the module''s proxy and key state used `[PSCustomObject]`, which returns a hashtable there. They are now created with `New-Object PSObject`. - TLS 1.2 is now also requested on .NET 3.5 (PowerShell 2.0 on Windows 7 / Server 2008 R2), where it works once the TLS 1.2 update for .NET 3.5.1 is installed. - The automatic relaunch from 32-bit to 64-bit PowerShell in direct download mode (used when the module is loaded from tools such as ScreenConnect) ran `Initialize-CWAA` in the 64-bit session instead of the caller''s commands, failed, and then ended the 32-bit session with nothing done. It now runs the original `powershell.exe` command line again in 64-bit (`-Command`, `-File` with its arguments, or `-EncodedCommand`) and exits with its exit code. Sessions that cannot be run again (not started with `-Command`, `-File` or `-EncodedCommand`, or started with `-NoExit`) get a warning and continue in 32-bit, as does a session whose 64-bit relaunch fails to start. - Importing the module with `Import-Module` from 32-bit PowerShell no longer attempts that relaunch; it only warns, as documented. - `Set-CWAAProxy -ProxyPassword` and `-EncodedProxyPassword` stored the text "System.Security.SecureString" as the proxy password, and `-ProxyCredential` failed with a conversion error. All three now apply the real password. Encoded credentials that cannot be decoded with the agent password are now an error instead of being applied as blank. - `Install-CWAA` with a proxy enabled failed after the MSI had installed, because it passed the proxy password to `Set-CWAAProxy` as plain text. The install was logged as failed and installer cleanup, `-Hide` and `-Rename` were skipped. - `Set-CWAAProxy -DetectProxy` could enable the Automate server''s own address as the proxy when no proxy was in use. It now falls back to the WinHTTP proxy setting, and leaves the proxy disabled when there is none. The fallback did not match the English output of `netsh winhttp show proxy`; it now reads both the single-proxy and the per-protocol form, whatever language the label is in, and routes the module''s own requests through the proxy it finds. - `Set-CWAAProxy -ProxyServerURL` without credentials kept the previous proxy''s username and password and wrote them to the agent for the new proxy. They are now cleared. - `Update-CWAA` without `-Version` threw a version conversion error when no server could be reached or the server was too old to offer updates. It now writes a warning that says which. - `Update-CWAA` could leave the session in the updater''s temporary folder when the update extractor failed to start. - `Repair-CWAA` only detected another running repair when it ran under `powershell.exe` and was called as `Repair-CWAA`. It now also detects `pwsh.exe` and the `Repair-LTService` alias, and never terminates the process chain that launched it. - `Repair-CWAA` reported "Agent recovered" after a service restart whenever the last check-in was recent, even if the heartbeat that triggered the restart was still stale. It now waits for both (up to two minutes) and otherwise reports that the agent has not recovered yet. - `-WhatIf` no longer writes "success" events: `Set-CWAAProxy` (event 3020), `Set-CWAALogLevel` (event 3030) and `New-CWAABackup` (event 3010). `New-CWAABackup` also no longer reports "backup has been created" when files could not be copied or `reg.exe` returned an error. Both cases now write an error, and a failed registry export stops before the import instead of importing an older export file. - Pester configuration in `build.yaml` used the `Script` key, which Sampler ignores; test discovery could fall back to a lowercase `tests` path on case-sensitive runners. - Per-function and per-alias export tests in `ConnectWiseAutomateAgent.Module.Tests.ps1` were silently generating zero test cases because their data was defined after discovery. - `Register-CWAAHealthCheckTask` now recreates the scheduled task when `-IntervalHours`, `-Server`, or `-LocationID` change, not only when `-InstallerToken` changes. - `Register-CWAAHealthCheckTask` now verifies the scheduled task actually exists after registration and logs an error (event ID 4023) if it doesn''t (e.g. removed by AV/policy immediately after creation). - `Register-CWAAHealthCheckTask` now correctly writes to the Windows Event Log on registration failure even when the caller has set `$ErrorAc' # Prerelease tag for PSGallery (ASCII alphanumeric only, no dots/hyphens) # Controlled by GitVersion at build time; leave empty in source Prerelease = 'alpha0010' } } } |