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?
• 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

Documentation coming soon.