Skip to content

CONCEPT Cited by 1 source

Machine metadata service

A machine metadata service is a guest-local endpoint that a workload running inside a VM / container / Machine uses to obtain information about itself from the platform that runs it — region, instance ID, tags, and (the load-bearing use case) short-lived credentials. The canonical example is AWS's EC2 Instance Metadata Service (IMDS) at http://169.254.169.254/; GCP, Azure, and most cloud platforms expose a peer.

Fly.io's analog is init's Unix-socket proxy at /.fly/api — self-described as "our answer to the EC2 Instant Metadata Service" (Source: sources/2024-06-19-flyio-aws-without-access-keys).

What a metadata service is for

The core purpose is to bridge platform-attested identity (what the control plane knows about this VM) with in-guest code that needs credentials (what the workload needs to call other services). The guest can't hold long-lived secrets safely, so the metadata service vends short-lived ones that expire before leakage matters.

On AWS:

  • IMDS → temporary credentials for the instance's IAM Role (via AssumeRole done transparently by the metadata service).

On Fly.io:

  • /.fly/api → an OIDC token signed by oidc.fly.io that the application then exchanges with STS for AWS credentials (or with any OIDC- compliant cloud's token-exchange service).

The Fly shape is two-hop (Fly → OIDC token → AWS STS → STS cred); the IMDS shape is one-hop (IMDS → IAM credential). The structural role is the same.

Security properties a metadata service must have

  1. Authenticated from the platform side. Returning credentials to anything that asks makes the service a credential oracle. EC2's IMDSv2 added a session-token handshake to address this; Fly's /.fly/api holds a Machine-scoped Macaroon token that flyd verifies on every request.
  2. Not easily reachable by SSRF. "The API proxy [is] tricky to SSRF to." (Source: sources/2024-06-19-flyio-aws-without-access-keys) A metadata service on a link-local HTTP address is trivial to target from a server-side-request-forgery vulnerability (curl http://169.254.169.254/ from the compromised app); a Unix socket requires the attacker to have the ability to open arbitrary file paths, which is a much harder primitive.
  3. Credentials the guest never directly holds. The ideal is that the metadata service attaches credentials on outbound requests (the Fly model) rather than dispenses them (the classic IMDS model). On Fly, "ordinary code running in a Fly Machine never gets a copy of the [Macaroon] token to begin with" — the guest sees only the response, not the auth material.

Shapes

  • Simple to access (curl http://169.254.169.254/...).
  • Reachable by any process in the guest's network namespace.
  • SSRF-sensitive (a vulnerable web app can be tricked into fetching http://169.254.169.254/... on behalf of an attacker).
  • Historic IMDSv1 vulnerabilities drove the IMDSv2 opt-in redesign (session-token handshake).

Unix-socket proxy (Fly /.fly/api)

  • Not reachable via HTTP-based SSRF.
  • Access-controlled by filesystem permissions (only privileged processes in the Machine can connect).
  • Credentials never flow through the guest's memory as raw tokens — the proxy attaches them to outbound requests on the way out.
  • The pattern is Fly-specific but generalisable.

Seen in

  • sources/2024-06-19-flyio-aws-without-access-keys — "Think of it as our answer to the EC2 Instant Metadata Service." /.fly/api is a Unix socket exported by init; "the API proxy [is] tricky to SSRF to." "The Fly.io platform won't honor [the Macaroon] unless it comes from that specific Fly Machine (flyd, our orchestrator, knows who it's talking to)." "Ordinary code running in a Fly Machine never gets a copy of the token to begin with."
Last updated · 200 distilled / 1,178 read