NinjaRmmApi.psm1
|
<#
This file is part of the NinjaRmmApi module. This module is not affiliated with, endorsed by, or related to NinjaRMM, LLC. NinjaRmmApi is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. NinjaRmmApi is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with NinjaRmmApi. If not, see <https://www.gnu.org/licenses/>. #> Function Set-NinjaRmmSecrets { [OutputType('void')] Param( [AllowNull()] [String] $AccessKeyId, [AllowNull()] [String] $SecretAccessKey ) $env:NinjaRmmAccessKeyID = $AccessKeyId $env:NinjaRmmSecretAccessKey = $SecretAccessKey } Function Reset-NinjaRmmSecrets { [Alias('Remove-NinjaRmmSecrets')] [OutputType('void')] Param() Remove-Variable -Name $env:NinjaRmmAccessKeyID Remove-Variable -Name $env:NinjaRmmSecretAccessKey } Function Set-NinjaRmmServerLocation { [OutputType('void')] Param( [ValidateSet('US', 'EU')] [String] $Location = 'US' ) $env:NinjaRmmServerLocation = $Location } Function Send-NinjaRmmApi { [CmdletBinding()] Param( [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [String] $RequestToSend, [ValidateSet('GET', 'PUT', 'POST', 'DELETE')] [String] $Method = 'GET' ) # Stop if our secrets have not been learned. If ($null -eq $env:NinjaRmmSecretAccessKey) { Throw [Data.NoNullAllowedException]::new('No secret access key has been provided. Please run Set-NinjaRmmSecrets.') } If ($null -eq $env:NinjaRmmAccessKeyID) { Throw [Data.NoNullAllowedException]::new('No access key ID has been provided. Please run Set-NinjaRmmSecrets.') } # Get the current date. Calling -Format converts it to a [String], so we # need two separate calls to Get-Date. $DateString = Get-Date -Format 'R' -Date ((Get-Date).ToUniversalTime()) # Format our signing string correctly. # NinjaRMM's signature has a place to put Content-MD5 and Content-Type # values, but leaving them out ($null) seems to be perfectly acceptable. $ContentMD5 = $null $ContentType = $null $StringToSign = @($Method, $ContentMD5, $ContentType, $DateString, $RequestToSend) -Join "`n" # Convert your string to a byte array, and then Base64-encode it. # Not sure why we're removing newlines, but Ninja's example C# code did it. $StringToSignBytes = [Text.Encoding]::UTF8.GetBytes($StringToSign) $EncodedString = ([Convert]::ToBase64String($StringToSignBytes)).Trim() # Construct our HMAC-SHA1 thing, then convert *it* to Base64 as well. # Sample: https://stackoverflow.com/questions/42150420/why-does-encrypting-hmac-sha1-in-exactly-the-same-code-in-c-sharp-and-powershell $Hasher = [Security.Cryptography.KeyedHashAlgorithm]::Create('HMACSHA1') $Hasher.Key = [Text.Encoding]::UTF8.GetBytes($env:NinjaRmmSecretAccessKey) $HashedStringBytes= $Hasher.ComputeHash([Text.Encoding]::UTF8.GetBytes($EncodedString)) # Convert the result to a Base64 string. $Signature = [Convert]::ToBase64String($HashedStringBytes) -Replace "`n","" # Pick our server. By default, we will use the United States server. # However, the European Union server can be used instead.' If (($env:NinjaRmmServerLocation -eq 'US') -or ($null -eq $env:NinjaRmmServerLocation)) { $HostName = 'api.ninjarmm.com' } ElseIf ($env:NinjaRmmServerLocation -eq 'EU') { $HostName = 'eu-api.ninjarmm.com' } Else { Throw [ArgumentException]::new("The server location ${env:NinjaRmmServerLocation} is not valid. Please run Set-NinjaRmmServerLocation.") } # Create a user agent for logging purposes. $UserAgent = "PowerShell/$($PSVersionTable.PSVersion) " $UserAgent += "NinjaRmmApi/$((Get-Module -Name 'NinjaRmmApi').Version) " $UserAgent += '(implementing API version 0.1.2)' # Ensure that TLS 1.2 is enabled, so that we can communicate with NinjaRMM. # It may be disabled by default before PowerShell 6. [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12 # Some new versions of PowerShell also support TLS 1.3. If that is a valid # option, then enable that, too, in case NinjaRMM ever enables it. If ([Net.SecurityProtocolType].GetMembers() -Contains 'Tls13') { [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls13 } # Finally, send it. Write-Debug -Message ("Will send the request:`n`n" ` + "$Method $RequestToSend HTTP/1.1`n" ` + "Host: $HostName`n" ` + "Authorization: NJ ${env:NinjaRmmAccessKeyID}:$Signature`n" ` + "Date: $DateString`n" ` + "User-Agent: $UserAgent") $Arguments = @{ 'Method' = $Method 'Uri' = "https://$HostName$RequestToSend" 'Headers' = @{ 'Authorization' = "NJ ${env:NinjaRmmAccessKeyID}:$Signature" 'Date' = $DateString 'Host' = $HostName 'User-Agent' = $UserAgent } } Return (Invoke-RestMethod @Arguments) } Function Get-NinjaRmmAlerts { [CmdletBinding(DefaultParameterSetName='AllAlerts')] Param( [Parameter(ParameterSetName='OneAlert')] [UInt32] $AlertId, [Parameter(ParameterSetName='AllAlertsSince')] [UInt32] $Since ) $Request = '/v1/alerts' If ($PSCmdlet.ParameterSetName -eq 'OneAlert') { $Request += "/$AlertId" } ElseIf ($PSCmdlet.ParameterSetName -eq 'AllAlertsSince') { $Request += "/since/$Since" } Return (Send-NinjaRmmApi -RequestToSend $Request) } Function Reset-NinjaRmmAlert { [CmdletBinding()] [Alias('Remove-NinjaRmmAlert')] Param( [Parameter(Mandatory)] [UInt32] $AlertId ) Return (Send-NinjaRmmApi -Method 'DELETE' -RequestToSend "/v1/alerts/$AlertId") } Function Get-NinjaRmmCustomers { [CmdletBinding(DefaultParameterSetName='AllCustomers')] Param( [Parameter(ParameterSetName='OneCustomer')] [UInt32] $CustomerId ) $Request = '/v1/customers' If ($PSCmdlet.ParameterSetName -eq 'OneCustomer') { $Request += "/$CustomerId" } Return (Send-NinjaRmmApi -RequestToSend $Request) } Function Get-NinjaRmmDevices { [CmdletBinding(DefaultParameterSetName='AllDevices')] Param( [Parameter(ParameterSetName='OneDevice')] [UInt32] $DeviceId ) $Request = '/v1/devices' If ($PSCmdlet.ParameterSetName -eq 'OneDevice') { $Request += "/$DeviceId" } Return (Send-NinjaRmmApi -RequestToSend $Request) } |