diff --git a/src/integrations.datto.ps1 b/src/integrations.datto.ps1 index 899f9df..543a954 100644 --- a/src/integrations.datto.ps1 +++ b/src/integrations.datto.ps1 @@ -1,3 +1,161 @@ +<# +.SYNOPSIS +Installs the Datto RMM agent and/or performs Datto RMM site operations using API or webhook-provided credentials. + +.DESCRIPTION +Install-DattoRMM can obtain Datto RMM API credentials either directly (ApiUrl/ApiKey/ApiSecretKey) or via a webhook +(-UseWebhook). It then acquires an OAuth token and can: +- Fetch sites (-FetchSites), optionally saving the list to CSV/JSON (-SaveSitesList, -OutputFile) +- Pull a site's variables and write them to the registry (-PushSiteVars, -SiteUID, -SiteName) +- Download and launch the RMM agent installer for a site (-InstallRMM, -SiteUID, -SiteName) +- Download and save a copy of the installer (-SaveCopy, -SiteUID) + +.PARAMETER UseWebhook +If specified, retrieves API credentials from the webhook endpoint specified by -WebhookUrl. +If not specified, -ApiUrl/-ApiKey/-ApiSecretKey must be provided. + +.PARAMETER WebhookPassword +Optional shared secret sent as the SAMYPW header when calling the webhook. +If null, it is treated as a blank string (intended for allowlisted IP flows). + +.PARAMETER WebhookUrl +Webhook endpoint to retrieve Datto RMM API credentials. Defaults to $Global:DattoWebhookUrl. + +.PARAMETER ApiUrl +Base URL of the Datto RMM instance (for example, https://rmm.example.com). +Required when -UseWebhook is not specified. + +.PARAMETER ApiKey +Datto RMM API key (used as the OAuth username in the token request). +Required when -UseWebhook is not specified. + +.PARAMETER ApiSecretKey +Datto RMM API secret key (used as the OAuth password in the token request). +Required when -UseWebhook is not specified. + +.PARAMETER FetchSites +If specified, fetches the full site list from the Datto RMM API and returns objects with Name and UID. + +.PARAMETER SaveSitesList +If specified, saves the fetched site list to disk. Requires -FetchSites. +The output format is determined by -OutputFile extension: +- .csv (default): CSV output +- .json: JSON output + +.PARAMETER OutputFile +Filename to write when using -SaveSitesList. Defaults to 'datto_sites.csv'. +The file is written to the current user's Desktop. + +.PARAMETER PushSiteVars +If specified, fetches variables for the specified site and writes them to the registry at: +HKLM:\Software\SVS\Deployment +Requires -SiteUID. -SiteName is used for logging. + +.PARAMETER InstallRMM +If specified, downloads the Datto RMM agent installer for -SiteUID to %TEMP%\AgentInstall.exe and launches it. +Requires -SiteUID. -SiteName is used for logging. Respects ShouldProcess/Confirm. + +.PARAMETER SaveCopy +If specified, downloads the Datto RMM agent installer for -SiteUID and saves it to: +C:\Temp\AgentInstall.exe +Requires -SiteUID. + +.PARAMETER SiteUID +Datto RMM Site UID used for site-scoped operations such as variable fetch, agent download/install, and save-copy. + +.PARAMETER SiteName +Friendly site name used for logging/output messages for site-scoped operations. Not required by the API calls. + +.EXAMPLE +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites + +Fetches the full site list from the Datto RMM API and returns objects containing Name and UID. + +.EXAMPLE +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites -SaveSitesList + +Fetches the site list and saves it as a CSV named "datto_sites.csv" on the current user's Desktop (default -OutputFile), +then returns the site list. + +.EXAMPLE +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites -SaveSitesList -OutputFile "sites.csv" + +Fetches the site list and saves it as "sites.csv" on the Desktop. + +.EXAMPLE +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites -SaveSitesList -OutputFile "sites.json" + +Fetches the site list and saves it as JSON ("sites.json") on the Desktop. + +.EXAMPLE +Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -WebhookPassword "SuperSecret" -FetchSites -SaveSitesList + +Uses the webhook endpoint to retrieve API credentials, then fetches sites and saves "datto_sites.csv" to the Desktop. + +.EXAMPLE +Install-DattoRMM -UseWebhook -WebhookUrl "https://internal.example.com/datto-creds" -FetchSites + +Uses the webhook endpoint to retrieve API credentials, then fetches and returns the site list. + +.EXAMPLE +Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -FetchSites -SaveSitesList -OutputFile "customer_sites.csv" + +Same as the other webhook fetch, but writes the CSV as "customer_sites.csv" on the Desktop. + +.EXAMPLE +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -PushSiteVars -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ" + +Fetches variables for the specified site and writes each variable name/value into: +HKLM:\Software\SVS\Deployment + +.EXAMPLE +Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -PushSiteVars -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ" + +Uses webhook-sourced credentials, then fetches and writes site variables to the registry. + +.EXAMPLE +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -InstallRMM -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ" + +Downloads the agent installer for the specified SiteUID to %TEMP%\AgentInstall.exe and launches it. +Because SupportsShouldProcess is enabled, this may prompt unless -Confirm:$false is used. + +.EXAMPLE +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -InstallRMM -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ" -Confirm:$false + +Installs the agent without prompting for confirmation. + +.EXAMPLE +Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -InstallRMM -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ" -Confirm:$false + +Uses webhook credentials, downloads the installer, and launches it without confirmation. + +.EXAMPLE +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -SaveCopy -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" + +Downloads the agent installer and saves a copy to: +C:\Temp\AgentInstall.exe + +.EXAMPLE +Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -SaveCopy -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" + +Uses webhook credentials, then downloads and saves the installer copy to C:\Temp\AgentInstall.exe. + +.EXAMPLE +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" + +If no action switch is specified (-FetchSites, -PushSiteVars, -InstallRMM, or -SaveCopy), +the function logs a warning indicating that no action was selected. + +.EXAMPLE +# Get the site list, then pick a site and install using its UID +$sites = Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites +$site = $sites | Where-Object Name -like "*Toronto*" | Select-Object -First 1 +Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -InstallRMM -SiteUID $site.UID -SiteName $site.Name -Confirm:$false + +Demonstrates a common flow: fetch sites, select one, then install the agent for that site. +#> + + function Install-DattoRMM { [CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='Medium')] param (