{"id":25,"date":"2026-04-18T18:13:32","date_gmt":"2026-04-18T16:13:32","guid":{"rendered":"https:\/\/wenisch.tech\/portal\/?p=25"},"modified":"2026-05-10T18:22:23","modified_gmt":"2026-05-10T16:22:23","slug":"validating-docker-image-pullability-without-the-docker-cli-or-socket","status":"publish","type":"post","link":"https:\/\/wenisch.tech\/portal\/validating-docker-image-pullability-without-the-docker-cli-or-socket\/","title":{"rendered":"Validating Docker Image Pullability without the Docker cli or socket"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

When you’re developoing an uptime monitor like Kaiors<\/a>, or in general checking whether a container image is actually pullable is a surprisingly deep problem. The naive approach \u2014 spinning up a Docker daemon and running\u00a0docker pull<\/code>\u00a0\u2014 is heavy, requires socket access, and introduces a serious security risk in most environments. Kairos solves this differently: by speaking directly to the\u00a0OCI Distribution API<\/strong>, it can validate image pullability with nothing but plain HTTPS calls.<\/p>\n\n\n\n

How Docker Pull Actually Works<\/h2>\n\n\n\n

Before skipping the CLI, it helps to understand what docker pull<\/code> does under the hood. Every container registry \u2014 Docker Hub, GitHub Container Registry, your self-hosted Harbor or JFrog Artifactory \u2014 implements the OCI Distribution Specification<\/a>. A pull is really just a sequence of three HTTP steps:<\/p>\n\n\n\n

    \n
  1. Authenticate<\/strong> \u2014 obtain a bearer token from the registry’s auth endpoint<\/li>\n\n\n\n
  2. Fetch the manifest<\/strong> \u2014 retrieve the image manifest by name and tag<\/li>\n\n\n\n
  3. Download blobs<\/strong> \u2014 pull each layer referenced in the manifest<\/li>\n<\/ol>\n\n\n\n

    To validate pullability<\/em>, you only need steps 1 and 2. If you can successfully authenticate and retrieve the manifest, the image exists, the credentials work, and the layers are reachable. You never need to actually download gigabytes of layer data.<\/p>\n\n\n\n

    Step 1 \u2014 Authentication<\/h2>\n\n\n\n

    Most registries use token-based authentication<\/strong> described in the Docker Registry Auth Specification. When you hit the manifest endpoint unauthenticated, the registry responds with:<\/p>\n\n\n\n

    textHTTP 401 Unauthorized\nWWW-Authenticate: Bearer realm=\"https:\/\/auth.docker.io\/token\",service=\"registry.docker.io\",scope=\"repository:library\/nginx:pull\"<\/code><\/pre>\n\n\n\n
    You parse the WWW-Authenticate<\/code> header and make a token request:<\/p>\n\n\n\n
    GET https:\/\/auth.docker.io\/token\n  ?service=registry.docker.io\n  &scope=repository:library\/nginx:pull<\/code><\/code><\/pre>\n\n\n\n
    For private registries, add Basic credentials:<\/p>\n\n\n\n
    GET https:\/\/registry.example.com\/token\n  ?service=registry.example.com\n  &scope=repository:myapp\/backend:pull\nAuthorization: Basic base64(user:password)<\/code><\/code><\/pre>\n\n\n\n
    The response is a short-lived Bearer token<\/strong> you attach to all subsequent requests.<\/p>\n\n\n\n
    Step 2 \u2014 Fetching the Manifest<\/h2>\n\n\n\n
    With the token in hand, request the image manifest:<\/p>\n\n\n\n
    GET \/v2\/{name}\/manifests\/{reference}\nAuthorization: Bearer <token>\nAccept: application\/vnd.oci.image.manifest.v1+json,\n        application\/vnd.docker.distribution.manifest.v2+json,\n        application\/vnd.docker.distribution.manifest.list.v2+json<\/code><\/code><\/pre>\n\n\n\n
    A 200 OK<\/code> response means the image exists and is pullable. That’s all you need. The response body contains the full manifest \u2014 digest, layers, config \u2014 but you don’t need to download any of it for a health check.<\/p>\n\n\n\n
    The important Accept<\/code> headers tell the registry you support both OCI manifests<\/strong> and Docker manifest lists<\/strong> (multi-arch images). Without them, some registries return a legacy v1 manifest or a 404.<\/p>\n\n\n\n
    Handling Multi-Architecture Images<\/h2>\n\n\n\n
    Modern images are often manifest lists<\/strong> (also called “fat manifests”) that bundle multiple architecture-specific images under one tag. A manifest list response looks like:<\/p>\n\n\n\n
    {\n  \"schemaVersion\": 2,\n  \"mediaType\": \"application\/vnd.docker.distribution.manifest.list.v2+json\",\n  \"manifests\": [\n    { \"platform\": { \"os\": \"linux\", \"architecture\": \"amd64\" }, \"digest\": \"sha256:abc...\" },\n    { \"platform\": { \"os\": \"linux\", \"architecture\": \"arm64\" }, \"digest\": \"sha256:def...\" }\n  ]\n}<\/code><\/code><\/pre>\n\n\n\n
    For a pullability check, receiving this response is already a success \u2014 the tag is valid and resolvable. If you want to validate a specific architecture, you make a second manifest request using the digest from the relevant entry.<\/p>\n\n\n\n
    Step 3 \u2014 No Docker Socket Needed<\/h2>\n\n\n\n
    The entire flow above is pure HTTPS. Kairos implements it in Java without ever touching a Docker socket or spawning a subprocess. The key advantages:<\/p>\n\n\n\n