Skip to content

about_DattoRMM.CoreSecurity.md

Latest commit

 

History

History
160 lines (100 loc) · 7.75 KB

about_DattoRMM.CoreSecurity.md

File metadata and controls

160 lines (100 loc) · 7.75 KB
Raw

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:

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:

$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.
$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

Get-RMMSite -Name "Staging" | Get-RMMDevice | Move-RMMDevice -Site $TargetSite -WhatIf

Example 2: Unattended automation with Force

Get-RMMAlert -Status Open | Resolve-RMMAlert -Force

SEE ALSO