IMDSCore – Azure Managed Identity Diagnostics
IMDSCore is a diagnostic and health monitoring utility designed to validate Azure Managed Identity and DefaultAzureCredential token acquisition behavior via the IMDS (Instance Metadata Service) endpoint. It optionally supports packet-level network tracing and proxy probing to help identify connectivity or authentication issues.
This tool is especially useful for diagnosing identity and token failures in environments such as:
Azure Virtual Machines or App Services using Managed Identity
Azure Kubernetes Service (AKS) with Workload Identity
Azure-hosted containers or Service Fabric applications
Cloud and local development environment.
Core Features
Managed Identity Token Probing
Uses ManagedIdentityCredential (--mode mic) or DefaultAzureCredential (--mode dac) to repeatedly request tokens and log results.
Failure Threshold Monitoring
Automatically exits after N consecutive token acquisition failures.
Network Trace Collection
Captures IMDS traffic using netsh (Windows) or tcpdump (Linux) to help debug connectivity issues.
Proxy Configuration Diagnostics
Optionally logs proxy settings and diagnostics using --proxyprob.
Flexible Logging
Supports custom log directories, log file size can be dynamically set (default unit: 250MB), and up to 4 rotated files.
Download IMDSCore for Windows and Linux
Download it via Winget [Windows]
WinGet install IMDSCore
Download it via WGet [Linux]
wget https://github.com/sashaOM231190/IMDSCore/releases/download/Beta-v2.3-2025.09.03_Linux/IMDSCore-Lin_v2.3-2025.09.03.zip
Command line options
IMDSCore.exe --mode mic|dac --identity sys|user
[--clientid [id]]
[--maxfailures [n]]
[--logdir [path]]
[--overridepath [path]]
[--logfilesize [size]]
[--test]
[--printtoken]
[--nettrace]
[--proxyprob]
IMDSCore.exe --options
[env|vs|cli|vscode|powershell|browser|cache|default]
[--tenantid [id]]
[--clientid [id]]
[--secret [value]]
[--certpath [path]]
[--certpass [pwd]]
| Switch | Description |
|---|
--mode | Credential type: mic (ManagedIdentityCredential) or dac (DefaultAzureCredential). |
--identity | Identity type: sys (system-assigned) or user (user-assigned). |
--clientid | Required if --identity user; specifies the Client ID of the user-assigned identity. |
--maxfailures | Stop execution after N consecutive token failures (default: unlimited; max recommended: 5). |
--logdir | Custom directory for logs; defaults to OS-specific location. |
--overridepath | (Linux only) Override the default internal log path. |
--logfilesize | Max size of each log file in MB (default: 250MB). |
--test | Run a single token test and exit (dry-run mode). |
--printtoken | Print acquired token into log file (recommended with --test). |
--nettrace | Enable network tracing using netsh (Windows) or tcpdump (Linux). |
--proxyprob | Print current proxy configuration and test its impact on IMDS traffic. |
--options | Local authentication mode; enables credential providers outside IMDS. Must specify one provider. |
--tenantid | (With --options env) Azure Tenant ID for service principal / cert-based auth. |
--secret | (With --options env) Client secret for service principal authentication. |
--certpath | (With --options env) Path to certificate .pfx file. |
--certpass | (With --options env) Password for the .pfx certificate file. |
| Provider | Description |
|---|
default | Full DefaultAzureCredential chain (env, VS, VSCode, CLI, PowerShell, browser). Skips IMDS. |
env | EnvironmentCredential. Uses environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, etc.) or CLI args (--tenantid, --clientid, --secret, --certpath, --certpass). |
vs | VisualStudioCredential. Uses accounts signed into Visual Studio. |
vscode | VisualStudioCodeCredential. Uses Azure Account extension in VS Code. |
cli | AzureCliCredential. Requires Azure CLI installed and logged in (az login). |
powershell | AzurePowerShellCredential. Requires Az PowerShell module installed (Connect-AzAccount). |
browser | InteractiveBrowserCredential. Opens a browser window for login. |
cache | SharedTokenCacheCredential. Uses MSAL shared cache (tokens from MS apps like Teams/Outlook/VS). |
Examples
Basic Token Probe with System Identity
IMDSCore.exe --mode mic --identity sys
Probe with Proxy Diagnostics
IMDSCore.exe --mode mic --identity sys --proxyprob
Use MIC with User Identity and Print Token
IMDSCore.exe --mode mic --identity user --clientid [ClientId] --printtoken
Run a Single Dry Test
IMDSCore.exe --mode dac --identity user --clientid [ClientId] --test
Enable Network Trace and Custom Logging
IMDSCore.exe --mode mic --identity sys --nettrace --logdir "C:\Logs"
On Linux: Override Default Log Path (/tmp/imdstrace)
Note : With network trace prefer using default log path (don't use --logdir), else it may fail with permission error,
./IMDSCore --mode mic --identity user --clientid [ClientId] --logdir /tmp/customlogs --overridepath
Use CLI Arguments with Client Secret
IMDSCore.exe --options env --tenantid yyyy --clientid xxxx --secret zzzz
Use CLI Arguments with Certificate
IMDSCore.exe --options env --tenantid yyyy --clientid xxxx --certpath "C:\Temp\appcert.pfx" --certpass "P@ssword123!"
Use Az CLI
IMDSCore.exe --options cli
Use Visual Studio Account
IMDSCore.exe --options vs
Use Environment Credentials
IMDSCore.exe --options env
On Linux:
--overridepath can be used to write logs outside /tmp/imdstrace.
For --nettrace, ensure tcpdump and pkill are installed.
On Windows:
--nettrace requires admin privileges (to run netsh trace).
For --options cache: Works only if a valid MSAL token exists (from VS/Office apps).
For --options cli: Requires az installed and az login executed.