diff --git a/Docs/authentication.md b/Docs/authentication.md index ad43ef9..6ed5b9e 100644 --- a/Docs/authentication.md +++ b/Docs/authentication.md @@ -1,75 +1,4 @@ # Sentinel Triage AssistanT (STAT) :hospital: - Authentication > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) - -The Microsoft Sentinel Triage AssistanT (STAT) makes use of multiple APIs such as the Microsoft Graph, Azure Resource Manager, Microsoft 365 Defender and more. To access these APIs, the STAT function must authenticate against these services. - -Multiple methods of authentication are supported by STAT and each of these methods requires different configuration on the STAT Function. This configuration is typically deployed automatically during the STAT deployment, however it can be changed post deployment. - -The type of identity used is determined the by the presence of Application Settings found under the Configuration menu of the STAT Function App. - -## Authentication Types - -### System Assigned Managed Identity - -Using a system assigned managed identity is the default and recommend method to deploy STAT for most scenarios. We recommend this approach because there is no need for the manual management of secrets, and the access given to STAT's identity can't be shared by other services running in the Azure tenant. - -|Required Application Setting|Description| -|---|---| -|AZURE_TENANT_ID|The Azure AD Tenant GUID associated with the Azure subscription where the function resides| - -> The presence of either of the following additional application settings may result in a different authentication method being selected: AZURE_CLIENT_ID or KEYVAULT_ENDPOINT - -### User Assigned Managed Identity - -Like a system assigned managed identity, with a user assigned managed there is no need for manual management of secrets. The main difference with this identity type is that it can be shared across multiple services, giving those services the same access rights. - -|Required Application Setting|Description| -|---|---| -|AZURE_TENANT_ID|The Azure AD Tenant GUID associated with the Azure subscription where the function resides| -|AZURE_CLIENT_ID|The Client ID GUID of the associated User Assigned Managed identity| - -> The presence of either of the following additional application settings may result in a different authentication method being selected: AZURE_CLIENT_SECRET or KEYVAULT_ENDPOINT - -### Service Principal - -Using a Service Principal requires the administrators to manually manage and rotate the associated secrets, so it should be used only when necessary. One scenario where this authentication method is necessary is multi-tenant environments such as for MSSP organizations. - -|Required Application Setting|Description| -|---|---| -|AZURE_TENANT_ID|The Azure AD Tenant GUID associated with the Azure subscription where the function resides| -|AZURE_CLIENT_ID|The Client ID GUID of the selected Service Principal| -|AZURE_CLIENT_SECRET|A valid secret for the Service Principal identified in the AZURE_CLIENT_ID| - -> The presence of the following additional application setting may result in a different authentication method being selected: KEYVAULT_ENDPOINT - -### Service Principal with Key Vault Secret Storage - -When using Service Principal authentication, you may wish to further protect the secret using Azure Key Vault. To use Azure Key Vault you must first: - -1. Provision your own Azure Key Vault -2. Determine how you want to authenticate against that Key Vault (System Assigned Managed Identity or User Assigned Managed Identity) -3. Grant the selected identity access to the key vault via an access policy to retrieve secrets -4. Store the Service Principal Secret in the key vault -5. Manually configure STAT to use Key Vault via the STAT Function -> Configuration -> Application Settings - -|Required Application Setting|Required|Description| -|---|---|---| -|AZURE_TENANT_ID|Yes|The Azure AD Tenant GUID associated with the Azure subscription where the function resides| -|AZURE_CLIENT_ID|No|The Client ID GUID of the User Assigned Managed Identity if using User Assigned Managed Identity to access Key Vault| -|KEYVAULT_ENDPOINT|Yes|The FQDN of the Keyvault containing the secret (Example: contoso.vault.azure.net)| -|KEYVAULT_SECRET_NAME|Yes|The name of the stored secret in Key Vault| -|KEYVAULT_CLIENT_ID|Yes|The Service Principal Client ID GUID associated with the secret stored in Key Vault| - -## Authentication Precedence - -If the configured application settings match with multiple authentication methods, the authentication method used with be selected in this order: - -1. Service Principal with Key Vault Secret Storage -2. Service Principal -3. User Assigned Managed Identity -4. System Assigned Managed Identity - ---- -[Documentation Home](readme.md) +> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Authentication) diff --git a/Docs/deployment.md b/Docs/deployment.md index 6c58f9c..d5f25e5 100644 --- a/Docs/deployment.md +++ b/Docs/deployment.md @@ -1,94 +1,4 @@ # Sentinel Triage AssistanT (STAT) :hospital: - Deployment > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) - -The deployment of the STAT solution is broken down into 2 steps: - -1. Deploying Azure Resources -2. Granting Permissions - -## Deploying Azure Resources - -The first step to deploying STAT is to deploy the STAT components into a Resource Group in your Azure subscription. These components consist of an Azure Function, API Connections and a Custom Logic Apps Connector. While seperate ARM templates exist for components of the STAT solution, it should be deployed through the single ARM template available below. - -Consider the permissions on the Resource Group where you deploy STAT and ensure that no unauthorized users have access to the resources. Since these resources will contain information about security incidents that have been analyzed which may contain private or sensitive information. - -When deploying STAT you should use a Resource Group within the same subscription and datacenter region as your other Microsoft Sentinel automation Playbooks. Logic Apps Custom Connectors can only be used from the same subscription and datacenter as they are created in. If multiple subscriptions or datacenters must be used, STAT can be deployed to each one. - -STAT can be deployed/updated via single ARM deployment - -### Deployment Template - -[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fbriandelmsft%2FSentinelAutomationModules%2Fstatv2_preview%2FDeploy%2Fstatdeploy.json/createUIDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2Fbriandelmsft%2FSentinelAutomationModules%2Fstatv2_preview%2FDeploy%2Fdeployui.json) - -## Identity Configuration - -STAT can be deployed using any of the following identity types - -* System Assigned Managed Identity -* User Assigned Managed Identity -* Service Principal Identity - -See [authentication](authentication.md) for more information on configuring these authentication methods. - -For MSSPs or other Multi Tenant environments, you will need to deploy STAT using a Multi Tenant Service Principal Identity if you wish to centrally run your automation. For Single Tenant use, we recommend using a System Assigned Managed Identity, but any other supported identity type will work in a single tenant deployment. - -## Post Deloyment - -After the STAT template is deployed it will need to be granted permissions to various APIs and Sentinel itself to operate. - -### Grant Permissions - -To grant permissions to STAT, use the PowerShell script [GrantPermissions.ps1](/Deploy/GrantPermissions.ps1). - -The following modifications will need to be made to the script - -* Set the $TenantID to your [tenant id](https://docs.microsoft.com/azure/active-directory/fundamentals/active-directory-how-to-find-tenant) -* Set the $AzureSubscriptionId to the Azure Subscription GUID of the **Microsoft Sentinel** subscription -* Set the $SentinelResourceGroupName to the Resource Group Name where **Microsoft Sentinel** resides -* Set the $STATIdentityName to the name of the identity you deployed STAT using. If using a System assigned managed identity, this will be the name of the Azure Function app - - -The GrantPermissions.ps1 script contains 2 types of permissions assignments that are set via PowerShell Functions. To execute these functions you will require permission: - -|Function|Permissions| -|---|---| -|Set-APIPermissions|Calls to this function require the user to be either an Azure AD Global Administrator or Azure AD Privileged Role Administrator| -|Set-RBACPermissions|Calls to this function require the user to be either a Resource Group Owner or User Access Administrator on the Resource Group where Microsoft Sentinel is installed| - -> If you do not have a single account with both the necessary Azure AD and Resource group permissions, you can run the Set-APIPermissions and Set-RBACPermissions calls seperately under different accounts. - -STAT Uses the following permissions - -|Permission|Type|Description| -|---|---|---| -|Data.Read|Log Analytics API|Execute KQL queries against your Log Analytics workspace| -|Directory.Read.All|Microsoft Graph API|Read Azure AD data in the Microsoft Graph to resolve/enrich entities| -|MailboxSettings.Read|Mirosoft Graph API|Read users Out of Office settings| -|RoleManagement.Read.Directory|Microsoft Graph API|Read privileged role information to enrich user data| -|IdentityRiskyUser.Read.All|Microsoft Graph API|Read user risk information from Azure AD Identity Protection| -|AdvancedQuery.Read.All|Microsoft Defender for Endpoint API|Query MDE data| -|Machine.Read.All|Microsoft Defender for Endpoint API|Retrieve Machine inforamtion including risk level| -|File.Read.All|Microsoft Defender for Endpoint API|Retrieve file information including known threats and GlobalPrevalence| -|investigation.read|Microsoft Defender for Cloud Apps API|Retrieve user investigation priorities| -|AdvancedHunting.Read.All|Microsoft 365 Security API|Execute KQL queries against the Microsoft 365 Security service| -|Microsoft Sentinel Responder|Azure RBAC Role|Gives permissions to update incidents and read data from Sentinel. This is typically used by STAT to add comments to incidents.| - -### Restrict Calls to STAT Coordinator (optional) - -All STAT modules, except the STAT Coordinator, are restricted to only being called from a Logic Apps IP and with a valid Shared Access Signature. However, by default the STAT coordinator is only protected by the Shared Access Signature. This is due to the Logic Apps Custom connector using IP addresses outside of the standard Logic Apps IP ranges. - -To restrict the STAT coordinator to only accept calls from the Logic apps custom connector: -1. Locate the appropriate IP ranges for your Azure datacenter region [here](https://www.microsoft.com/download/details.aspx?id=56519) under the section **AzureConnectors.<AzureRegion>** -2. Navigate in the Azure Portal to the **STAT-Coordinator** logic app -3. Locate **Settings -> Workflow settings** -4. Change the drop down menu from **Any IP** to **Specific IP ranges** -5. Add the IP ranges obtained in step 1 -6. **Save** - -> Note: To maintain these IP restrictions, these steps will need to be repeated when updating the STAT solution. - - ---- -[Documentation Home](readme.md) +> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Deployment) diff --git a/Docs/howitworks.md b/Docs/howitworks.md index 373f766..fba5a33 100644 --- a/Docs/howitworks.md +++ b/Docs/howitworks.md @@ -1,35 +1,4 @@ # Sentinel Triage AssistanT (STAT) :hospital: - How it Works > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) - -The Sentinel Triage AssistanT consists of 3 components - -* Sentinel Playbook (Logic App) -* Logic Apps Custom Connector -* STAT Function - -## Sentinel Playbook (Logic App) - -When a Sentinel incidient is created that requires triage, a Sentinel Playbook will be started using an [automation rule](https://docs.microsoft.com/azure/sentinel/automate-incident-handling-with-automation-rules). This playbook will start with a Sentinel Incident trigger and be used to call the Sentinel Triage AssistanT through the Logic Apps Custom Connector. Once the triage information is receieved from STAT, this Playbook can then determine the outcome of the incident. - -Here is a high level view of the information flow using STAT: - -![STAT Information Flow](images/statoverview.png) - -## Logic Apps Custom Connector - -The Logic Apps Custom Connector (STAT Connector) serves as the user interface of STAT. All automations built on the STAT platform will use this custom connector to retrieve relevant information about the incident or alert and return that information into the Sentinel Playbook for a determination to be made. The STAT Connector works in a similar way to built-in Logic App connectors so if you already have experience with Logic Apps this will be a familiar interface. - -## STAT Function - -Today a series of 13 modules have been released for STAT. These modules also operate behind the scenes but it is important to understand their capabilites to make the best use of the solution. Each module is responsible for getting specfic insights into the entities associated with the incident or alert and returning those insights in a easy to use format back to the STAT Connector. - -When using STAT, the first module you should call from the STAT Connector is the Base Module. The Base Module performs some enrichment activities to prepare the incident data for the rest of the STAT solution. All other modules will require inputs from this Base module so they should be called after the Base Module has processed the incident data. - -An example of the use of multiple modules can be found in the [Sample](sample.md) playbook included during the deployment. - -More information about the automation modules can be located within the [Modules](/Modules/) folders. - ---- -[Documentation Home](readme.md) +> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki#how-it-works) diff --git a/Docs/incidenttasks.md b/Docs/incidenttasks.md index cb9af48..c976dc3 100644 --- a/Docs/incidenttasks.md +++ b/Docs/incidenttasks.md @@ -1,20 +1,4 @@ # Sentinel Triage AssistanT (STAT) :hospital: - Incident Tasks (Preview) > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) - -Microsoft Sentinel now supports the addition of [tasks](https://learn.microsoft.com/azure/sentinel/work-with-tasks) to incidents. Tasks have a more prominent place in the incident interface than comments do so it can help draw attention to important steps for an analyst to follow. - -STAT now has support to add incident tasks to the corresponding incident. - -Tasks will only be added if there is a finding from STAT. For example, if the KQL module is used and no records are found based on your search, no task will be added to the incident. - -To use the Incident Tasks feature, when adding a supported module to your Logic app, select the *Add new parameter* option and check off *AddIncidentTask* and *IncidentTaskInstructions*. - -|Setting|Description| -|---|---| -|AddIncidentTask|When true, an incident task will be added if this module finds any relevant data| -|IncidentTaskInstructions|The instructions placed here will be added to the incident task for your analyst to review| - ---- -[Documentation Home](readme.md) \ No newline at end of file +> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Modules#incident-tasks) diff --git a/Docs/mssp.md b/Docs/mssp.md index db95394..8ae5692 100644 --- a/Docs/mssp.md +++ b/Docs/mssp.md @@ -1,58 +1,4 @@ # Sentinel Triage AssistanT (STAT) :hospital: - MSSP / Multi Tenant Deployments > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) - -With the introduction of STAT v2 we have added support for Multi Tenant Service Principal Authentication to enable MSSP and other organizations with multiple tenants to run STAT in a centralized location, while accessing services in another Azure Ad tenant. - -## Prerequisites - -* Create a Multi tenant Service Principal in the central tenant -* Run the GrantPermissions.ps1 against this service principal -* Grant consent in the customer/other tenants to this Service Principal -* Deploy STAT v2 (Preview build 1.5.0 or later) using the Service Principal as the Identity type during the deployment - -## Identify the AAD tenant to run STAT against - -By default STAT will execute its API calls against the tenant where it is installed. However, if you are using Azure Lighthouse to execute a logic app in your MSSP tenant from a customer tenant you will need to add some additional configuration. You, must come up with a way to identify the source tenant of the incident such that you can pass the tenant id to STAT. This could be accomplished by a watchlist in your source tenant, which looks up the workspace id or subscription id against a watchlist to determine the originating tenant, or it could be done through any other means. Ultimately, STAT cannot make the determination of which tenant to execute against, so you will need to provide this information. Additionally, to use the MDCA module you will also be able to lookup the customers MDCA API endpoint and provide this information as well. This can be stored and looked up in a similiar fashion as the tenant id. - -## Provide AAD Tenant Details to STAT - -The Base Module has a new optional parameter called *MultiTenantConfig*. In a multi tenant configuration, this parameter will need to be passed to the base module. The parameter is expecting a JSON object containing the multi tenant configuration. - -### Example 1 - All APIs are located in the Customer Tenant / STAT Deployed in MSSP Tenant - -```json -{ - "TenantId": "CustomerTenantGUID", - "MDCAUrl": "customer.region.portal.cloudappsecurity.com" -} -``` - -### Example 2 - The Sentinel Incidents and STAT are in MSSP Tenant / All other data in the Customer Tenant - -```json -{ - "ARMTenantId": "MSSPTenantGUID", - "TenantId": "CustomerTenantGUID", - "MDCAUrl": "customer.region.portal.cloudappsecurity.com" -} -``` - -## Advanced Configuration - -STAT v2 allows for an API by API level of control against which tenant the authentication occurs, so for other scenarios you can customize this further. To do so, the *MultiTenantConfig* accepts all of these properties. - -|Property|Description| -|---|---| -|TenantId|The default tenant id to use for any APIs not explicitly specified. Setting a service specific tenant id overrides this value for that service.| -|ARMTenantId|The tenant id to use when accessing the Azure Resource Manager API. This API is primarily used for updating incidents.| -|MSGraphTenantId|The tenant id to use when accessing the Microsoft Graph API.| -|LogAnalyticsTenantId|The tenant id to use when access the Log Analytics API to run KQL queries.| -|M365DTenantId|The tenant id to use when accessing Microsoft 365 Defender APIs| -|MDETenantId|The tenant id to use when accessing Microsoft Defender for Endpoint APIs| -|MDCAUrl|The tenant specific API endpoint to use when accessing MDCA (MDCA module only). Do not include *https://*| - - ---- -[Documentation Home](readme.md) +> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki/MSSP) diff --git a/Docs/readme.md b/Docs/readme.md index adaae14..cd143f1 100644 --- a/Docs/readme.md +++ b/Docs/readme.md @@ -1,9 +1,9 @@ # Microsoft Sentinel Triage AssistanT (STAT) :hospital: - Documentation Home > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) +> STAT documentation is located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki). -The Microsoft Sentinel Triage AssistanT (STAT) is a Logic Apps Custom Connector that calls on a library of Automation [Modules](/Modules/) that can be used from Incident or alert based Microsoft Sentinel playbooks. This connector and modules will simplify automation by moving the complex tasks into these callable modules so they can be performed consistently and with ease from the Logic Apps Connector. +The Microsoft Sentinel Triage AssistanT (STAT) is a Logic Apps Custom Connector that calls on a library of Automation [Modules](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Modules#modules) that can be used from Incident or alert based Microsoft Sentinel playbooks. This connector and modules will simplify automation by moving the complex tasks into these callable modules so they can be performed consistently and with ease from the Logic Apps Connector. The primary focus of these modules is to perform automated incident triage. An incident triage takes an incoming incident and assesses it based on the criteria you choose to determine which further actions should be taken. @@ -11,12 +11,12 @@ Take for example an impossible travel incident, while this incident could repres ## Learn more -* [How it works](howitworks.md) -* [Deployment](deployment.md) -* [Sample Playbook](sample.md) -* [Risk Scoring](riskscoring.md) -* [Incident Tasks](incidenttasks.md) -* [Remediation](remediation.md) -* [Authentication](authentication.md) -* [MSSP Deployments](mssp.md) -* [Troubleshooting](troubleshooting.md) +* [How it works](https://github.com/briandelmsft/SentinelAutomationModules/wiki#how-it-works) +* [Deployment](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Deployment) +* [Sample Playbook](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Examples#sample-playbook-logic) +* [Risk Scoring](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Examples#risk-scoring-example) +* [Incident Tasks](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Modules#incident-tasks) +* [Remediation](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Examples#triggering-a-remediation-playbook-on-stat-output) +* [Authentication](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Authentication) +* [MSSP Deployments](https://github.com/briandelmsft/SentinelAutomationModules/wiki/MSSP) +* [Troubleshooting](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Troubleshooting-%E2%80%90-Common-Errors) diff --git a/Docs/remediation.md b/Docs/remediation.md index 5bbe291..a1cba8f 100644 --- a/Docs/remediation.md +++ b/Docs/remediation.md @@ -1,45 +1,4 @@ # Sentinel Triage AssistanT (STAT) :hospital: - Remediation > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) - -Once you have used STAT to triage your incident and make a decision on the remediation actions you want to take, you may notice that STAT does not include any remediation actions. This is because many common remediation action Playbooks have already been built in the [Sentinel Github repo](https://github.com/Azure/Azure-Sentinel/tree/master/Playbooks). Since STAT is encouraging reusable automation, it didn't make sense at this time to incorporate remediation directly into STAT. However, that doesn't mean they can't work together. - -## Triggering a Remediation Playbook on STAT Output - -Let's say you want to use the [Confirm-AADRiskyUser](https://github.com/Azure/Azure-Sentinel/tree/master/Playbooks/Confirm-AADRiskyUser) playbook on an incident that STAT has triaged as a high risk. How can I run this playbook? - -There's actually 3 common ways to accomplish this: - -* Run Playbook Module -* Run Playbook API -* Incident Tags and Automation Rules - -### Run Playbook Module - -The easiest way to perform an automated remediation playbook based on a STAT triage is to use the Run Playbook STAT Module. This module allows for you to initiate another automation Playbook using an incident trigger on the incident you are triaging. More information on calling this module can be found [here](/Modules/RunPlaybook/readme.md). - - -### Run Playbook API - -Microsoft Sentinel has an API endpoint that allows for the running of a playbook on an incident. In this approach, you would use that API endpoint to trigger the Confirm-AADRiskUser playbook - -[Incidents - Run Playbook API Documentation](https://docs.microsoft.com/rest/api/securityinsights/preview/incidents/run-playbook) - -> The Run Playbook Module uses this API, but simplifies the inputs and authentication needed to call it. - -### Incident Tags and Automation Rules - -In this approach, you will configure the STAT playbook to tag the incident where you want to run the playbook, and an automation rule to execute the playbook if the Tag is present. - -1. In your STAT triage playbook add a Sentinel\Update Incident action to the part of your playbook where a high risk has been determined -2. In that Update incident action, set a tag on the incident such as 'ConfirmRiskyUser' -3. Create a new automation rule that runs after (higher Order #) the STAT triage Playbook which runs the Confirm-AADRiskyUser Playbook -4. Set a Condition on the automation rule for Tag Contains 'ConfirmRiskyUser' - -With this configuration the STAT playbook will run first, determine if a the remediation action is needed, and then only if the tag has been added will the remeidation action take place. - -![Automation Rule Sample](images/remediation.jpg) - ---- -[Documentation Home](readme.md) +> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Examples#triggering-a-remediation-playbook-on-stat-output) diff --git a/Docs/riskscoring.md b/Docs/riskscoring.md index 95dbb6e..213a611 100644 --- a/Docs/riskscoring.md +++ b/Docs/riskscoring.md @@ -1,89 +1,4 @@ # Sentinel Triage AssistanT (STAT) :hospital: - Risk Scoring > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) - -Risk Scoring is a module of STAT that can be used to calculate a cumulative risk score based on the findings of multiple STAT modules. The Risk Scoring module can consume the output *Body* of multiple STAT modules, and will calculate a simple numeric score based on what those modules have found. Its purpose is to make it easier to make a decision based on the cumulative risk associated with an incident. - -## Supported Modules - -The Risk Scoring module accepts the *Body* output of the following modules as an input: - -* AAD Risks Module -* Microsoft Defender for Endpoint Module -* Related Alerts Module -* KQL Module -* Threat Intelligence Module -* Watchlist Module -* User Entity Behavior Analytics Module -* File Module -* Microsoft Defender for Cloud Apps Module -* Custom Content Scoring - -## Risk Scoring Example - -For this example let's assume you want to make a decision based on the related alerts to an incident. While the Related Alerts module will return information about the amount of alerts, the severity of the alerts and other properties influence the risk of the incident. Without a risk score, it is difficult to analyze these properties in automation. For example, if there are multiple related high risk alerts you may wish to handle that differently than if there are multiple low or information risk alerts. - -Passing the Related Alerts *Body* through the risk scoring module will return a simple cumulative score based on the number of alerts and severity of each alert. So instead of applying multiple conditions based on the number of alerts and severity of alerts, you can evaluate a simple condition such as TotalScore > 20. - -> Note: While this is useful for a module like Related alerts on its own, the Risk Scoring module provides even greater value as it can combine the risk scores from other modules such as Threat Intel, Watchlist and KQL into a single score that can be easily evaluated. - -Without the Risk Scoring Module a triage Logic app would look something like this: - -![STAT Information Flow without Scoring](images/relatedalerts.jpg) - -With risk scoring added: - -![STAT Information Flow with Scoring](images/riskscoring.jpg) - -## Risk Scoring Inputs - -|Input|Expected Values|Description| -|---|---|---| -|AddIncidentComments|True/False (Default:True)|When set to true, the results of the scoring module will be added to the Sentinel Incident Comments| -|Base Module Body|Body (dynamic content)|The Body should be selected from the Dynamic content of the Base-Module response| -|ScoringData-ModuleBody|Body (dynamic content)|The *Body* of a supported module you want to score| -|ScoringData-ScoreMultiplier|Decimal value (1 for default scoring)|Default scores will be multiplied by this value, this can be a negative value which will result in the cummulative score being reduced| -|ScoreingData-ScorePerItem|true/false|true if you want to score the input on a row level (per alert or record)| - -The ScoringData may be provided multiple times, for each module you wish to be included in the risk score. For example, if you want to evaluate Related Alerts and 2 custom KQL queries, you would provide 3 sets of Scoring data. - -![Risk Scoring Input Sample](images/riskscoringsample.jpg) - -## Risk Scoring Outputs - -The return from the risk scoring module includes a TotalScore which can be easily evaluated in Condition or Switch statements inside your Logic App. Additionally, a DetailedResults array is returned indicated the modules that contributed to the risk score. - -### Sample Return - -``` -{ - "DetailedResults": [ - { - "Score": 25, - "ScoreSource": "Bad Password KQL Query" - }, - { - "Score": 10, - "ScoreSource": "Related Alerts - Initial Access Incident" - }, - { - "Score": 5, - "ScoreSource": "Related Alerts - Multiple Password changes" - }, - { - "Score": -10, - "ScoreSource": "Watchlist - Check for Trusted IP Location" - } - ], - "TotalScore": 30 -} -``` - -## More information - -For more information on how the scores are calculated for each module, please see the [Module Page](/Modules/ScoringModule/readme.md). - - ---- -[Documentation Home](readme.md) +> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Examples#risk-scoring-example) diff --git a/Docs/sample.md b/Docs/sample.md index 89add20..67b6864 100644 --- a/Docs/sample.md +++ b/Docs/sample.md @@ -1,35 +1,4 @@ # Sentinel Triage AssistanT (STAT) :hospital: - Sample Playbook > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) - -The Sample playbook is a Proof of Concept to demonstrate how STAT can be used to Triage an incident. This sample is not meant to be capable of triaging any type of incident; additional playbooks may need to be built using STAT to handle the unique requirements of different incident types. - -The Playbook starts on a Sentinel Incident creation rule trigger and then starts the triage process using STAT: - -## Sample Playbook Logic - -1. The STAT Base Module is called using the STAT Connector to enrich and prepare the entity data for the STAT Solution -2. In parallel, the AAD Risks Module, Related Alerts Module and Threat Intel Module are called - * The AAD Risks Module is configured to pass the Base Module response, and lookback 30 days in the Sentinel data for any MFA Fraud reports related to the entities in the triggering incident - * The Related Alerts Module is configured to pass the Base Module response and check for any Related Sentinel alerts based on matching Account, Host or IP entity data in the last 30 days - * The Threat Intel Module is configured to pass the Base module response and check for any Related Sentinel Threat Intelligence in the last 30 days based on matching - Domain, FileHash, IP, and URL entity data -3. The Scoring module is then executed using the inputs of the Base, AAD Risks, Related Alerts and Threat Intel modules to determine a risk score for the incident -3. A Condition is then evaluated on the calculated risk score to determine if it is greater than or equal to 40 - * If it is, the Incident severity is raised and a tag is added with the Triage result - * If not, the Incident severity is lowered and a tag is added with the Triage result - -## Sample Screenshot - -![Screenshot of Logic Apps designer](images/sampletriage.png) - -## Adding Additional STAT Modules - -The sample playbook only makes use of a few of the STAT modules available to you. To add additional STAT modules to this, or other playbooks you can add additional actions. When adding a new action, select the Custom tab. Typically you will see the Sentinel Triage AssistanT right away, but if you have other custom connectors and you cannot locate it, search for Sentinel Triage or STAT to narrow your results. - -![STAT Connector View](images/statconnector.jpg) - - ---- -[Documentation Home](readme.md) \ No newline at end of file +> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Examples#sample-playbook-logic) diff --git a/Docs/troubleshooting.md b/Docs/troubleshooting.md index 1f5a222..8e005ad 100644 --- a/Docs/troubleshooting.md +++ b/Docs/troubleshooting.md @@ -1,68 +1,4 @@ # Sentinel Triage AssistanT (STAT) :hospital: - Troubleshooting > [!NOTE] -> STAT documentation is being relocated to the builin [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki) - -You will find here the troubleshooting steps for specific situations. - -## A module is failing with a 40x error message - -This can happen in the following situations: -- You did not run the `GrantPermissions.ps1` to grant the RBAC roles and application permissions. -- You used the modules at least once before executing the `GrantPermissions.ps1` script. The modules are all using [system-assigned managed identity](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview). When managed identities are used through logic apps, they are caching access tokens. If you run the permission script after you already cached a token, it might take up to an hour for managed identity to refresh its token. - -## STAT Logic App Connector prompts for a Function Code - -When creating a Logic App in a resource group other than the RG where STAT was deployed, you will be prompted to provide a connection name and a function code. Connection name is just a descriptive name and could be set to almost any value. The Function code must be obtained from the STAT Function app and entered in the Function Code text box. - -#### Obtaining the Function Code - -1. In the Azure Portal go into the Resource Group where the STAT Function app was deployed -2. Click on the STAT Function App -3. Navigate to Functions -> modules -4. Click the **Get Function Url** button -5. Copy the function code from the end of the URL. The code starts immediately after **?code=** - -## Microsoft Defender for Cloud Apps fails with *There is no configured endpoint for MDCA* - -This module needs the API endpoint of your Microsoft Defender for Cloud Apps tenant. If this was not entered, or entered incorrectly, during the setup of STAT you may run into this error. You can find the correct value in the portal https://portal.cloudappsecurity.com/ by following these steps: - -1. Click on the ❔ icone on the top right -2. Click on the About item -3. Copy the FQDN you see from the PORTAL URL section - -> Do not include the https:// component, copy the FQDN only. - -![image](https://user-images.githubusercontent.com/22434561/153331954-c072f23d-1e3e-4d69-bf1c-448fa27e92ec.png) - -4. Navigate to the Azure Portal and into your STAT Function App -5. Click on Configuration -6. Edit the MDCA_ENDPOINT set it to the value obtained above and click Ok -7. Click Save - -## GrantPermissions.ps1 permissions failures - -The script will fail to set Graph API permissions on the system-assigned managed identities if you use an account which is not a member of the Global Administrator role or User Access Administrator role. See the [deployment documentation](/Deploy#grant-permissions) for more details. - -If you run into permissions or consent issues with the GrantPermissions.ps1, you can try using the [LegacyGrantPermissions.ps1](/Deploy/LegacyGrantPermissions.ps1). It leverages the legacy AzureAD PowerShell module and doesn't require explicit consent for the scopes `AppRoleAssignment.ReadWrite.All` and `Application.Read.All`. - -## GrantPermissions.ps1 Missing closing '}' - -If you save and run the script on a machine without the MgGraph module installed, you might see a misleading error message suggesting that a missing } prevents the script from running. It is in fact an issue with MgGraph cmdlets not being available. -Make sure you have installed the MgGraph module prior executing the script. You can do so by uncommenting the 5th line of the script: -``` -Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force -``` - -## LegacyGrantPermissions.ps1 failures - -See the following table for specific failure troubleshooting. -|Error|Troubleshooting steps| -|---|---| -|`New-AzureADServiceAppRoleAssignment : Cannot convert 'System.Object[]' to the type 'System.String' required by parameter 'ObjectId'. Specified method is not supported.`|You have more than one logic app with the same name in your Azure subscription. This scenario is not supported with the current version of the script.| - -## GCC Medium - No active license found - -When using STAT in GCC Medium, you may receive an error within some modules indicating 'No active license found'. This is due to the incorrect API endpoint being used by the module. To correct this, deploy STAT using advanced mode and set both the Microsoft 365 Defender API Endpoint and Microsoft Defender for Endpoint API Endpoint to the GCC version of the endpoint. - -STAT is not presently supported in GCC High, DoD or other Sovereign clouds. \ No newline at end of file +> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Troubleshooting-%E2%80%90-Common-Errors)