Skip to content

Update documentation to point to the Wiki #476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
briandelmsft merged 14 commits into from
Jan 3, 2025
Merged

Update documentation to point to the Wiki #476

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
fdf8fc8
Update readme.md
piaudonn Jan 3, 2025
2c0fa80
Update authentication.md
piaudonn Jan 3, 2025
4548e77
Update authentication.md
piaudonn Jan 3, 2025
95eb5fa
Update deployment.md
piaudonn Jan 3, 2025
3a12db6
Update howitworks.md
piaudonn Jan 3, 2025
db1bbba
Update incidenttasks.md
piaudonn Jan 3, 2025
6717e9b
Update deployment.md
piaudonn Jan 3, 2025
58b405c
Update authentication.md
piaudonn Jan 3, 2025
b3bd70f
Update howitworks.md
piaudonn Jan 3, 2025
f5c97a1
Update mssp.md
piaudonn Jan 3, 2025
537214e
Update remediation.md
piaudonn Jan 3, 2025
46d1db7
Update riskscoring.md
piaudonn Jan 3, 2025
dd449f4
Update sample.md
piaudonn Jan 3, 2025
3837e39
Update troubleshooting.md
piaudonn Jan 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 1 addition & 72 deletions Docs/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
92 changes: 1 addition & 91 deletions Docs/deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
33 changes: 1 addition & 32 deletions Docs/howitworks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
18 changes: 1 addition & 17 deletions Docs/incidenttasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
> STAT documentation is now located in the built-in [Wiki](https://github.com/briandelmsft/SentinelAutomationModules/wiki/Modules#incident-tasks)
56 changes: 1 addition & 55 deletions Docs/mssp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Loading
Loading