OCI Image Inspection

Overview

OCI image inspection resolves an image reference to its manifest or index, enumerates platform manifests, and returns ordered layer metadata. The inspector is used by CLI workflows that need deterministic image metadata without pulling layers.

Architecture

Components

Component	Location	Responsibility
`IOciImageInspector`	`Scanner.Storage.Oci`	Public interface for image inspection
`OciImageInspector`	`Scanner.Storage.Oci`	Implements manifest/index resolution, auth flow, and ordering
`ImageInspectionResult`	`Scanner.Contracts`	Output model for index, platform, and layer data

Data flow

Parse the image reference into registry, repository, tag or digest.
HEAD the manifest to obtain media type and digest.
GET the manifest payload.
If media type is index, enumerate platform manifests and optionally resolve each manifest.
For each manifest, fetch config (for platform metadata) and list layers in manifest order.
Return ordered results with warnings and a deterministic inspection timestamp.

Media type support

Media type	Type	Handling
`application/vnd.oci.image.index.v1+json`	OCI index	Parse as index and enumerate manifests
`application/vnd.docker.distribution.manifest.list.v2+json`	Docker list	Parse as index
`application/vnd.oci.image.manifest.v1+json`	OCI manifest	Parse as manifest
`application/vnd.docker.distribution.manifest.v2+json`	Docker manifest	Parse as manifest

Configuration

The inspector uses OciRegistryOptions:

Field	Purpose
`DefaultRegistry`	Registry to use when no registry is specified
`AllowInsecure`	Allow HTTP and insecure TLS for registry calls
`Auth.Username` / `Auth.Password`	Basic auth credentials
`Auth.Token`	Bearer token
`Auth.AllowAnonymousFallback`	Allow retry without auth after 401

CLI configuration binding uses the OciRegistry section (example):

{
  "OciRegistry": {
    "DefaultRegistry": "docker.io",
    "AllowInsecure": false,
    "Auth": {
      "Username": "registry-user",
      "Password": "registry-pass",
      "AllowAnonymousFallback": true
    }
  }
}

Output model

ImageInspectionResult returns:

Resolved digest and media type
Multi-arch indicator
Ordered platform manifests (os, arch, variant)
Ordered layer list with size and media type
UTC inspection timestamp from TimeProvider
Deterministic, sorted warnings

Determinism

Platforms sorted by os, architecture, variant.
Layers preserve manifest order (0-indexed).
Warnings sorted lexicographically and de-duplicated.
Timestamps come from injected TimeProvider.

Integration points

CLI: stella image inspect consumes the inspector result for table and JSON output.
Scanner services can reuse the inspector for registry resolution without pulling layers.