Troubleshooting ‐ Debug Module

Troubleshooting - Debug Module

In STAT v2.0.16 and later, a Debug module has been added for debugging issues with STAT deployments. The debug module has the following capabilities.

• Collect Environment settings and Python runtime information
• Obtain and Analyze a JSON Web Token using the configured STAT identity
• Run a supported REST API call using the function app

Enable the Debug Module

The Debug module is not enabled by default and requires some setup to use. This module cannot be called by the STAT connector and would typically be called from the Azure Portal function apps interface.

To setup the debug module:

1. In the STAT Function app, Navigate to Settings -> Environment variables
2. Create or Modify the DEBUG_MODE environment variable and set the Value to 1
3. Apply this configuration
4. In the STAT Function app, Navigate to API -> CORS 
5. Add https://portal.azure.com to the Allowed Origins
6. Save the CORS configuration and restart the function app.

Perform a Token Debug

This process will obtain a token and return the properties of that token such as the scopes to ensure the token can be successfully obtained and contains the relevant scopes to the API you are calling. This process requires you to have setup the debug module.

To perform a token debug:

1. Go to your STAT Function app and on the Overview click on debug
2. Click Test/Run
3. Set the HTTP Method to POST and Key to _master (Host key)
4. Supply the following body

{
    "Test": "token",
    "Params": {
        "TokenType": "msgraph"
    }
}

Valid TokenType values include:

TokenType	Description
arm	Azure Resource Manager Token
msgraph	Microsoft Graph Token
la	Log Analytics Token
m365	Microsoft Defender XDR Token
mde	Microsoft Defender for Endpoint Token
mdca	Microsoft Defender for Cloud Apps Token

Token Output

Once completed, the token information returned should include:

{
    "ModuleName": "DebugModule",
    "STATVersion": "2.0.16",
    "Test": "token",
    "Params": {
        "TokenType": "msgraph"
    },
    "GraphEndpoint": "graph.microsoft.com",
    "ARMEndpoint": "management.azure.com",
    "LAEndpoint": "api.loganalytics.io",
    "M365Endpoint": "api.security.microsoft.com",
    "MDEEndpoint": "api.securitycenter.microsoft.com",
    "MDCAEndpoint": "<tenant>.<region>.portal.cloudappsecurity.com",
    "TenantId": "<tenantid>",
    "KVEndpoint": null,
    "KVSecretName": null,
    "KVClientId": null,
    "PackageUrl": "https://github.com/briandelmsft/STAT-Function/releases/download/v2.0.16/stat.zip",
    "PythonVersion": "3.10.15 (main, Sep 27 2024, 06:06:40) [GCC 10.2.1 20210110]",
    "Audience": "https://graph.microsoft.com",
    "Issuer": "https://sts.windows.net/<tenantid>/",
    "Expiration": "2024-12-13T15:13:10",
    "AppDisplayName": "STATv2-id",
    "AppId": "6da51fae-f6cb-466a-bdef-975e95f5a7c3",
    "Idp": "https://sts.windows.net/<tenantid>/",
    "AppRoles": [
        "RoleManagement.Read.Directory",
        "MailboxSettings.Read",
        "Directory.Read.All",
        "IdentityRiskyUser.Read.All",
        "IdentityRiskEvent.Read.All",
        "AuditLog.Read.All",
        "Reports.Read.All"
    ]
}

Note

Note: App roles for the token will vary based on the type of token requested, only relevant roles will be returned

With this output you should confirm the following:

• Is the App Display Name / App Id the identity you are expecting STAT to be operating under and the one you ran the GrantPermissions.ps1 script against?
• Is the API endpoint correct for the API you are obtaining a token for (Commercial, GCC, etc)?
• Is the tenant id in the Issuer field correct for the tenant you are expecting to get a token for?
• Is the Python version in the 3.10 or 3.11 series?
• Are the app roles in the token consistent with the permissions set by the GrantPermissions.ps1 script?

Perform a REST Call test

With the debug module enabled, rest calls can be tested directly, without the need to call other STAT capabilities. This can help to understand if the underlying problem is with accessing the API, or something within STAT processing the returned data.

In this example, we'll execute a query against a log analytics workspace using the debug module:

To perform a log analytics query using the debug module:

1. Go to your STAT Function app and on the Overview click on debug
2. Click Test/Run
3. Set the HTTP Method to POST and Key to _master (Host key)
4. Supply the following body changing the <workspaceid> and <query> as needed

{
    "Test": "rest",
    "Params": {
        "TokenType": "la",
        "Method": "post",
        "Path": "/v1/workspaces/<workspaceid>/query",
        "Body": {
            "query": "SigninLogs | take 10 | project TimeGenerated, UserPrincipalName",
            "timespan": "P1D"
        }
    }
}

The raw JSON returned from the call will be found in JSONContent and the return status code in StatusCode

Perform a RBAC Check against Sentinel

In STAT v2.0.21 and later, with the debug module enabled, you can check STAT's access to Sentinel in the context of the configured identity.

To perform a the RBAC check using debug module:

1. Go to your STAT Function app and on the Overview click on debug
2. Click Test/Run
3. Set the HTTP Method to POST and Key to _master (Host key)
4. Supply the following body changing the <SentinelSubscriptionId> and <SentinelRGName>

{
  "Test": "rbac",
  "Params": {
    "TokenType": "arm",
    "SubscriptionId": "<SentinelSubscriptionId>",
    "RGName": "<SentinelRGName>"
  }
}

Once completed review the RBACAssignedRoles to ensure it contains at least one of the following: Microsoft Sentinel Responder, Microsoft Sentinel Contributor, Contributor or Owner. If you do not see RBACAssignedRoles in the return, review the SourceError. If the SourceError is 403 / Forbidden, the STAT identity currently doesn't have access to the Sentinel RG. This could be because of an incorrect/incomplete delegation, or a cached token.