en-US/about_DattoRMM.CoreSecurity.help.txt
|
TOPIC
about_DattoRMM.CoreSecurity SHORT DESCRIPTION Describes the security model of the DattoRMM.Core module, including credential handling, PII handling philosophy, SecureString behaviour, and safe automation patterns. LONG DESCRIPTION Security is a core design principle of the DattoRMM.Core module. The module handles API credentials and access tokens with deliberate safeguards throughout the session lifecycle. API data — including fields that may contain personally identifiable information (PII) — is returned exactly as provided by the Datto RMM API. PII governance is the caller's responsibility. ## CREDENTIAL HANDLING ### Secrets in Memory Only - API secrets are accepted as `SecureString` or `PSCredential` objects — never as plaintext strings. - Access tokens are stored in a script-scoped variable (`$Script:RMMAuth`) and are never written to disk. - When the module is removed from the session, all authentication state (tokens, proxy credentials) is cleared automatically. ### Credential Lifecycle **Key/Secret and Credential authentication:** 1. Credentials are supplied via `Connect-DattoRMM`. 2. The module exchanges them for an API token and stores the token in memory. 3. If `-AutoRefresh` is enabled, credentials are retained in memory for automatic token renewal. 4. On `Disconnect-DattoRMM` or module removal, all credentials and tokens are cleared. **ApiToken authentication (bring your own token):** 1. A pre-existing token is supplied via `Connect-DattoRMM -ApiToken`. 2. The token is stored in memory. No credentials are stored. 3. `-AutoRefresh` is not available. The module does not track token expiry. 4. On `Disconnect-DattoRMM` or module removal, the token is cleared. This separation means that in ApiToken mode, no credentials capable of generating new tokens are ever present in the module's memory — only the token itself. **Request-RMMToken (standalone token generation):** `Request-RMMToken` generates a token from the OAuth endpoint and returns it as a `DRMMToken` object. It does not store anything in the module's authentication state. Credentials are used only for the duration of the token request and are not retained. ### SecureString Cross-Platform Behaviour The module runs on PowerShell 7+ (Core edition), which supports Windows, Linux, and macOS. SecureString handling differs by platform: - **Windows** — `SecureString` values are decrypted using secure .NET APIs. Memory is zeroed immediately after use. - **Linux/macOS** — `SecureString` is converted via `PSCredential.GetNetworkCredential().Password`. Due to .NET Core limitations, plaintext may persist in managed memory until garbage collection runs. In all cases, sensitive variables are cleared from scope as soon as they are no longer needed. > [!NOTE] > This is a .NET Core platform limitation, not specific to this module. On non-Windows platforms, `SecureString` provides reduced protection compared to Windows. ## PII HANDLING ### Philosophy DattoRMM.Core is an SDK — a neutral data layer. It returns Datto RMM API data exactly as provided, without filtering, masking, or confirmation prompts on read operations. Read operations such as `Get-RMMUser`, `Get-RMMDevice`, and `Get-RMMActivityLog` behave like standard SDK cmdlets (comparable to Microsoft Graph, AzureAD, or Exchange Online PowerShell). No confirmation prompt is applied. The reasons for this approach: - **Consistency** — All data flows (object properties, CSV exports, pipeline, console output, transcripts) would require coordinated masking. Partial masking creates false security. - **User control** — PII governance is the caller's responsibility, not the SDK's. Different organisations have different policies. - **Discoverability** — Data masked by default hides legitimate values from legitimate users. - **Extensibility** — The module provides type and format extension points for users who need PII protection without requiring changes to the module itself. ### If You Need PII Protection Use the custom type/format extension system: - **Types.ps1xml** — Define masked `ScriptProperty` members (e.g., `MaskedEmail`, `MaskedTelephone`) and reference them in pipelines or export transforms. - **Format.ps1xml** — Override default table views to display only masked properties. - **Profile folder** — Place files in `$HOME/.DattoRMM.Core/` following the `DattoRMM.Core.*.Types.ps1xml` and `DattoRMM.Core.*.Format.ps1xml` naming convention. - **MaskString utility** — `[DRMMObject]::MaskString($value, $visibleChars, $maskChar)` is available as a static method for use in custom type properties. See about_DattoRMM.CoreTypeExtensions and about_DattoRMM.CoreFormatExtensions for examples. A reference example is provided in docs/examples/PII-Safe-Output-Pack/. ### WhatIf Support Mutating commands support `-WhatIf` to preview what would happen without making changes: ```powershell Move-RMMDevice -DeviceUid "abc-123" -TargetSiteUid "def-456" -WhatIf ``` ## SAFE AUTOMATION PATTERNS ### Force and Confirm All mutating commands (`Move-RMMDevice`, `Set-RMMDeviceUdf`, `Resolve-RMMAlert`, `New-RMMQuickJob`, etc.) support: - `-Force` — Suppresses confirmation prompts for unattended execution. - `-WhatIf` — Simulates the operation without applying changes. - `-Confirm` — Explicitly enables or disables confirmation (`-Confirm:$false`). ### Preference Variables For bulk automation, you can set `$ConfirmPreference` to control confirmation behaviour at the session level: ```powershell $ConfirmPreference = 'None' # All mutating commands run without confirmation prompts Get-RMMSite -Name "Staging" | Get-RMMDevice | Move-RMMDevice -Site $Target ``` > [!WARNING] > Setting `$ConfirmPreference` to `None` disables all confirmation prompts, including for destructive operations. Use this only in controlled automation scripts where you understand every operation being performed. ## API KEY SECURITY ### Key Regeneration `Reset-RMMAPIKeys` regenerates the API access key and secret for the authenticated user. This immediately invalidates the current session. - With `-ReturnNewKey`, the new key/secret pair is returned as a `DRMMAPIKeySecret` object (secret as `SecureString`). - Without `-ReturnNewKey`, the new keys are discarded and must be retrieved from the Datto RMM web portal. ```powershell $NewKeys = Reset-RMMAPIKeys -ReturnNewKey ``` ### Token Clipboard Copy `Set-RMMTokenClipboard` copies the current session access token to the system clipboard. No token value is written to the console or captured by transcripts. This is a security-sensitive operation and supports `-WhatIf`, `-Confirm`, and `-Force`. > [!WARNING] > Clear the clipboard after use (`Set-Clipboard -Value $null`). If Windows Cloud Clipboard synchronisation is enabled, the token may be transmitted to Microsoft servers. ## PROXY CREDENTIAL SECURITY When connecting through an authenticated proxy, proxy credentials follow the same lifecycle as API credentials: - Stored in memory only (`$Script:RMMAuth.ProxyCredential`). - Cleared on `Disconnect-DattoRMM` or module removal. - Never written to disk. ## EXAMPLES ### Example 1: Safe bulk operation with WhatIf ```powershell Get-RMMSite -Name "Staging" | Get-RMMDevice | Move-RMMDevice -Site $TargetSite -WhatIf ``` ### Example 2: Unattended automation with Force ```powershell Get-RMMAlert -Status Open | Resolve-RMMAlert -Force ``` ## SEE ALSO - about_DattoRMM.Core - about_DattoRMM.CoreAuthentication - about_DattoRMM.CoreConfiguration - about_DattoRMM.CoreTypeExtensions - about_DattoRMM.CoreFormatExtensions SEE ALSO https://github.com/TheShadowTek/DattoRMM.Core/blob/main/docs/about/about_DattoRMM.CoreSecurity.md |