# How VMAware Detects Microsoft Azure Virtual Machines: Techniques and Implementation

> Discover how VMAware detects Microsoft Azure virtual machines using hostname heuristics and Hyper-V interrupt analysis for accurate AZURE_HYPERV classification. Learn the implementation details.

- Repository: [Louis/vmaware](https://github.com/kernelwernel/vmaware)
- Tags: deep-dive
- Published: 2026-03-05

---

**VMAware detects Azure virtual machines by combining a hostname heuristic that searches for the** `runnervm` **prefix with generic Hyper-V detection via interrupt descriptor table analysis, then merges both signals into a unified** `AZURE_HYPERV` **brand classification.**

The kernelwernel/vmaware library implements multiple specialized techniques to detect Azure virtual machines specifically, distinguishing them from other Hyper-V-based environments through a multi-layered approach that analyzes system metadata and low-level CPU structures.

## Azure-Specific Hostname Heuristic

The primary Azure detection mechanism relies on a hostname pattern match implemented in the `azure()` function located at [[`vmaware.hpp`](https://github.com/kernelwernel/vmaware/blob/main/vmaware.hpp) lines 6753-6800](https://github.com/kernelwernel/vmaware/blob/main/src/vmaware.hpp#L6753).

This function retrieves the machine hostname using platform-specific APIs—`GetComputerNameA` on Windows or `gethostname` on Linux—and validates it against a strict pattern:

- The hostname must start with the literal prefix **`runnervm`**
- Followed by exactly five alphanumeric characters (the typical Azure default format `runnervmXXXXX`)

When this pattern matches, the code invokes `core::add(brand_enum::AZURE_HYPERV)`, flagging the system specifically as an Azure Hyper-V instance rather than a generic Hyper-V environment.

## Generic Hyper-V Detection via Descriptor Tables

VMAware augments the hostname check with low-level hypervisor detection through the `system_registers()` function at [[`vmaware.hpp`](https://github.com/kernelwernel/vmaware/blob/main/vmaware.hpp) lines 6660-6670](https://github.com/kernelwernel/vmaware/blob/main/src/vmaware.hpp#L6660).

This method inspects the **Interrupt Descriptor Table (IDT)** base address returned by the `SIDT` instruction. When the high byte of the IDT base equals **`0xE8`**, the function identifies the environment as a Hyper-V or Virtual PC hypervisor. This signature indicates the presence of Microsoft's hypervisor platform, which underpins Azure infrastructure.

The detection works across all Hyper-V-based platforms, providing the foundation upon which Azure-specific identification builds.

## Brand Classification and Merging Logic

After individual checks execute, VMAware performs post-processing to resolve overlapping hypervisor brands. The Azure merge logic resides at [[`vmaware.hpp`](https://github.com/kernelwernel/vmaware/blob/main/vmaware.hpp) lines 4566-4569](https://github.com/kernelwernel/vmaware/blob/main/src/vmaware.hpp#L4566).

This block combines the `AZURE_HYPERV` brand with generic `HYPERV` and `VPC` entries. If a virtual machine triggers both the Azure hostname pattern and the generic Hyper-V IDT signature, the library reports a unified `AZURE_HYPERV` classification rather than returning ambiguous or conflicting results.

## Implementation and API Usage

Developers can access Azure detection through the high-level C++ API or the CLI wrapper.

### C++ API Detection

```cpp
// Detect Azure VM using the high-level API
if (VMAware::azure()) {
    std::cout << "Running inside Microsoft Azure\n";
}

// The low-level detection is invoked automatically 
// via VMAware::system_registers() as part of the 
// generic VM detection flow.

```

### CLI Integration

The command-line interface registers the Azure checker in [[`src/cli.cpp`](https://github.com/kernelwernel/vmaware/blob/main/src/cli.cpp)](https://github.com/kernelwernel/vmaware/blob/main/src/cli.cpp) using the following registration pattern:

```cpp
// cli.cpp – registers the Azure checker
checker(VM::AZURE, "Azure Hyper-V");

```

This exposes the detection result through the standard CLI output, allowing scripts and automation tools to identify Azure instances without direct code integration.

## Summary

- **Hostname Pattern Matching**: The `azure()` function validates the `runnervmXXXXX` hostname pattern using `GetComputerNameA` or `gethostname` to identify Azure-specific naming conventions.
- **Descriptor Table Analysis**: The `system_registers()` function detects Hyper-V via the IDT base high byte signature `0xE8`, providing the underlying hypervisor foundation.
- **Brand Resolution**: Post-processing at lines 4566-4569 merges `AZURE_HYPERV` with generic Hyper-V brands to produce unambiguous classification results.
- **Cross-Platform Support**: Implementation handles both Windows and Linux Azure VMs through conditional compilation and platform-specific system calls.

## Frequently Asked Questions

### How does VMAware distinguish Azure from other Hyper-V environments?

VMAware distinguishes Azure from other Hyper-V platforms by implementing the **`azure()`** hostname check alongside the generic Hyper-V detection. While the `system_registers()` function identifies any Hyper-V hypervisor via the IDT base signature `0xE8`, only Azure VMs exhibit the `runnervm` hostname prefix followed by exactly five alphanumeric characters. This combination allows the library to differentiate Azure specifically from on-premises Hyper-V or other Microsoft virtualization products.

### What happens if an Azure VM has a custom hostname?

If an Azure administrator configures a custom hostname that does not match the `runnervmXXXXX` pattern, the **`azure()`** function will return false. However, VMAware may still detect the environment as a generic Hyper-V instance through the `system_registers()` IDT analysis. The system would then be classified under the generic `HYPERV` brand rather than `AZURE_HYPERV`, depending on whether other Azure-specific artifacts are present and detected by additional checks in the library.

### Does the Azure detection work on both Windows and Linux guests?

Yes, the Azure hostname detection operates cross-platform. The implementation uses **`GetComputerNameA`** for Windows environments and **`gethostname`** for Linux systems to retrieve the machine name before applying the `runnervm` regex pattern. The Hyper-V detection via descriptor table analysis also functions on both platforms, ensuring consistent Azure identification regardless of the guest operating system.

### Where is the Azure detection logic located in the source code?

The Azure-specific detection logic resides in **[`src/vmaware.hpp`](https://github.com/kernelwernel/vmaware/blob/main/src/vmaware.hpp)** at lines 6753-6800 for the hostname check, lines 6660-6670 for the generic Hyper-V descriptor table analysis, and lines 4566-4569 for the brand merging post-processing. The CLI exposure is implemented in **[`src/cli.cpp`](https://github.com/kernelwernel/vmaware/blob/main/src/cli.cpp)**, which wires the detection into the public API through the `checker(VM::AZURE, "Azure Hyper-V")` registration.