Container image inspection and analysis using skopeo and podman

version
0.0.2
GitHub stars
123

Install

/plugin install container-image@ai-helpers

Run it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.

Contents

Discovered from source

Skills 1

cve-scan

Multi-source container-image CVE scanner with an AI triage layer. The bundled toolkit in toolkit/ runs two complementary scanners and merges them; this skill drives that toolkit and reasons over the merged report — the reasoning is the point, not the mechanical scan.

Why two sources: no single scanner tells the whole truth about a Red Hat image. Red Hat's security data knows container-level and layered-product CVEs that NVD-driven scanners can't see, and applies backport-aware fix status and Red Hat severities. grype/trivy in turn report CVEs Red Hat has assessed as not-affected/won't-fix. Merging both is the only defensible picture.

Arguments

/container-image:cve-scan [<image>] [--output=triage|remediation|evidence] [--severity=<list>]
  • <image> (optional) — target image ref (e.g. registry.redhat.io/edo/foo:1.2). If omitted, infer it from the current session (see Phase 0).
  • --output (default triage) — comma-separated list of AI artifacts to produce:
    • triage — prioritized findings + coverage-gap and disagreement analysis.
    • remediation — concrete, grouped remediation steps tied to specific CVEs.
    • evidence — auditable FedRAMP/ConMon narrative citing scanner versions + provenance.
  • --severity (default: all) — comma-separated severities to focus on (critical,important,moderate,low). Lower severities are still scanned, just not foregrounded in the triage.

Both scanners always run (Red Hat security data and the open-source scanners); there is no source toggle.

Implementation

Operational details (engine selection, build/run commands, auth, caching, exit codes, troubleshooting, JSON shape) live in references/scanning.md — read it before running anything.

The scanner container takes one argument: a skopeo source (docker://…, docker-archive:…, …) and copies it with skopeo — it cannot see the host engine. Deciding which skopeo source to pass is the skill's job (Phase 0 → Phase 1).

Phase 0 — Resolve the target reference

  1. If <image> was given, use it.
  2. Otherwise infer candidates from the current session, and rank them:
    • locally built/tagged images (podman images / docker images);
    • image refs in a Dockerfile, Containerfile, or build command in the working dir;
    • image refs mentioned earlier in this conversation;
    • the repo's component image (git remote → known image name).
  3. Decide:
    • exactly one strong candidate → use it, and state which and why;
    • multiple candidates → ask the user to pick (use the AskUserQuestion tool);
    • none → ask the user for the image ref.

Phase 1 — Pick the engine, detect where the image lives, then scan

Follow references/scanning.md:

  1. Engine: if only docker or only podman is present, use it ($ENGINE); if both are present or it is unclear, ask the user; if neither is installed, stop and tell the user to install one first. Never install a container engine or any scanner on the host.
  2. Build the scanner image with $ENGINE from the bundled toolkit as the build context: ${CLAUDE_PLUGIN_ROOT}/skills/cve-scan/toolkit (see toolkit/). Tag it by the toolkit's content so a plugin upgrade never silently reuses a stale image: derive a short digest of the toolkit directory (e.g. find "$TOOLKIT" -type f | sort | xargs sha256sum | sha256sum | cut -c1-12) and build cve-scanner:<digest> only when that tag is missing. (cve-scanner:latest is acceptable only if you rebuild whenever the toolkit changes.)
  3. Detect where the reference lives (this is why detection is the skill's job — the container can't), and build the skopeo source to pass:
    • Host-local — $ENGINE image exists <ref> (podman) / $ENGINE image inspect <ref> (docker) succeeds, i.e. a build that lives only in the host engine (typically an unqualified or localhost/… tag). Export it and pass it as an archive: $ENGINE save --format docker-archive -o <tmp>/img.tar <ref> (docker: docker save -o <tmp>/img.tar <ref>), then source = docker-archive:/input/img.tar with the tar mounted -v <tmp>/img.tar:/input/img.tar:ro,z (the ,z SELinux relabel is required).
    • Registry — a registry-qualified ref not (or not only) local: source = docker://<ref>. For authenticated registries, mount credentials (next step).
    • If a registry-qualified ref is also cached in the host engine and the intent is unclear, ask which to scan (the published image vs the local copy). 3a. Registry credentials (registry sources only). skopeo inside the container can't see the host's login, so locate the host auth file, in order, and use the first that exists: $REGISTRY_AUTH_FILE → ${XDG_RUNTIME_DIR}/containers/auth.json (podman login) → $HOME/.docker/config.json (docker login) → ${XDG_CONFIG_HOME:-$HOME/.config}/containers/auth.json. Copy it into the per-run temp dir (a private mktemp -d, never relabel the user's live file) and mount the copy -v <tmp>/auth.json:/run/secrets/auth.json:ro,z -e REGISTRY_AUTH_FILE=/run/secrets/auth.json (the ,z SELinux relabel is required, as with the local tar). Credential helpers: if config.json uses credsStore/credHelpers (the secret is in a keychain, not the file), copying it yields nothing — tell the user to podman login <registry> (writes an inline auth.json) and use that. If none exists and the scan returns unauthorized, stop and tell the user to log in first — never prompt for, echo, or store credentials. Public images need none.
  4. Run the entrypoint with the chosen skopeo source and --format json -q, mounting a /cache volume (plus the tar for a local source, and the auth copy for an authenticated registry). The entrypoint pins a registry tag to its digest once so both scanners scan the identical image. Both scanners run and merge automatically; for a local source the Pyxis catalog cross-check is skipped (no catalog record). Capture the merged JSON and the exit code.

If the build or scan cannot run in this environment, stop and give the user the exact command to run, then offer to triage the JSON they produce.

Phase 2 — AI triage over the merged JSON

Filter findings to --severity (default: all), then produce the requested --output:

  • triage (default): rank findings by real-world risk, combining Red Hat severity, fix availability (fixed / won't-fix / under-investigation), PROVENANCE/COVERAGE, and Go reachability (govulncheck). Explicitly call out:
    • Red-Hat-only findings (COVERAGE script1-only) — only Red Hat's data reported them; NVD scanners did not. This is which source saw it, not where it lives: Script 1 also reports RPM and Go findings, so do not call these "container-level" from coverage alone. True container-level CVEs are the Pyxis-sourced ones — identify them by PROVENANCE (pyxis) / an image-level component, not by script1-only.
    • scanner-only findings (COVERAGE script2-only) — reported only by the open-source scanners, not in the Red Hat errata API. Their severity may come from NVD or a vendor source (e.g. GHSA, or Red Hat via trivy's SeveritySource) — check the finding's severity_source rather than assuming NVD; note when Red Hat has assessed them not-affected/won't-fix.
    • DISAGREE rows — adjudicate using Red Hat as authoritative, showing the scanner's rating (and its severity_source) for reference.
  • remediation: concrete, grouped next steps tied to specific CVEs — rebuild on a newer base, rebase the affected RPM/source package, backport, or waive-with-justification.
  • evidence: an auditable narrative suitable for FedRAMP/ConMon, citing the pinned scanner versions and scan provenance from the report header.

--output may combine artifacts (e.g. --output=triage,remediation).

Return Value

The requested AI artifact(s), plus a gate decision derived from the scan exit code: 0 clean, 1 Critical/Important present (gate would fail), 2 scan error (nothing usable ran), 3 incomplete coverage — any of: Red Hat security data degraded, the image rootfs only partially unpacked, or the OSS scan was requested but could not run or all its scanners failed. Always state the image scanned, which sources ran, and the gate decision.

Examples

/container-image:cve-scan registry.access.redhat.com/ubi9/ubi-micro:latest
/container-image:cve-scan quay.io/myorg/myapp:tag --output=triage,remediation
/container-image:cve-scan --severity=critical,important          # infer image from session
/container-image:cve-scan registry.redhat.io/edo/foo:1.3 --output=evidence

Prerequisites

  • docker or podman available in the session (the skill will not install one).
  • Network access to Red Hat's security-data APIs and to the target registry; set REGISTRY_AUTH_FILE for authenticated registries.
  • See references/scanning.md and toolkit/README.md.

Sponsors

Details

Marketplace
openshift-eng/ai-helpers
Source
plugins/container-image
Category
Community

More from openshift-eng/ai-helpers

All 56