feat(live-response): ✨ Added Invoke-MdeMachineLiveResponse function

Author: itpropro

src/public/Invoke-MdeMachineAntivirusScan.ps1

@@ -18,7 +18,7 @@
   Comment to associate with the action.
 
 .PARAMETER scanType
-  Optional. Defines the type of the Scan. Required. Allowed values are: 'Quick' or 'Full' (default: 'Quick').
+  Optional. Defines the type of the Scan. Allowed values are: 'Quick' or 'Full' (default: 'Quick').
 
 .EXAMPLE
   Invoke-MdeMachineAntivirusScan -id "MACHINE_ID" -comment "Your comment"

src/public/Invoke-MdeMachineLiveResponse.ps1

@@ -0,0 +1,54 @@
+<#
+.SYNOPSIS
+  Runs a sequence of live response commands on a device.
+
+.DESCRIPTION
+  Runs a sequence of live response commands on a device.
+
+.NOTES
+  Author: Jan-Henrik Damaschke
+
+.LINK
+  https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/run-live-response?view=o365-worldwide
+
+.PARAMETER id
+  Specifies the id of the target MDE machine.
+
+.PARAMETER comment
+  Comment to associate with the action.
+
+.PARAMETER commands
+  Array of commands to run. Allowed values are "PutFile", "RunScript", "GetFile". See the reference link for more details on the body.
+
+.EXAMPLE
+  Invoke-MdeMachineLiveResponse -id "MACHINE_ID" -comment "Your comment" -commands @(@{type = "RunScript"; params = @(@{key = "scriptName"; value = "scriptFile.ps1"}; @{key = "Args"; value = "argument1"})})
+
+.ROLE
+  @(@{permission = 'Machine.LiveResponse'; permissionType = 'Application'}, @{permission = 'Machine.LiveResponse'; permissionType = 'Delegated'})
+#>
+
+function Invoke-MdeMachineLiveResponse {
+  [CmdletBinding()]
+  param (
+    [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)]
+    [string]
+    $id,
+    [Parameter(Mandatory)]
+    [string]
+    $comment,
+    [Parameter(Mandatory)]
+    [array]
+    $commands
+  )
+  Begin {
+    if (-not (Test-MdePermissions -functionName $PSCmdlet.CommandRuntime)) {
+      $requiredRoles = (Get-Help $PSCmdlet.CommandRuntime -Full).role | Invoke-Expression
+      Throw "Missing required permission(s). Please check if one of these is in current token roles: $($requiredRoles.permission)"
+    }
+  }
+  Process {
+    return Invoke-RetryRequest -Method Post -Uri "https://api.securitycenter.microsoft.com/api/machines/$id/runliveresponse" -body (ConvertTo-Json -Depth 5 -InputObject @{ Comment = $comment; Commands = $commands })
+  }
+  End {}
+}
+

tests/public/Invoke-MdeMachineLiveResponse.Tests.ps1

@@ -0,0 +1,33 @@
+BeforeAll {
+  Remove-Module PSMDE -Force -ErrorAction SilentlyContinue
+  Import-Module (Split-Path $PSCommandPath).replace('tests', 'src').Replace('public', 'PSMDE.psd1')
+}
+
+Describe "Invoke-MdeMachineLiveResponse" {
+
+  It 'Should have the PSMDE module loaded' {
+    $module = Get-Module PSMDE
+    $module | Should -Not -BeNullOrEmpty
+  }
+
+  It 'Should have access to internal functions' {
+    InModuleScope PSMDE {
+      $iar = Get-Command Invoke-AzureRequest
+      $iar | Should -Not -BeNullOrEmpty
+    }
+  }
+
+  It 'Should correctly create the request uri' {
+    InModuleScope PSMDE {
+      Mock Invoke-RetryRequest { return @{uri = $uri; body = $body } }
+      Mock Test-MdePermissions { return $true }
+      $id = '12345'
+      $comment = 'Comment'
+      $commands = @(@{type = "RunScript"; params = @(@{key = "scriptName"; value = "scriptFile.ps1" }; @{key = "Args"; value = "argument1" }) })
+      $body = ConvertTo-Json -Depth 5 -InputObject @{comment = $comment; commands = $commands }
+      $result = Invoke-MdeMachineLiveResponse -id $id -comment $comment -commands $commands
+      $result.uri | Should -Be "https://api.securitycenter.microsoft.com/api/machines/$id/runliveresponse"
+      $result.body | Should -Be $body
+    }
+  }
+}