An OCI image layout is a directory with three parts: an index.json file that points to the image, a small oci-layout file that names the layout version, and a blobs directory that holds the manifest, configuration and filesystem layers by hash. A scanner follows index.json to the manifest, then reads the layers.
Why a buyer should care
Many scanner questions come down to "can you scan from a file, with no registry and no daemon?" Air-gapped sites, build farms and customers who send you an image archive all depend on the answer. Knowing the layout helps you ask precise questions and spot a tool that handles only the easy case.
The OCI image layout specification describes the layout as a directory structure for content-addressable blobs and location-addressable references. It says the layout may be carried by many transports, including archive formats such as tar or zip, shared filesystems or network fetching. So the same bytes can arrive as a folder, a tarball or a download.
The three parts
| Part | Required | What it holds |
|---|---|---|
| blobs directory | Yes, may be empty | Content-addressable objects, stored under a folder per hash algorithm |
| oci-layout file | Yes | A JSON object with an imageLayoutVersion field |
| index.json | Yes | An image index JSON object that lists the entry points, called refs |
The specification adds that implementations should not fail when they meet unknown extra files, and it gives a common example: a manifest.json file that comes from the older Docker save format and sits beside the standard files for compatibility.
How blobs are named
Blobs are named by their content. A blob under blobs/sha256 has a file name equal to the SHA-256 hash of its bytes, and the specification says the content must match the digest in its name. That has two practical effects for a scanner and for you.
First, integrity checking is simple. If a file's hash does not match its name, something is wrong. Second, the blobs directory may contain blobs that no ref points to, and it may also lack some referenced blobs, which the specification says should then come from an external blob store. A scanner given an incomplete layout may see only part of an image. A careful tool should say so instead of reporting a clean result.
What a scanner does with the layout
In plain steps, a tool working from a layout does this:
- Reads index.json to find the manifest for the image, possibly through an image index when there are several platforms.
- Reads the manifest to find the configuration blob and the ordered list of layer blobs.
- Applies the layers in order to build the final filesystem view, honoring deletions that later layers make.
- Reads package databases and files from that view to list installed software.
- Matches the list against vulnerability data.
The specification itself describes a similar flow for creating a runtime bundle: follow the ref to a manifest, apply the filesystem layers in the specified order, and convert the image configuration to a runtime config. A scanner stops before the last step.
A worked example: checking an archive before you trust a scan
Suppose a supplier sends you an image as an OCI archive and a scan report that says "no critical findings." Before you rely on it, you can check a few things yourself.
- Unpack the archive into a clean directory.
- Confirm that index.json, oci-layout and the blobs directory exist.
- Pick two blobs and compute their hashes. Each hash should equal the file name.
- Read index.json and note how many manifests it lists. If it lists several platforms, ask which one the report covers.
- Count the layer blobs the manifest lists and confirm each is present in blobs. A missing one means the archive is partial.
- Run your own scanner on the archive and compare with the supplier's report.
If step 5 fails, the supplier's scan may have run on a different, complete copy, and the archive you hold is not what they scanned. That is worth an email.
Questions to ask a scanner vendor
- Can you scan an OCI directory and an OCI archive with no network and no daemon?
- What do you do with an index that lists several platforms? Do you scan all of them?
- What happens when a referenced blob is missing? Do you fail, warn or report clean?
- Do you verify that blob content matches its digest?
- Do you record the manifest digest in the report, so I can tie the result to one image?
Common mistakes
- Treating a tag or an archive file name as the identity of an image. The digest is the identity.
- Scanning one platform of a multi-platform image and assuming the rest match.
- Accepting a "clean" result from a tool that silently skipped missing layers.
- Mixing up the older Docker save layout with the OCI layout. They can sit side by side in one archive, as the specification notes.
Try it yourself
Click through it at your own pace, or open it full screen.
Watch which parts of the image the scan reports on, and relate each to the layers and package lists described above.
Where Safeguard fits
The Safeguard CLI, version 1.4.0, can scan container images, and the free scan at gold.safeguard.sh/scan gives you a quick way to see what a report looks like. For the no-daemon route in more detail, read scanning from a tar or OCI layout.
Quick check
Is an OCI archive the same as a docker save file?
Not exactly. They are different layouts, although the OCI specification notes that a Docker style manifest file may sit alongside the standard OCI files in one directory for compatibility.
Why are blobs named by hash?
So the content can be verified. The specification requires blob content to match the digest in its name, which makes tampering or corruption detectable.
What should a scanner do if a layer blob is missing?
It should say so clearly and not report a clean result. A partial image cannot be fully scanned, and a silent skip hides findings.
Sources
Last reviewed: 19 October 2026.
