dockerls 1.0.0__py3-none-any.whl

dockerls/integrations/registry/inspector.py

@@ -0,0 +1,420 @@
+"""Resolve a tag to a digest and read the image's configuration.
+
+This is where "digest-first" stops being a slogan. A tag is a mutable
+pointer: `node:22` names different bytes this week than last, so a
+recommendation that says only `node:22` cannot be checked against the scan
+that produced it. Resolving the tag through the registry gives the manifest
+digest -- the content-addressed identity of the image -- and everything
+downstream (deduplication, caching, the evidence trail, the recommendation
+itself) keys off that instead.
+
+The same round-trip yields the OCI image **config**, which is the only
+source of verified runtime facts available without pulling and unpacking
+the image: the account it runs as, the ports it declares, its entrypoint,
+its layer count. Those facts are what the hardening and attack-surface
+models are built from, and they are labelled `REGISTRY` because they were
+measured, not claimed.
+
+Integrity is checked rather than assumed: a config blob is addressed by its
+own SHA-256, so the bytes that come back are hashed and compared against the
+digest that was requested. A registry, proxy or cache that returns different
+content fails that comparison and the config is discarded. This is a cheap,
+real supply-chain check, and skipping it would mean trusting a network path
+to describe the image whose security we are about to certify.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import re
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+from dockerls.domain.entities.image_facts import EvidenceSource, HardeningFacts
+from dockerls.domain.value_objects.tristate import Tristate
+from dockerls.infrastructure.network.host_guard import HostGuard
+from dockerls.integrations.registry.oci import OCIRegistryClient
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.image import DockerImage
+
+#: Docker Hub's registry endpoint. Distinct from `hub.docker.com`, which is
+#: the catalogue API the search client uses.
+DOCKER_HUB_REGISTRY = "registry-1.docker.io"
+
+#: Media types accepted when asking for a manifest. Both the OCI and the
+#: Docker v2 spellings, indexes first, because a multi-arch tag answers with
+#: an index and the per-architecture manifest has to be selected from it.
+MANIFEST_ACCEPT = ", ".join(
+    (
+        "application/vnd.oci.image.index.v1+json",
+        "application/vnd.docker.distribution.manifest.list.v2+json",
+        "application/vnd.oci.image.manifest.v1+json",
+        "application/vnd.docker.distribution.manifest.v2+json",
+    )
+)
+
+#: Architecture preferred when a tag resolves to a multi-arch index.
+DEFAULT_ARCHITECTURE = "amd64"
+DEFAULT_OS = "linux"
+
+_DIGEST = re.compile(r"^sha256:[a-f0-9]{64}$")
+#: Registry host: a DNS name with an optional port. Anchored, and no
+#: userinfo, scheme or path can survive it -- this string is interpolated
+#: into a URL, so nothing that could redirect the request is allowed
+#: through.
+_HOST = re.compile(r"^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,251}[a-zA-Z0-9])?(:\d{1,5})?$")
+_REPOSITORY = re.compile(r"^[a-z0-9]+(?:[._/-][a-z0-9]+)*$")
+
+
+class RegistryInspector:
+    """Resolves references to digests and reads image configs, per registry.
+
+    One `OCIRegistryClient` is kept per host so connections and anonymous
+    tokens are reused across every candidate from that registry, and each
+    (repository, reference) pair is resolved at most once per run.
+    """
+
+    def __init__(
+        self,
+        timeout: int = 30,
+        guard: HostGuard | None = None,
+        credentials: dict[str, tuple[str, str]] | None = None,
+    ):
+        self._timeout = timeout
+        # Where this inspector is permitted to send a request. A reference is
+        # user input carrying a hostname, so without a policy `dockerls
+        # analyze 169.254.169.254/x` is an outbound request to the cloud
+        # metadata endpoint chosen by whoever supplied the reference.
+        self._guard = guard or HostGuard()
+        # host -> (username, password), for a reference naming a registry
+        # this run has credentials for -- the configured private registry,
+        # today. `analyze`/`compare`/`alternatives` take a reference
+        # directly rather than going through `SourceRegistry`, so this is
+        # how they reach the same credentials `--source private` uses.
+        self._credentials = credentials or {}
+        self._clients: dict[str, OCIRegistryClient] = {}
+        self._clients_lock = asyncio.Lock()
+        self._resolved: dict[str, tuple[str, dict[str, Any] | None]] = {}
+        # Digests learned from a cheap HEAD, kept separately so a later full
+        # inspection of the same reference does not re-resolve them.
+        self._digests: dict[str, str] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
+
+    async def _client(self, host: str) -> OCIRegistryClient | None:
+        if not _HOST.match(host):
+            logger.warning(f"Refusing to contact registry with unexpected host: {host!r}")
+            return None
+        # Checked here rather than at the call sites: this is the single
+        # place a host becomes a connection, so a future caller cannot
+        # forget the check.
+        if not self._guard.allows(host):
+            logger.warning(f"Refusing to contact {host}: {self._guard.explain(host)}")
+            return None
+        async with self._clients_lock:
+            client = self._clients.get(host)
+            if client is None:
+                username, password = self._credentials.get(host, ("", ""))
+                client = OCIRegistryClient(
+                    host,
+                    timeout=self._timeout,
+                    guard=self._guard,
+                    username=username,
+                    password=password,
+                )
+                self._clients[host] = client
+            return client
+
+    async def close(self) -> None:
+        async with self._clients_lock:
+            clients, self._clients = list(self._clients.values()), {}
+        for client in clients:
+            await client.close()
+
+    async def resolve_digest(self, image: DockerImage) -> str:
+        """The manifest digest for `image`, from a single HEAD request.
+
+        This is the cheap half of `inspect`, and it runs over every
+        candidate rather than just the finalists: without a digest, two tags
+        that name the same bytes look like two different images and are
+        scanned twice. One HEAD per unresolved tag buys deduplication across
+        *every* source -- `node:22`, `node:22-bookworm` and a hardened
+        catalogue's alias of the same manifest collapse into one scan.
+
+        Returns "" when the registry cannot be asked or does not answer,
+        which leaves the candidate keyed by its reference as before.
+        """
+        target = _registry_target(image)
+        if target is None:
+            return ""
+        host, repository = target
+        key = f"{host}/{repository}:{image.tag}"
+
+        lock = self._locks.setdefault(key, asyncio.Lock())
+        async with lock:
+            if key in self._digests:
+                return self._digests[key]
+            client = await self._client(host)
+            digest = ""
+            if client is not None:
+                resp = await client.get(
+                    f"{repository}/manifests/{image.tag}", accept=MANIFEST_ACCEPT, head=True
+                )
+                if resp is not None:
+                    digest = _clean_digest(resp.headers.get("Docker-Content-Digest", ""))
+            self._digests[key] = digest
+            return digest
+
+    async def inspect(self, image: DockerImage) -> tuple[str, HardeningFacts]:
+        """Return (digest, facts) for `image`.
+
+        The digest is "" when the registry could not be asked or did not
+        answer, and the facts are empty in the same case. Both outcomes mean
+        "not determined": the caller keeps whatever it already had and the
+        candidate carries UNKNOWNs rather than fabricated defaults.
+        """
+        target = _registry_target(image)
+        if target is None:
+            return "", HardeningFacts()
+        host, repository = target
+        reference = image.digest if _DIGEST.match(image.digest) else image.tag
+        key = f"{host}/{repository}:{reference}"
+
+        lock = self._locks.setdefault(key, asyncio.Lock())
+        async with lock:
+            if key in self._resolved:
+                digest, config = self._resolved[key]
+            else:
+                digest, config = await self._resolve(host, repository, reference)
+                self._resolved[key] = (digest, config)
+                if digest:
+                    self._digests.setdefault(f"{host}/{repository}:{image.tag}", digest)
+
+        return digest, _facts_from_config(config)
+
+    async def _resolve(
+        self, host: str, repository: str, reference: str
+    ) -> tuple[str, dict[str, Any] | None]:
+        client = await self._client(host)
+        if client is None:
+            return "", None
+
+        resp = await client.get(f"{repository}/manifests/{reference}", accept=MANIFEST_ACCEPT)
+        if resp is None:
+            return "", None
+
+        digest = _clean_digest(resp.headers.get("Docker-Content-Digest", ""))
+        try:
+            manifest: Any = resp.json()
+        except ValueError:
+            logger.warning(f"Registry returned an unparseable manifest for {host}/{repository}")
+            return digest, None
+        if not isinstance(manifest, dict):
+            return digest, None
+
+        manifests = manifest.get("manifests")
+        if isinstance(manifests, list):
+            # A multi-arch index. The index digest is the image's identity,
+            # so it is kept; the per-architecture manifest is followed only
+            # to reach the config.
+            child = _select_platform(manifests)
+            if child is None:
+                return digest, None
+            child_digest = _clean_digest(str(child.get("digest") or ""))
+            if not child_digest:
+                return digest, None
+            child_resp = await client.get(
+                f"{repository}/manifests/{child_digest}", accept=MANIFEST_ACCEPT
+            )
+            if child_resp is None:
+                return digest, None
+            try:
+                manifest = child_resp.json()
+            except ValueError:
+                return digest, None
+            if not isinstance(manifest, dict):
+                return digest, None
+
+        config = await self._fetch_config(client, host, repository, manifest)
+        return digest, config
+
+    async def _fetch_config(
+        self,
+        client: OCIRegistryClient,
+        host: str,
+        repository: str,
+        manifest: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        descriptor = manifest.get("config")
+        if not isinstance(descriptor, dict):
+            return None
+        config_digest = _clean_digest(str(descriptor.get("digest") or ""))
+        if not config_digest:
+            return None
+
+        resp = await client.get(f"{repository}/blobs/{config_digest}")
+        if resp is None:
+            return None
+
+        # Content addressing, actually checked. A blob whose bytes do not
+        # hash to the digest that named it is not the config this manifest
+        # points at, whatever the registry says.
+        actual = f"sha256:{hashlib.sha256(resp.content).hexdigest()}"
+        if actual != config_digest:
+            logger.warning(
+                f"Config blob digest mismatch for {host}/{repository}: "
+                f"requested {config_digest}, received {actual}. Discarding."
+            )
+            return None
+
+        try:
+            config: Any = json.loads(resp.content)
+        except ValueError:
+            logger.warning(f"Config blob for {host}/{repository} was not valid JSON")
+            return None
+        if not isinstance(config, dict):
+            return None
+        # The layer list lives on the manifest, not the config, and it is
+        # what gives a verified layer count.
+        layers = manifest.get("layers")
+        if isinstance(layers, list):
+            config["__layers"] = layers
+        return config
+
+
+def _registry_target(image: DockerImage) -> tuple[str, str] | None:
+    """Split an image name into (registry host, repository path).
+
+    Unqualified names are Docker Hub, where a single-component name lives
+    under `library/`. Returns None for anything whose host or repository
+    does not match the expected shape, so a crafted name cannot become a
+    request to an arbitrary URL.
+    """
+    name = image.name.strip()
+    host = image.registry_host
+    repository = name[len(host) + 1 :] if host else name
+    if not host:
+        host = DOCKER_HUB_REGISTRY
+        if "/" not in repository:
+            repository = f"library/{repository}"
+
+    if not _HOST.match(host) or not _REPOSITORY.match(repository):
+        logger.info(f"Not resolving {name!r}: unexpected registry or repository shape")
+        return None
+    return host, repository
+
+
+def _select_platform(manifests: list[Any]) -> dict[str, Any] | None:
+    """Pick the linux/amd64 entry of an index, or the first usable one.
+
+    Attestation manifests (cosign, SLSA) appear alongside real images in
+    modern indexes and declare `platform.architecture: unknown`; selecting
+    one would produce a config describing a signature rather than an image.
+    """
+    usable: list[dict[str, Any]] = []
+    for entry in manifests:
+        if not isinstance(entry, dict):
+            continue
+        platform = entry.get("platform")
+        platform = platform if isinstance(platform, dict) else {}
+        architecture = str(platform.get("architecture") or "")
+        if architecture == "unknown":
+            continue
+        if architecture == DEFAULT_ARCHITECTURE and str(platform.get("os") or "") == DEFAULT_OS:
+            return entry
+        usable.append(entry)
+    return usable[0] if usable else None
+
+
+def _clean_digest(value: str) -> str:
+    digest = value.strip().lower()
+    return digest if _DIGEST.match(digest) else ""
+
+
+def _facts_from_config(config: dict[str, Any] | None) -> HardeningFacts:
+    """Turn an OCI image config into verified facts.
+
+    The one judgement call worth stating: an image whose config sets no
+    `User` runs as root. That is a determined FALSE for `runs_as_non_root`,
+    not an UNKNOWN -- the config was read and it says the default account is
+    root. The distinction matters, because "the image does not say" and
+    "nobody looked" have opposite consequences for a score.
+    """
+    if config is None:
+        return HardeningFacts()
+
+    section = config.get("config")
+    section = section if isinstance(section, dict) else {}
+
+    user = str(section.get("User") or "").strip()
+    ports = _ports(section.get("ExposedPorts"))
+    entrypoint = _string_list(section.get("Entrypoint"))
+    cmd = _string_list(section.get("Cmd"))
+    layers = config.get("__layers")
+    layer_count = len(layers) if isinstance(layers, list) else None
+    size = _total_size(layers) if isinstance(layers, list) else None
+
+    evidence = {
+        "runs_as_non_root": EvidenceSource.REGISTRY,
+        "exposed_ports": EvidenceSource.REGISTRY,
+        "has_healthcheck": EvidenceSource.REGISTRY,
+        "entrypoint": EvidenceSource.REGISTRY,
+    }
+    if layer_count is not None:
+        evidence["layer_count"] = EvidenceSource.REGISTRY
+
+    return HardeningFacts(
+        runs_as_non_root=Tristate.of(bool(user) and user.split(":", 1)[0] not in ("root", "0")),
+        user=user,
+        exposed_ports=ports,
+        # A config that declares no healthcheck was still read: Docker treats
+        # an absent Healthcheck as "none", which is a determined fact.
+        has_healthcheck=Tristate.of(bool(section.get("Healthcheck"))),
+        entrypoint=entrypoint,
+        cmd=cmd,
+        layer_count=layer_count,
+        size_bytes=size,
+        os_family=str(config.get("os") or ""),
+        config_verified=True,
+        evidence=evidence,
+    )
+
+
+def _ports(value: Any) -> list[int]:
+    """Port numbers from an OCI `ExposedPorts` map ("8080/tcp": {})."""
+    if not isinstance(value, dict):
+        return []
+    ports: list[int] = []
+    for key in value:
+        if not isinstance(key, str):
+            continue
+        head = key.split("/", 1)[0]
+        try:
+            port = int(head)
+        except ValueError:
+            continue
+        if 0 < port <= 65535:
+            ports.append(port)
+    return sorted(set(ports))
+
+
+def _string_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, str)]
+
+
+def _total_size(layers: list[Any]) -> int | None:
+    total = 0
+    seen = False
+    for layer in layers:
+        if not isinstance(layer, dict):
+            continue
+        size = layer.get("size")
+        if isinstance(size, int) and size >= 0:
+            total += size
+            seen = True
+    return total if seen else None

dockerls/integrations/registry/oci.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from loguru import logger
+
+from dockerls.infrastructure.network.guarded_client import guarded_async_client
+
+if TYPE_CHECKING:
+    from dockerls.infrastructure.network.host_guard import HostGuard
+
+# Cosign and friends publish their signatures, attestations and SBOMs as
+# ordinary tags in the same repository. They are not runnable images, so
+# they must never reach the scan pipeline.
+_ARTIFACT_TAG = re.compile(
+    r"""
+    ^sha256[-:]            # cosign artifacts: sha256-<digest>.sig/.att/.sbom
+  | \.(sig|att|sbom)$
+  | ^deprecated-public-image-
+    """,
+    re.VERBOSE,
+)
+
+# Single-architecture aliases of a multi-arch tag ("16-amd64"). Scanning them
+# adds duplicates of a tag we already have.
+_ARCH_SUFFIX = re.compile(r"-(amd64|arm64|arm|armv[567]|386|ppc64le|s390x|riscv64|mips64le|wasm)$")
+
+# Provenance-pinned variants -- either suffixed ("debug-nonroot-165b5d63...")
+# or a bare commit hash -- point at the same image as their base tag.
+# Distroless publishes dozens per release; unfiltered they crowd out every
+# distinct image in the listing.
+_COMMIT_TAG = re.compile(r"(-[0-9a-f]{32,}$|^[0-9a-f]{32,}$)")
+
+
+#: Manifests and config blobs are kilobytes. A registry (or something
+#: pretending to be one) answering with more than this is not serving
+#: metadata, and the body is discarded rather than parsed.
+MAX_BLOB_BYTES = 8 * 1024 * 1024
+
+
+def is_runnable_tag(tag: str) -> bool:
+    """True for tags that name a distinct image a user would actually pull."""
+    if not tag or _ARTIFACT_TAG.search(tag):
+        return False
+    if _COMMIT_TAG.search(tag):
+        return False
+    return not _ARCH_SUFFIX.search(tag)
+
+
+def parse_www_authenticate(header: str) -> tuple[str, dict[str, str]]:
+    """Split a `Bearer realm="...",service="...",scope="..."` challenge into
+    (realm, params)."""
+    if not header.lower().startswith("bearer"):
+        return "", {}
+    params = dict(re.findall(r'(\w+)="([^"]*)"', header))
+    return params.pop("realm", ""), params
+
+
+def is_fetchable_realm(realm: str) -> bool:
+    """Whether a `WWW-Authenticate` realm is a URL we will actually fetch.
+
+    Requires an absolute http/https URL with a host. That rules out
+    `file://`, `gopher://` and the schemeless forms; *where* the host may be
+    is the network policy's business, enforced per hop by the guarded
+    client, and is deliberately not re-decided here.
+    """
+    try:
+        url = httpx.URL(realm)
+    except (httpx.InvalidURL, ValueError, TypeError, UnicodeError):
+        return False
+    return url.scheme in ("http", "https") and bool(url.host)
+
+
+class OCIRegistryClient:
+    """Minimal OCI Distribution v2 client for listing tags.
+
+    Implements only the anonymous pull-scope token dance that public
+    registries use: request the endpoint, and if it answers 401 with a
+    Bearer challenge, fetch a token from the advertised realm and retry.
+
+    A listing is fetched **once per repository per run**. `recommend` asks
+    for the same listing many times over -- once during discovery, then once
+    more for every candidate whose tag `_verify_tags` confirms -- and each
+    call previously opened a fresh connection, ate a 401, fetched a token,
+    and re-downloaded a payload identical to the one it already had. For a
+    single repository with ten candidates that is 33 requests where 3 do the
+    job.
+
+    Three things close that gap, and they compose:
+
+    * One `httpx.AsyncClient` for the client's lifetime, so connections and
+      the TLS handshake are reused (HTTP keep-alive) instead of rebuilt.
+    * A per-repository result cache.
+    * A per-repository lock, so ten *concurrent* first calls collapse into
+      one request rather than ten -- a cache with no single-flight guard
+      would still stampede, because verification runs them in parallel.
+
+    The cache lives on the instance, so it lasts exactly one run and cannot
+    serve a listing from a previous invocation.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        timeout: int = 30,
+        guard: HostGuard | None = None,
+        *,
+        username: str = "",
+        password: str = "",
+    ):
+        self._host = host
+        self._timeout = timeout
+        # Redirects are followed, and the token realm is a URL this registry
+        # chooses. Both are hops the caller's up-front check on `host` says
+        # nothing about, so the guard travels with the client.
+        self._guard = guard
+        # Basic credentials for the token endpoint -- the standard Docker
+        # Registry HTTP API V2 flow every private registry this client
+        # targets (ECR, Harbor, GHCR, a generic OCI registry) implements the
+        # same way: the 401 challenge names a realm, and that realm accepts
+        # HTTP Basic auth in exchange for a scoped bearer token. Empty
+        # strings mean anonymous, unchanged from before this parameter
+        # existed.
+        self._username = username
+        self._password = password
+        self._client: httpx.AsyncClient | None = None
+        self._client_lock = asyncio.Lock()
+        self._listings: dict[str, dict[str, Any] | None] = {}
+        self._listing_locks: dict[str, asyncio.Lock] = {}
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            async with self._client_lock:
+                if self._client is None:
+                    self._client = guarded_async_client(
+                        self._guard, timeout=self._timeout, follow_redirects=True
+                    )
+        return self._client
+
+    async def close(self) -> None:
+        """Release the shared connection pool."""
+        client, self._client = self._client, None
+        if client is not None:
+            await client.aclose()
+
+    async def _token(self, client: httpx.AsyncClient, challenge: str) -> str:
+        realm, params = parse_www_authenticate(challenge)
+        if not realm:
+            return ""
+        if not is_fetchable_realm(realm):
+            # The realm is a URL chosen by the far end. Fetching whatever it
+            # names turns any registry -- or anything on the path to one --
+            # into a redirector pointing this process at the host's internal
+            # network. An `https://` realm on a real registry is the norm;
+            # anything else is refused before a socket is opened.
+            logger.warning(f"Refusing token realm advertised by {self._host}: {realm!r}")
+            return ""
+        auth = (self._username, self._password) if self._username and self._password else None
+        resp = await client.get(realm, params=params, auth=auth)
+        resp.raise_for_status()
+        data = resp.json()
+        # Registries disagree on the field name; GCR/ECR use access_token.
+        token: str = data.get("token") or data.get("access_token") or ""
+        return token
+
+    async def list_tags(self, repository: str) -> dict[str, Any] | None:
+        """Return the raw `/v2/<repository>/tags/list` payload, or None when
+        the repository does not exist or cannot be reached.
+
+        Memoised per repository for the lifetime of this client, including
+        the `None` outcome: a repository that does not exist should be asked
+        about once, not once per candidate.
+        """
+        if repository in self._listings:
+            return self._listings[repository]
+
+        lock = self._listing_locks.setdefault(repository, asyncio.Lock())
+        async with lock:
+            # A concurrent caller may have filled it while we waited.
+            if repository in self._listings:
+                return self._listings[repository]
+            payload = await self._fetch_tags(repository)
+            self._listings[repository] = payload
+            return payload
+
+    async def get(
+        self,
+        path: str,
+        *,
+        accept: str = "",
+        head: bool = False,
+        max_bytes: int = MAX_BLOB_BYTES,
+    ) -> httpx.Response | None:
+        """One authenticated request against `/v2/<path>` on this registry.
+
+        Performs the same anonymous token dance `_fetch_tags` uses, and
+        bounds the response body: a manifest or config blob is a few
+        kilobytes, and a registry answering with megabytes is either broken
+        or hostile. Returns None on any failure, including an oversized
+        body -- callers treat that as "could not determine", never as an
+        empty result.
+        """
+        url = f"https://{self._host}/v2/{path}"
+        headers = {"Accept": accept} if accept else {}
+        try:
+            client = await self._get_client()
+            resp = await client.request("HEAD" if head else "GET", url, headers=headers)
+            if resp.status_code == 401:
+                token = await self._token(client, resp.headers.get("WWW-Authenticate", ""))
+                if not token:
+                    logger.info(f"No anonymous token available for {self._host}/{path}")
+                    return None
+                resp = await client.request(
+                    "HEAD" if head else "GET",
+                    url,
+                    headers={**headers, "Authorization": f"Bearer {token}"},
+                )
+        except (httpx.HTTPError, ValueError) as e:
+            logger.warning(f"Registry request failed for {self._host}/{path}: {e}")
+            return None
+
+        if not resp.is_success:
+            logger.info(f"Registry answered {resp.status_code} for {self._host}/{path}")
+            return None
+        if not head and len(resp.content) > max_bytes:
+            logger.warning(
+                f"Registry response for {self._host}/{path} exceeded {max_bytes} bytes; discarded"
+            )
+            return None
+        return resp
+
+    async def _fetch_tags(self, repository: str) -> dict[str, Any] | None:
+        url = f"https://{self._host}/v2/{repository}/tags/list"
+        try:
+            client = await self._get_client()
+            resp = await client.get(url)
+            if resp.status_code == 401:
+                token = await self._token(client, resp.headers.get("WWW-Authenticate", ""))
+                if not token:
+                    logger.warning(f"No anonymous token available for {self._host}")
+                    return None
+                resp = await client.get(url, headers={"Authorization": f"Bearer {token}"})
+
+            if resp.status_code == 404:
+                logger.info(f"Repository not found: {self._host}/{repository}")
+                return None
+            resp.raise_for_status()
+            payload: dict[str, Any] = resp.json()
+            return payload
+        except (httpx.HTTPError, ValueError) as e:
+            logger.warning(f"Tag listing failed for {self._host}/{repository}: {e}")
+            return None