SKILL.md
Container image reviewer
An evidence-first workflow to review an image for provenance, contents, privileges, secrets, and reproducibility.
- Revision
- 2
- Verified
- 2026-10-20
Compatibility and paths
Codex
skills/container-image-review/SKILL.mdClaude Code
.claude/skills/container-image-review/SKILL.mdVS Code
.github/skills/container-image-review/SKILL.mdTrust and provenance
Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.
Generated assetReady to copy or download
---
name: container-image-review
description: Binds image evidence to the selected platform manifest and separates final-filesystem visibility from retained layers. Use when a digest pin, clean scanner count or later file deletion is being mistaken for a full image safety review.
license: CC-BY-4.0
compatibility: Owned Node.js 22.13+ examples inspect synthetic JSON offline. kubectl, Helm, Docker, a cluster, registry and credentials are not used by these exercises.
metadata:
author: oneliners
version: "2.0.0"
---
# Container image reviewer
## Name the artifact before reading its verdict
Record registry/repository, immutable index and platform-manifest identity, OS/architecture/variant, source/build revision, build-context/dependency evidence, config/layer identity and report subjects/timestamps. Distinguish a mutable tag, multi-platform index, manifest, config and filesystem layer. Verify provenance/signature policy against the approved trust root, not a self-reported label or a matching-looking filename. Never run an untrusted image to inspect it as a default review step.
## Original subject-mismatch and retained-layer exercise
The [OCI index specification](https://github.com/opencontainers/image-spec/blob/main/image-index.md) distinguishes an index from platform manifests. The complete code below models one flat index and two fake platform descriptors, plus simple layer records. The layer null value is this fixture's tombstone notation, not an implementation of OCI whiteouts. Save the reviewed block as image-evidence-fixture.mjs and run node image-evidence-fixture.mjs with Node.js 22.13+; it has no Docker/registry/network dependency.
```js
function reviewImageEvidence(packet) {
const validDigest = (value) => typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
if (!packet?.targetPlatform || !Array.isArray(packet.manifests) || !packet.scan || !Array.isArray(packet.layers)) throw new Error("platform, index, scan and layer evidence required");
for (const value of [packet.indexDigest, packet.deployedManifestDigest, packet.imageConfigDigest, packet.scan.subjectManifestDigest, ...packet.manifests.map((manifest) => manifest.digest)]) if (!validDigest(value)) throw new Error("invalid digest syntax");
const matches = packet.manifests.filter((manifest) => manifest.platform?.os === packet.targetPlatform.os && manifest.platform?.architecture === packet.targetPlatform.architecture);
if (packet.targetPlatform.variant != null || matches.some((manifest) => manifest.platform?.variant != null)) return { gate: "HOLD_PLATFORM_VARIANT_REVIEW_REQUIRED" };
if (matches.length !== 1) return { gate: "HOLD_PLATFORM_SELECTION_AMBIGUOUS_OR_MISSING" };
const selected = matches[0].digest;
const merged = new Map();
for (const layer of packet.layers) for (const [path, value] of Object.entries(layer)) {
if (value !== null && typeof value !== "string") throw new Error("layer toy values must be strings or null tombstones");
if (value === null) merged.delete(path); else merged.set(path, value);
}
const retainedTrainingMarker = packet.layers.some((layer) => Object.values(layer).some((value) => typeof value === "string" && value.includes("TRAINING_ONLY_NOT_A_SECRET")));
const blockers = [];
if (selected !== packet.deployedManifestDigest) blockers.push("DEPLOYED_MANIFEST_NOT_SELECTED_PLATFORM");
if (packet.scan.subjectManifestDigest !== selected) blockers.push("SCAN_SUBJECT_NOT_SELECTED_MANIFEST");
if (retainedTrainingMarker) blockers.push("DELETION_DID_NOT_REMOVE_EARLIER_LAYER_MARKER");
return { selectedManifest: selected, scanSubjectMatches: packet.scan.subjectManifestDigest === selected, finalViewHasEnv: merged.has(".env"), earlierLayerHasTrainingMarker: retainedTrainingMarker, blockers, gate: blockers.length ? "HOLD" : "MODELED_CHECKS_CLEAR_NOT_IMAGE_SAFETY_PROOF" };
}
const packet = {
"provenance": "synthetic flat OCI index and review records; digests are fake fixture identifiers, no registry was queried",
"targetPlatform": {
"os": "linux",
"architecture": "amd64"
},
"indexDigest": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"manifests": [
{
"digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"platform": {
"os": "linux",
"architecture": "amd64"
}
},
{
"digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"platform": {
"os": "linux",
"architecture": "arm64"
}
}
],
"deployedManifestDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"imageConfigDigest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"scan": {
"subjectManifestDigest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"criticalFindings": 0,
"provenance": "synthetic single-manifest report, not a verified scanner result"
},
"layers": [
{
".env": "TRAINING_ONLY_NOT_A_SECRET",
"app.js": "synthetic program bytes"
},
{
".env": null
}
]
};
console.log(JSON.stringify(reviewImageEvidence(packet), null, 2));
```
## Evidence ledger and decision
HOLD. The linux/amd64 descriptor selects manifest sha256:aaaa… (64 a characters), matching the supplied deployment reference. The zero-critical report names sha256:bbbb… for the arm64 manifest, not that selected image. A result for a different single-manifest subject cannot establish the deployed manifest's findings. Index digest sha256:1111… and config digest sha256:cccc… identify different OCI objects; comparing either directly to a platform-manifest digest would not establish an image mismatch by itself.
The toy final filesystem no longer contains .env, yet the first retained layer record still contains TRAINING_ONLY_NOT_A_SECRET. Deleting a path in a later layer changes the merged view, not the bytes retained in that earlier layer. This marker is explicitly not a real secret. The example is an object/Map model of layered visibility, NOT a Docker build, OCI tar/whiteout parser, credential scan or proof that any actual image leaks a secret.
Next evidence: obtain authorized digest-bound scan/SBOM/provenance coverage for the actually selected platform manifest, and inspect the approved build-context/secret-handling policy and relevant artifact evidence without dumping secret bytes. A report targeting an index may be useful only when its platform coverage is evidenced; this fixture intentionally handles a report naming one manifest. Pinning a digest identifies content but does not by itself prove provenance, a clean scan, reproducible builds or safe runtime privileges.
Fixing only the report subject leaves the layer marker blocker. Omitting the copied marker from the owned model removes that toy blocker, but passing modeled checks is still not an image-safety verdict. Real signatures, build identity, package/advisory freshness, secret controls and runtime permissions remain unverified. No image was pulled, built, executed, pushed or scanned.
## Review build inputs and runtime separately
Check the final stage and material actually copied into it, base image identity, lockfiles/package sources, build-context exclusions and approved secret mounts. [Docker build secrets](https://docs.docker.com/build/building/secrets/) are distinct from general ARG/ENV parameters. A secret mount does not prevent a build command from copying its content elsewhere; inspect the build behavior and artifacts without disclosing sensitive values. Check effective runtime UID, privilege/capability policy, mounts, writable paths and application needs in the actual deployment; a Dockerfile USER line alone is not the complete runtime security context.
## Discriminating checks and limits
Keep the selected platform unchanged and correct only the scan subject: the report-identity blocker should disappear, not the earlier-layer marker. Remove only the marker from the toy build input: the layer blocker disappears, not the wrong report subject. Missing/ambiguous platform selection is a hold for this deliberately limited checker; it does not implement nested-index/variant negotiation or claim the OCI index is invalid. Scanner identity, scope, package database age and exclusions still matter even for a matching digest.
## Output and stop conditions
Return an artifact→platform→evidence-subject ledger, verified facts versus missing evidence, actual observed findings, proposed bounded read-only checks, owner and rollout gate. Do not invent a successful rebuild, scan or signature verification. Do not send image layers, private source, environment dumps or raw scanner output containing secrets to a new destination. Missing artifact identity, report coverage, trust policy or build/runtime evidence prevents a safety claim; ask for those bounded inputs instead of recommending an automatic deploy or an unreviewed base-image upgrade.
Real example
Input
Review the platform/scan subject relationship and toy layer visibility. Do not claim actual registry, scan or secret evidence from these fake descriptors.
{
"provenance": "synthetic flat OCI index and review records; digests are fake fixture identifiers, no registry was queried",
"targetPlatform": {
"os": "linux",
"architecture": "amd64"
},
"indexDigest": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"manifests": [
{
"digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"platform": {
"os": "linux",
"architecture": "amd64"
}
},
{
"digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"platform": {
"os": "linux",
"architecture": "arm64"
}
}
],
"deployedManifestDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"imageConfigDigest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"scan": {
"subjectManifestDigest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"criticalFindings": 0,
"provenance": "synthetic single-manifest report, not a verified scanner result"
},
"layers": [
{
".env": "TRAINING_ONLY_NOT_A_SECRET",
"app.js": "synthetic program bytes"
},
{
".env": null
}
]
}Expected result
HOLD. The linux/amd64 descriptor selects manifest sha256:aaaa… (64 a characters), matching the supplied deployment reference. The zero-critical report names sha256:bbbb… for the arm64 manifest, not that selected image. A result for a different single-manifest subject cannot establish the deployed manifest's findings. Index digest sha256:1111… and config digest sha256:cccc… identify different OCI objects; comparing either directly to a platform-manifest digest would not establish an image mismatch by itself. The toy final filesystem no longer contains .env, yet the first retained layer record still contains TRAINING_ONLY_NOT_A_SECRET. Deleting a path in a later layer changes the merged view, not the bytes retained in that earlier layer. This marker is explicitly not a real secret. The example is an object/Map model of layered visibility, NOT a Docker build, OCI tar/whiteout parser, credential scan or proof that any actual image leaks a secret. Next evidence: obtain authorized digest-bound scan/SBOM/provenance coverage for the actually selected platform manifest, and inspect the approved build-context/secret-handling policy and relevant artifact evidence without dumping secret bytes. A report targeting an index may be useful only when its platform coverage is evidenced; this fixture intentionally handles a report naming one manifest. Pinning a digest identifies content but does not by itself prove provenance, a clean scan, reproducible builds or safe runtime privileges. Fixing only the report subject leaves the layer marker blocker. Omitting the copied marker from the owned model removes that toy blocker, but passing modeled checks is still not an image-safety verdict. Real signatures, build identity, package/advisory freshness, secret controls and runtime permissions remain unverified. No image was pulled, built, executed, pushed or scanned.