initial copy of Accelerynt-Security AS-MDE-Unisolate-Machine repo

Playbooks/AS-MDE-Unisolate-Machine/README.md

@@ -0,0 +1,174 @@
+# AS-MDE-Unisolate-Machine
+
+Author: Accelerynt
+
+For any technical questions, please contact info@accelerynt.com  
+
+[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAccelerynt-Security%2FAS-MDE-Unisolate-Machine%2Fmain%2Fazuredeploy.json)
+[![Deploy to Azure Gov](https://aka.ms/deploytoazuregovbutton)](https://portal.azure.us/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAccelerynt-Security%2FAS-MDE-Unisolate-Machine%2Fmain%2Fazuredeploy.json)       
+
+This playbook is intended to be run from a Microsoft Sentinel incident. It will match the hosts from a Microsoft Sentinel incident with Microsoft Defender machines and free them from isolation in Defender. A comment noting the affected machines will be added to the Microsoft Sentinel incident.
+                                                                                                                                     
+![UnisolateMachine_Demo_1](Images/UnisolateMachine_Demo_1.png)
+
+
+#
+### Requirements
+                                                                                                                                     
+The following items are required under the template settings during deployment: 
+
+* A Microsoft Azure Active Directory [app registration](https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine#create-an-app-registration) with admin consent granted for "**Machine.Isolate**" in the "**WindowsDefenderATP**" API
+* An [Azure key vault secret](https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine#create-an-azure-key-vault-secret) containing your app registration client secret
+
+
+> **Note**
+> This playbook is meant to be used in tandem with https://github.com/Accelerynt-Security/AS-MDE-Isolate-Machine. The "**Create an App Registration**" and "**Create an Azure Key Vault Secret**" setup steps only need to be completed once, as both playbooks share the same requirements.
+
+
+# 
+### Setup
+
+#### Create an App Registration
+
+Navigate to the Microsoft Azure Active Directory app registration page: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
+
+Click "**New registration**".
+
+![UnisolateMachine_App_Registration_1](Images/UnisolateMachine_App_Registration_1.png)
+
+Enter "**AS-MDE-Isolate-Machine**" for the name, all else can be left as is. Click "**Register**".
+
+![UnisolateMachine_App_Registration_2](Images/UnisolateMachine_App_Registration_2.png)
+
+Once the app registration is created, you will be redirected to the "**Overview**" page. Under the "**Essentials**" section, take note of the "**Application (client) ID**", as this will be needed for deployment.
+
+![UnisolateMachine_App_Registration_3](Images/UnisolateMachine_App_Registration_3.png)
+
+Next, you will need to add permissions for the app registration to call the [Microsoft Defender Isolate machine endpoint](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/api/isolate-machine?view=o365-worldwide#http-request). From the left menu blade, click "**API permissions**" under the "**Manage**" section. Then, click "**Add a permission**".
+
+![UnisolateMachine_App_Registration_4](Images/UnisolateMachine_App_Registration_4.png)
+
+From the "**Select an API**" pane, click the "**APIs my organization uses**" tab, then paste "**WindowsDefenderATP**" in the search bar. Click the option matching the search.
+
+![UnisolateMachine_App_Registration_5](Images/UnisolateMachine_App_Registration_5.png)
+
+Click "**Application permissions**", then type "**Machine.Unisolate**" into the search bar and select the result. Click "**Add permissions**".
+
+![UnisolateMachine_App_Registration_6](Images/UnisolateMachine_App_Registration_6.png)
+
+Admin consent will be needed before your app registration can use the assigned permission. Click "**Grant admin consent for (name)**".
+
+![UnisolateMachine_App_Registration_7](Images/UnisolateMachine_App_Registration_7.png)
+
+Lastly, a client secret will need to be generated for the app registration. From the left menu blade, click "**Certificates & secrets**" under the "**Manage**" section. Then, click "**New client secret**". Enter a description and select the desired expiration date, then click "**Add**".
+
+![UnisolateMachine_App_Registration_8](Images/UnisolateMachine_App_Registration_8.png)
+
+Copy the value of the secret that is generated, as this will be needed for [Create an Azure Key Vault Secret](https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine#create-an-azure-key-vault-secret).
+
+![UnisolateMachine_App_Registration_9](Images/UnisolateMachine_App_Registration_9.png)
+
+
+#### Create an Azure Key Vault Secret
+
+Navigate to the Azure key vaults page: https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults
+
+Navigate to an existing key vault or create a new one. From the key vault overview page, click the "**Secrets**" menu option, found under the "**Settings**" section. Click "**Generate/Import**".
+
+![UnisolateMachine_Key_Vault_1](Images/UnisolateMachine_Key_Vault_1.png)
+
+Choose a name for the secret, such as "**AS-MDE-Isolate-Machine--AR-Client-Secret**", and enter the client secret copied in the [previous section](https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine#create-an-app-registration). All other settings can be left as is. Click "**Create**". 
+
+![UnisolateMachine_Key_Vault_2](Images/UnisolateMachine_Key_Vault_2.png)
+
+Once your secret has been added to the vault, navigate to the "**Access policies**" menu option. Leave this page open, as you will need to return to it once the playbook has been deployed. See [Granting Access to Azure Key Vault](https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine#granting-access-to-azure-key-vault).
+
+![UnisolateMachine_Key_Vault_3](Images/UnisolateMachine_Key_Vault_3.png)
+
+
+#
+### Deployment
+
+To configure and deploy this playbook:
+ 
+Open your browser and ensure you are logged into your Microsoft Sentinel workspace. In a separate tab, open the link to our playbook on the Accelerynt Security GitHub repository:
+
+https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine
+
+[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAccelerynt-Security%2FAS-MDE-Unisolate-Machine%2Fmain%2Fazuredeploy.json)
+[![Deploy to Azure Gov](https://aka.ms/deploytoazuregovbutton)](https://portal.azure.us/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAccelerynt-Security%2FAS-MDE-Unisolate-Machine%2Fmain%2Fazuredeploy.json)                                             
+
+Click the "**Deploy to Azure**" button at the bottom and it will bring you to the custom deployment template.
+
+In the **Project Details** section:
+
+* Select the "**Subscription**" and "**Resource Group**" from the dropdown boxes you would like the playbook deployed to.  
+
+In the **Instance Details** section:
+
+* **Playbook Name**: This can be left as "**AS-MDE-Unisolate-Machine**" or you may change it.
+
+* **Client ID**: Enter the Application (client) ID of your app registration referenced in [Create an App Registration](https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine#create-an-app-registration).
+
+* **Key Vault Name**: Enter the name of the key vault referenced in [Create an Azure Key Vault Secret](https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine#create-an-azure-key-vault-secret).
+
+* **Secret Name**: Enter the name of the key vault Secret created in [Create an Azure Key Vault Secret](https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine#create-an-azure-key-vault-secret).
+
+Towards the bottom, click on "**Review + create**". 
+
+![UnisolateMachine_Deploy_1](Images/UnisolateMachine_Deploy_1.png)
+
+Once the resources have validated, click on "**Create**".
+
+![UnisolateMachine_Deploy_2](Images/UnisolateMachine_Deploy_2.png)
+
+The resources should take around a minute to deploy. Once the deployment is complete, you can expand the "**Deployment details**" section to view them.
+Click the one corresponding to the Logic App.
+
+![UnisolateMachine_Deploy_3](Images/UnisolateMachine_Deploy_3.png)
+
+
+#
+### Microsoft Sentinel Contributor Role
+
+After deployment, you will need to give the system assigned managed identity the "**Microsoft Sentinel Contributor**" role. This will enable it to add comments to incidents. Navigate to the Log Analytics Workspaces page and select the same workspace the playbook is located in:
+
+https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.OperationalInsights%2Fworkspaces
+
+Select the "**Access control (IAM)**" option from the menu blade, then click "**Add role assignment**".
+
+![UnisolateMachine_Add_Contributor_Role_1](Images/UnisolateMachine_Add_Contributor_Role_1.png)
+
+Select the "**Microsoft Sentinel Contributor**" role, then click "**Next**".
+
+![UnisolateMachine_Add_Contributor_Role_2](Images/UnisolateMachine_Add_Contributor_Role_2.png)
+
+Select the "**Managed identity**" option, then click "**Select Members**". Under the subscription the logic app is located, set the value of "**Managed identity**" to "**Logic app**". Next, enter "**AS-MDE-Unisolate-Machine**", or the alternative playbook name used during deployment, in the field labeled "**Select**". Select the playbook, then click "**Select**".
+
+![UnisolateMachine_Add_Contributor_Role_3](Images/UnisolateMachine_Add_Contributor_Role_3.png)
+
+Continue on to the "**Review + assign**" tab and click "**Review + assign**".
+
+![UnisolateMachine_Add_Contributor_Role_4](Images/UnisolateMachine_Add_Contributor_Role_4.png)
+
+
+#
+### Granting Access to Azure Key Vault
+
+Before the Logic App can run successfully, the key vault connection created during deployment must be granted access to the key vault storing your app registration client secret.
+
+From the key vault "**Access policies**" page, click "**Create**".
+
+![UnisolateMachine_Key_Vault_Access_1](Images/UnisolateMachine_Key_Vault_Access_1.png)
+
+Select the "**Get**" checkbox under "**Secret permissions**", then click "**Next**".
+
+![UnisolateMachine_Key_Vault_Access_2](Images/UnisolateMachine_Key_Vault_Access_2.png)
+
+Paste "**AS-MDE-Unisolate-Machine**" into the principal search box and click the option that appears. Click "**Next**" towards the bottom of the page.
+
+![UnisolateMachine_Key_Vault_Access_3](Images/UnisolateMachine_Key_Vault_Access_3.png)
+
+Navigate to the "**Review + create**" section and click "**Create**".
+
+![UnisolateMachine_Key_Vault_Access_4](Images/UnisolateMachine_Key_Vault_Access_4.png)

Playbooks/AS-MDE-Unisolate-Machine/azuredeploy.json

@@ -0,0 +1,335 @@
+{
+    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+    "contentVersion": "1.0.0.0",
+    "metadata": {
+        "title": "AS-MDE-Unisolate-Machine", 
+        "description": "This playbook is intended to be run from a Microsoft Sentinel Incident. It will match Microsoft Defender for Endpoint isolated machines with the host entities on the incident and then reslease them from isolation.",
+        "prerequisites": "1. An App Registraton with the Machine.Isolate must be created. 2. A Microsoft Azure key vault containing the app registration client secret must also be set up. Support for the set up and configuration of each of these items can be found here: https://github.com/Accelerynt-Security/AS-MDE-Unisolate-Machine",
+        "lastUpdateTime": "2024-02-08T14:29:33Z",
+        "entities": ["Host"], 
+        "tags": ["Microsoft Sentinel", "Incident", "Microsoft Defender", "Unisolate Machine"], 
+        "support": {
+            "tier": "developer"
+        },
+        "author": {
+            "name": "Accelerynt"
+        }
+    },
+    "parameters": {
+        "PlaybookName": {
+            "defaultValue": "AS-MDE-Unisolate-Machine",
+            "type": "string"
+        },
+        "ClientID": {
+            "type": "string",
+            "metadata" : {
+                "description" : "The client id of the app registration"
+            }
+        },
+        "KeyVaultName": {
+            "type": "string",
+            "metadata" : {
+                "description" : "Name of the Key Vault that stores the app registration client secret"
+            }
+        },
+        "KeyVaultSecretName": {
+            "type": "string",
+            "metadata": {
+                "description": "Name of Key Vault Secret that contains the value of the app registration client secret"
+            }
+        }
+    },
+    "variables": {
+        "azuresentinel": "[concat('azuresentinel-', parameters('PlaybookName'))]",
+        "keyvault": "[concat('keyvault-', parameters('PlaybookName'))]"
+    },
+    "resources": [
+        {
+            "type": "Microsoft.Web/connections",
+            "apiVersion": "2016-06-01",
+            "name": "[variables('azuresentinel')]",
+            "location": "[resourceGroup().location]",
+            "kind": "V1",
+            "properties": {
+                "displayName": "[parameters('PlaybookName')]",
+                "customParameterValues": {},
+                "parameterValueType": "Alternative",
+                "api": {
+                    "id": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Web/locations/', resourceGroup().location, '/managedApis/azuresentinel')]"
+                }
+            }
+        },
+        {
+            "type": "Microsoft.Web/connections",
+            "apiVersion": "2016-06-01",
+            "name": "[variables('keyvault')]",
+            "location": "[resourceGroup().location]",
+            "properties": {
+                "displayName": "[parameters('PlaybookName')]",
+                "parameterValueType": "Alternative",
+                "alternativeParameterValues": {
+                    "vaultName": "[parameters('KeyVaultName')]"
+                },
+                "customParameterValues": {
+                },
+                "api": {
+                    "id": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Web/locations/', resourceGroup().location, '/managedApis/keyvault')]"
+                }
+            }
+        },
+        {
+            "type": "Microsoft.Logic/workflows",
+            "apiVersion": "2017-07-01",
+            "name": "[parameters('PlaybookName')]",
+            "location": "[resourceGroup().location]",
+            "tags": {
+                "LogicAppsCategory": "security"
+            },
+            "identity": {
+                "type": "SystemAssigned"
+            },
+            "dependsOn": [
+                "[resourceId('Microsoft.Web/connections', variables('azuresentinel'))]",
+                "[resourceId('Microsoft.Web/connections', variables('keyvault'))]"
+            ],
+            "properties": {
+                "state": "Enabled",
+                "definition": {
+                    "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
+                    "contentVersion": "1.0.0.0",
+                    "parameters": {
+                        "$connections": {
+                            "defaultValue": {},
+                            "type": "Object"
+                        }
+                    },
+                    "triggers": {
+                        "Microsoft_Sentinel_incident": {
+                            "inputs": {
+                                "body": {
+                                    "callback_url": "@{listCallbackUrl()}"
+                                },
+                                "host": {
+                                    "connection": {
+                                        "name": "@parameters('$connections')['azuresentinel']['connectionId']"
+                                    }
+                                },
+                                "path": "/incident-creation"
+                            },
+                            "type": "ApiConnectionWebhook"
+                        }
+                    },
+                    "actions": {
+                        "Add_comment_to_incident_(V3)": {
+                            "inputs": {
+                                "body": {
+                                    "incidentArmId": "@triggerBody()?['object']?['id']",
+                                    "message": "<p>@{variables('Affected Hosts')}</p>"
+                                },
+                                "host": {
+                                    "connection": {
+                                        "name": "@parameters('$connections')['azuresentinel']['connectionId']"
+                                    }
+                                },
+                                "method": "post",
+                                "path": "/Incidents/Comment"
+                            },
+                            "runAfter": {
+                                "For_each_-_Host": [
+                                    "Succeeded"
+                                ]
+                            },
+                            "type": "ApiConnection"
+                        },
+                        "Entities_-_Get_Hosts": {
+                            "inputs": {
+                                "body": "@triggerBody()?['object']?['properties']?['relatedEntities']",
+                                "host": {
+                                    "connection": {
+                                        "name": "@parameters('$connections')['azuresentinel']['connectionId']"
+                                    }
+                                },
+                                "method": "post",
+                                "path": "/entities/host"
+                            },
+                            "runAfter": {},
+                            "type": "ApiConnection"
+                        },
+                        "For_each_-_Host": {
+                            "actions": {
+                                "Condition_-_Check_for_MDE_Device_ID": {
+                                    "actions": {
+                                        "Append_to_string_variable_-_Machine_Unisolated": {
+                                            "inputs": {
+                                                "name": "Affected Hosts",
+                                                "value": "Successfully unisolated @{items('For_each_-_Host')?['HostName']} in MDE\n"
+                                            },
+                                            "runAfter": {
+                                                "HTTP_-_Unisolate_Machine": [
+                                                    "Succeeded"
+                                                ]
+                                            },
+                                            "type": "AppendToStringVariable"
+                                        },
+                                        "HTTP_-_Unisolate_Machine": {
+                                            "inputs": {
+                                                "body": {
+                                                    "Comment": "Unisolated by playbook run from Incident: @{triggerBody()?['object']?['properties']?['incidentNumber']}"
+                                                },
+                                                "headers": {
+                                                    "Authorization": "Bearer @{body('Parse_JSON_-_Token')?['access_token']}"
+                                                },
+                                                "method": "POST",
+                                                "uri": "https://api.securitycenter.microsoft.com/api/machines/@{items('For_each_-_Host')?['additionalData']?['MdatpDeviceId']}/unisolate"
+                                            },
+                                            "runAfter": {},
+                                            "type": "Http"
+                                        }
+                                    },
+                                    "else": {
+                                        "actions": {
+                                            "Append_to_string_variable_-_Unable_to_Unisolate_Machine": {
+                                                "inputs": {
+                                                    "name": "Affected Hosts",
+                                                    "value": "No MDE Device ID was found for @{items('For_each_-_Host')?['HostName']}\n"
+                                                },
+                                                "runAfter": {},
+                                                "type": "AppendToStringVariable"
+                                            }
+                                        }
+                                    },
+                                    "expression": {
+                                        "and": [
+                                            {
+                                                "not": {
+                                                    "equals": [
+                                                        "@items('For_each_-_Host')?['additionalData']?['MdatpDeviceId']",
+                                                        ""
+                                                    ]
+                                                }
+                                            }
+                                        ]
+                                    },
+                                    "runAfter": {},
+                                    "type": "If"
+                                }
+                            },
+                            "foreach": "@body('Entities_-_Get_Hosts')?['Hosts']",
+                            "runAfter": {
+                                "Initialize_variable_-_Affected_Hosts": [
+                                    "Succeeded"
+                                ]
+                            },
+                            "type": "Foreach"
+                        },
+                        "Get_Client_Secret": {
+                            "inputs": {
+                                "host": {
+                                    "connection": {
+                                        "name": "@parameters('$connections')['keyvault']['connectionId']"
+                                    }
+                                },
+                                "method": "get",
+                                "path": "[concat('/secrets/@{encodeURIComponent(''', parameters('KeyVaultSecretName'), ''')}/value')]"
+                            },
+                            "runAfter": {
+                                "Entities_-_Get_Hosts": [
+                                    "Succeeded"
+                                ]
+                            },
+                            "type": "ApiConnection"
+                        },
+                        "HTTP_-_Authenticate": {
+                            "inputs": {
+                                "body": "[concat('grant_type=client_credentials&client_id=', parameters('ClientID'),'&client_secret=@{body(''Get_Client_Secret'')?[''value'']}&scope=https://api.securitycenter.microsoft.com/.default')]",
+                                "headers": {
+                                    "Content-Type": "application/x-www-form-urlencoded",
+                                    "Host": "login.microsoftonline.com"
+                                },
+                                "method": "POST",
+                                "uri": "[concat('https://login.microsoftonline.com/', subscription().tenantId, '/oauth2/v2.0/token')]"
+                            },
+                            "runAfter": {
+                                "Get_Client_Secret": [
+                                    "Succeeded"
+                                ]
+                            },
+                            "type": "Http"
+                        },
+                        "Initialize_variable_-_Affected_Hosts": {
+                            "inputs": {
+                                "variables": [
+                                    {
+                                        "name": "Affected Hosts",
+                                        "type": "string"
+                                    }
+                                ]
+                            },
+                            "runAfter": {
+                                "Parse_JSON_-_Token": [
+                                    "Succeeded"
+                                ]
+                            },
+                            "type": "InitializeVariable"
+                        },
+                        "Parse_JSON_-_Token": {
+                            "inputs": {
+                                "content": "@body('HTTP_-_Authenticate')",
+                                "schema": {
+                                    "properties": {
+                                        "access_token": {
+                                            "type": "string"
+                                        },
+                                        "expires_in": {
+                                            "type": "integer"
+                                        },
+                                        "ext_expires_in": {
+                                            "type": "integer"
+                                        },
+                                        "token_type": {
+                                            "type": "string"
+                                        }
+                                    },
+                                    "type": "object"
+                                }
+                            },
+                            "runAfter": {
+                                "HTTP_-_Authenticate": [
+                                    "Succeeded"
+                                ]
+                            },
+                            "type": "ParseJson"
+                        }
+                    },
+                    "outputs": {}
+                },
+                "parameters": {
+                    "$connections": {
+                        "value": {
+                            "azuresentinel": {
+                                "connectionId": "[resourceId('Microsoft.Web/connections', variables('azuresentinel'))]",
+                                "connectionName": "[variables('azuresentinel')]",
+                                "id": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Web/locations/', resourceGroup().location, '/managedApis/azuresentinel')]",
+                                "connectionProperties": {
+                                    "authentication": {
+                                        "type": "ManagedServiceIdentity"
+                                    }
+                                }
+                            },
+                            "keyvault": {
+                                "connectionId": "[resourceId('Microsoft.Web/connections', variables('keyvault'))]",
+                                "connectionName": "[variables('keyvault')]",
+                                "id": "[concat('/subscriptions/', subscription().subscriptionId,'/providers/Microsoft.Web/locations/', resourceGroup().location, '/managedApis/keyvault')]",
+                                "connectionProperties": {
+                                    "authentication": {
+                                        "type": "ManagedServiceIdentity"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    ]
+}