Cybersecurity glossary
What is Instance Metadata Service (IMDS)?
Learn what the Instance Metadata Service (IMDS) is, how IMDSv1 and IMDSv2 differ, why hop limits matter on container hosts, and how to stop SSRF from stealing instance roles.
Definition
Instance Metadata Service (IMDS) is the virtual-machine metadata API—reached at a link-local address such as 169.254.169.254—that provides instance identity, user data, and temporary credentials for the role attached to that VM.
Why IMDS is a high-value target
The role on a VM is often the most powerful identity in that environment: it can read buckets, assume other roles, or talk to the Kubernetes API as the node. IMDS vends that role as an HTTP response to whoever can reach the link-local address.
Capital One–class incidents taught the industry that an SSRF in a public app plus IMDSv1 plus an overbroad instance profile is a complete cloud compromise path. The protocol details below exist to make that path expensive.
IMDSv1 versus IMDSv2
| Aspect | IMDSv1 | IMDSv2 |
|---|---|---|
| How a client starts | GET the metadata path | PUT to obtain a session token, then GET with that header |
| Blind GET-only SSRF | Often enough to retrieve credentials | Usually blocked unless the app can PUT and replay headers |
| Hop / TTL control | Limited | Response TTL can be 1 so pods off the host namespace drop the packet |
| Default on new accounts | Legacy AMIs and old Terraform still enable it | Should be required; v1 disabled at org policy when possible |
How IMDS credential theft usually happens
An application can fetch URLs
Webhooks, previewers, import-from-URL, or an SSRF in an XML/PDF parser.
The fetch hits 169.254.169.254
Redirects, DNS rebinding, or an unsanitized host parameter aim at IMDS.
Temporary instance credentials return
Access key, secret, and session token for the instance profile.
The attacker uses the role from outside
Cloud APIs are called as the VM. IAM—not IMDS—decides the blast radius.
Controls that actually change the outcome
Require IMDSv2
Disable v1 at the AMI, launch template, and organization policy layers.
Hop limit 1 on container hosts
IMDS replies stay in the host namespace so ordinary pods never see them.
Shrink the instance role
Nodes need ECR pull and CNI permissions—not S3 admin or iam:*.
Split workload identity
Pods assume their own role via IRSA/WIF/Azure Workload ID instead of IMDS.
IMDS hardening checklist
- Require IMDSv2 (or the provider equivalent) and disable IMDSv1 with an org guardrail.
- Set the IMDS hop limit to 1 on Kubernetes and container hosts; use 2 only with a documented exception.
- Put SSRF defenses in every server-side fetcher: deny link-local, localhost, and metadata hostnames.
- Give application pods workload identity; do not let them inherit the node instance profile.
- Block 169.254.169.254 from pod networks with NetworkPolicy or eBPF policy where supported.
- Forbid hostNetwork on application pods so hop-limit tricks cannot be skipped casually.
- Keep secrets out of instance user-data; IMDS serves user-data to the same clients as credentials.
- Alert on unusual AssumeRole or management-plane calls from instance roles that should only pull images.
The practical takeaway
IMDS is the VM metadata API that hands out the instance’s cloud role. IMDSv2 and hop limits raise the bar for SSRF; they do not shrink an Administrator instance profile.
Require v2, pin hop limit 1 on container nodes, keep apps off the endpoint, and attach the smallest role the VM truly needs. Stolen IMDS tokens are stolen cloud identity—treat the protocol as a credential dispenser, not an internal curiosity.
Related security terms
Metadata Service
The general pattern of link-local identity APIs; IMDS is the VM-scoped form.
Server-Side Request Forgery (SSRF)
The usual way an application is coerced into querying IMDS.
Cloud IAM
The instance profile or managed identity that IMDS vends tokens for.
Workload Identity
Per-pod credentials so containers do not need the VM’s IMDS role.
Container Escape
HostNetwork and breakouts make IMDS reachable even when pod policy looks tight.
Frequently asked questions
What is IMDS in simple terms?
It is a web API that only the virtual machine should call. The VM asks for its own name, disks, and—most importantly—temporary keys for the IAM role attached to that instance.
How is IMDS different from a generic metadata service?
IMDS specifically serves a VM (or the host under containers). Other metadata endpoints exist for functions or GCE project attributes. The theft pattern is the same: local HTTP, powerful tokens.
What is IMDSv1 versus IMDSv2?
IMDSv1 accepts a simple GET. IMDSv2 requires a session token from a PUT with a header, which blocks many blind SSRF cases that can only issue GET requests.
What does the hop limit (TTL) do?
The packet TTL on IMDS responses can be set to 1 so packets do not leave the host network namespace. On container nodes, TTL 1 stops most pods from receiving IMDS replies unless they share the host network.
Does IMDSv2 make SSRF impossible?
No. If the attacker can send a PUT and then a GET with the returned token—or if the app forwards arbitrary headers—IMDSv2 can still be abused. Combine it with hop limits, network policy, and tiny instance roles.
Should Kubernetes worker nodes disable IMDS?
Usually not: kubelet, CSI, and the node agent need it. Restrict hops, shrink the node role, and keep application pods off hostNetwork and off 169.254.169.254.
Where else does IMDS show up?
AWS, Azure, GCP, and others expose instance metadata with different paths and headers. Treat every provider’s instance metadata as in-scope for SSRF and container network policy.
References
Explore authoritative guidance and frameworks related to instance metadata service (imds).
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.