Image Inspection Guide

This guide is for operators and CI engineers using the Stella Ops CLI to inspect container images directly from a registry.

Overview

stella image inspect resolves an OCI image reference, enumerates platform manifests, and lists layers. Use it to confirm what is deployed where and to feed downstream verification workflows.

The command talks directly to the target registry over the OCI distribution API. It is a local CLI operation and does not call the Stella Authority — no Stella scope is required. Registry credentials (when needed) come from the CLI’s OciRegistry config section, not from a Stella access token.

Source: command wiring in src/Cli/StellaOps.Cli/Commands/ImageCommandGroup.cs; handler in src/Cli/StellaOps.Cli/Commands/CommandHandlers.Image.cs; inspector in src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/OciImageInspector.cs.

Deprecation note. The CLI route map (src/Cli/StellaOps.Cli/cli-routes.json) marks image inspect as deprecated in favour of scan image inspect (slated for removal in 3.0, “Image analysis consolidated under scan”). However, as of this writing scan image inspect is a placeholder stub that prints fixed sample data (sha256:abc123..., Layers: 5, Size: 125MB) and does not perform real inspection. The functional implementation is stella image inspect, documented here. Prefer it until scan image inspect is wired to the real inspector. See the flagged note at the end of this guide.

Basic usage

stella image inspect nginx:latest

Bare names resolve against the default registry (docker.io) and bare Docker Hub repos are expanded to library/<name> (so nginx becomes docker.io/library/nginx). If no tag or digest is given, latest is assumed.

Options

JSON output for automation

stella image inspect nginx:latest --output json > image-inspect.json

The JSON is canonical (stable key ordering) so it is safe to diff or hash across runs. Top-level fields (camelCase):

• reference — the reference you passed.
• resolvedDigest — digest of the resolved index/manifest.
• mediaType — media type of the resolved artifact.
• isMultiArch — true for an image index, false for a single manifest.
• platforms[] — one entry per platform; each has os, architecture, manifestDigest, manifestMediaType, configDigest, layers[] (each order, digest, mediaType, size, optional annotations), and totalSize. The optional variant and osVersion keys are emitted only when present — the canonical serializer omits null-valued fields, so platforms without a variant or OS version simply lack those keys.
• registry, repository — parsed registry host and repo path.
• inspectedAt — UTC inspection timestamp.
• inspectorVersion — inspector assembly version, for reproducibility.
• warnings[] — non-fatal issues encountered during inspection (sorted, de-duplicated).

Platform filter

stella image inspect nginx:latest --platform linux/amd64

The filter accepts os/arch or os/arch/variant. An out-of-range form (one part, or more than three) is rejected as a usage error.

Private registry (HTTP)

For local registries that use HTTP, include the scheme in the reference:

stella image inspect http://localhost:5000/myapp:1.0.0

http:// and https:// scheme prefixes are honoured end-to-end (the inspector’s reference parser, OciImageReference.Parse, strips them and contacts the registry over the matching scheme). A docker:// prefix is accepted by the CLI’s pre-flight reference validation (OciImageReferenceParser.Parse) but is not understood by the inspector parser that actually builds the registry URL — docker://... passes validation and then mis-parses when contacting the registry. Do not prefix references with docker://; pass a bare reference or use http:// / https://. (Setting OciRegistry.AllowInsecure=true in CLI config additionally forces plain HTTP and accepts self-signed TLS certificates.) See the flagged note at the end of this guide.

If you need registry auth, configure the OciRegistry section in your CLI config (see docs/modules/scanner/image-inspection.md). The available keys are:

• OciRegistry.DefaultRegistry — registry used for bare references (default docker.io).
• OciRegistry.AllowInsecure — allow plain HTTP / self-signed TLS (default false).
• OciRegistry.Auth.Username / OciRegistry.Auth.Password — Basic auth.
• OciRegistry.Auth.Token — Bearer token (takes precedence over username/password).
• OciRegistry.Auth.AllowAnonymousFallback — fall back to anonymous on 401 (default true).

The CLI uses anonymous-by-default credentials; it does not consult the integration-aware credential provider that the scanner worker uses.

CI usage example

stella image inspect ghcr.io/org/app:1.2.3 --output json \
  | jq '.platforms[] | { os: .os, arch: .architecture, layers: (.layers | length) }'

Exit codes

In JSON mode, errors are emitted as a canonical { "status": "error", "message": "..." } object on stdout.

Offline mode

When the CLI is in offline mode, image inspect refuses to run (it requires network access) and exits 2 with Offline mode enabled. Image inspection requires network access.. See the flagged note below regarding the current state of offline-mode detection.

Troubleshooting

Authentication required

• Symptom: Authentication required for <registry>. error (exit code 2). This is raised when the registry response carries a 401/403/Unauthorized/Forbidden warning.
• Fix: configure OciRegistry.Auth in your CLI config or use a registry that allows anonymous pulls.

Rate limits and other registry warnings

• Symptom: with --verbose, warnings such as Manifest GET returned TooManyRequests. (HTTP 429) or other non-2xx statuses; in JSON output these appear in the warnings[] array.
• Fix: retry later, use authenticated credentials, or mirror to a private registry. Note there is no dedicated retry/back-off for 429 — the status is surfaced as a warning and inspection continues with whatever the registry returned.

Unsupported media types

• Symptom: warnings such as Unknown manifest media type '<type>'. or Unable to parse manifest JSON..
• Fix: confirm the registry serves OCI or Docker v2 manifests (image index, manifest list, image manifest, Docker manifest, or OCI artifact manifest), and ensure the image reference is correct.

Image not found

• Symptom: Image not found: <reference> (exit code 1).
• Fix: verify the tag/digest exists in the repository and that the reference (registry, repo path, tag/digest) is correct.

Flagged for maintainers (doc<->code reconciliation):

1. cli-routes.json deprecates image inspect toward scan image inspect, but scan image inspect (CommandFactory.BuildScanImageCommand, ~line 1559) is a stub printing hardcoded placeholder values — it never calls OciImageInspector. The deprecation target is not yet functional; the deprecated image inspect is the only real implementation. This guide intentionally documents image inspect.
2. OfflineModeGuard (src/Cli/StellaOps.Cli/Services/OfflineModeGuard.cs) is a stub keyed off a static IsOffline flag that is documented in-source as “will be wired to actual offline mode detection” and is not bound to any config key or CLI flag. The handler calls the IsNetworkAllowed(options, "image inspect") overload, but that overload ignores the options argument entirely and just returns !IsOffline. The offline-mode exit-2 path exists in code but is not currently reachable through normal configuration. The “Offline mode” section above describes the coded behaviour, not a wired feature.
3. Two different reference parsers run on each invocation and disagree about docker://. The CLI pre-flight validation uses OciImageReferenceParser.Parse (src/Cli/StellaOps.Cli/Services/OciImageReferenceParser.cs), which recognises http://, https://, and docker://. The actual inspection uses OciImageReference.Parse (src/Scanner/__Libraries/StellaOps.Scanner.Storage.Oci/OciImageReference.cs), which only strips http:///https:// and has no docker:// branch. Net effect: a docker://... reference passes validation, then mis-parses when the inspector builds the registry URL. Either teach the inspector parser to strip docker://, or reject it in the CLI validation parser, so the two agree.