Surveyor

Image surveys

An image survey is an inventory survey of a container image’s contents. Give spice survey inventory the image with a docker:// prefix, and the CLI pulls it from its registry with oras, which is built into the CLI’s container, so there is no docker pull and no tar export. It surveys the image’s contents and handles the result like any inventory survey, with the same options (--no-upload, --output and the rest) and the same artifact cutoff.

Run a survey

spice survey inventory [<subject>] docker://<image>

• <image> is the image reference, in the form name[:tag][@digest]. oci://<image> means the same as docker://<image>.
• <subject> is the name you choose for this application in Spice Labs; see Choose a subject. Without it, the image’s repository name, without its tag or digest, becomes the subject, so every version of the image lands on one subject. Set it when you want a different name.

Without the prefix, nginx:1.27 is read as a path. When no such file exists, the CLI stops and says to use docker://nginx:1.27.

Survey a public image:

spice survey inventory docker://nginx:1.27
spice survey inventory web-frontend docker://ghcr.io/myorg/web:2.3.0

The first survey is labeled nginx; the second, web-frontend.

How image names are expanded

spice expands short names to their full form. The default subject is the repository name, without the tag or digest:

Pin a tag or a digest when you need repeatable results, because latest changes over time.

Survey a private image

spice uses the registry credentials already stored on your machine. Log in once with Docker, then survey as normal:

docker login ghcr.io
spice survey inventory docker://ghcr.io/myorg/app:2.3.0

The wrapper shares your Docker configuration folder with the CLI, read-only. It uses $DOCKER_CONFIG if you set it, and ~/.docker otherwise. If your credentials live somewhere else, set DOCKER_CONFIG to that folder before running spice.

Docker Desktop keeps logins in a credential helper (the macOS Keychain or Windows Credential Manager) rather than in that folder. When it does, the wrapper asks the helper for the login to that one registry and passes it to the CLI in a temporary file, which is deleted when the run ends. Without a login, public images still work and private ones fail with an authentication error.

Survey a saved image

An image saved as an OCI image layout folder, for example with oras cp --to-oci-layout, needs no prefix. Survey the folder like any other, with a subject:

spice survey inventory web-frontend ./saved-image

Survey locally and upload later

Add --no-upload to survey on your machine only. Always pass --output with it, so the results land in a folder you choose:

spice survey inventory web-frontend docker://nginx:1.27 --no-upload --output ./spice-results

Each run creates its own folder inside the one you name, with the same layout as an inventory survey. While the survey runs, the image itself is downloaded into a temporary folder under --output and removed afterwards, so point --output at a disk with room for the image.

spice survey inventory web-frontend ./spice-results/surveyor/survey-<random-id> --upload-only

Other options

Image surveys accept the same options as other inventory surveys: --tag-json, --threads, --max-records, --log-level, --log-file and --analysis-args, and for the upload --chunk-size and --upload-args. See Inventory surveys for how to use them.

The older command

Before image surveys moved into spice survey inventory, they had a command of their own, spice survey image <image> [--subject=<subject>]. It still runs, but it is hidden from the help, prints a notice naming the new form, and will be removed. Its default subject now also drops the tag.