This project introduces the Guest Proxy Agent (GPA) to enhance the security of the Azure Instance Metadata Service
and Azure Wireserver endpoints (available in Azure IaaS VM/VMSS at 169.254.169.254
and 168.63.129.16
respectively).
Analogous metadata servers are offered from the majority of cloud providers.
These services are used for providing metadata and bootstrapping VM credentials. As a result, they are frequently targeted by threat actors. Common vectors include confused deputy attacks (e.g. SSRF) against in guest workloads and sandbox escapes, which are of particular concern for hosted-on-behalf-of workloads where untrusted code is intentionally loaded into the VM.
With metadata services, the trust boundary is the VM itself. Any software within the guest is authorized to request secrets from IMDS. VM owners are responsible for carefully sandboxing any software they run inside the VM and ensuring that external actors can't exfiltrate data. This is achievable, but in practice the complexity of the problem leads to mistakes at scale which in turn lead to exploits.
While numerous defense in depth strategies exist, providing secrets over an unauthenticated HTTP API carries inherent risk. This project closes many of the most common vulnerabilities by addressing the root cause of these attacks and introducing strong Authentication (AuthN) and Authorization (AuthZ) concepts to cloud metadata services.
The GPA hardens against these types of attacks by:
At provisioning time the metadata service establishes a trusted delegate within the guest (the GPA). A long-lived secret is negotiated to authenticate with the trusted delegate, and all requests to the metadata service must be endorsed by the delegate using an HMAC. This establishes a point-to-point trust relationship with strong AuthN.
The GPA leverages eBPF to intercept HTTP requests to the metadata services. eBPF enables the GPA to authoritatively verify the identity of the in guest software that made the request without introducing an additional kernel module. Using this information, it compares the identity of the client against an allow list defined as a part of the VM model in the Azure Resource Manager (ARM) and endorses requests that are authorized by transparently adding a signature header. This means that the feature can be enabled on existing workloads without breaking changes.
eBPF is available in Linux kernels 5.15+ and on Windows VMs by installing eBPF-for-Windows. The design is not dependent on any modern security hardware, but it can be further enhanced by hardware like vTPM when available.
This project supports Azure VMs running:
The following diagram shows the basic architecture of this project and related components:
Refer to the instructions that correspond to the Operating System you wish to target:
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
The GPA can emit diagnostic and audit telemetry from the VM locally and/or to Azure for analysis. The collected events
are labeled Azure GuestProxyAgent logs
. Engineering teams and support professionals can use this telemetry to
understand metadata service usage in their workload, investigate issues, and detect hostile actors.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.