Container Images

Picket native scans can read local Docker/OCI archives and pull exact image references from OCI Distribution registries.

The same sources are available through the GitHub Action and the Azure DevOps task, so CI jobs do not need a separate direct CLI invocation after their normal Picket integration is installed.

Local Image Archives

Use --docker-archive for an archive produced by docker save:

picket scan --docker-archive image.tar --report-format jsonl --redact=100

Use --oci-archive for an OCI image-layout archive:

picket scan --oci-archive image-oci.tar --report-format jsonl --redact=100

Picket scans image manifests and configs, then expands tar, gzip, and zstd layer content. Findings retain the enclosing archive and layer path:

docker-archive/image.tar!layer/layer.tar!app/settings.txt
oci-archive/image-oci.tar!blobs/sha256/<digest>!etc/secret.conf

The report path preserves that provenance, but the native fingerprint uses the logical in-image path. An equivalent layer therefore keeps the same picket:v1 fingerprint and .picketignore entry when another Docker engine recompresses it or assigns a different blob digest.

Registry Images

Pass a tagged or digest-pinned image name to --registry-image:

picket scan --registry-image ghcr.io/example/app:latest --report-format jsonl --redact=100

Docker Hub shorthand is accepted. This scans docker.io/library/ubuntu:latest:

picket scan --registry-image ubuntu --report-format jsonl --redact=100

For a multi-platform index, Picket scans every supported manifest by default. Select one platform when only one image is relevant:

picket scan --registry-image example/app:latest --registry-platform linux/amd64 --report-format sarif --report-path picket.sarif --redact=100

The platform form is os/architecture[/variant]. x64, x86_64, and aarch64 normalize to their OCI names.

Authentication

Anonymous pull is the default. Credentials are read from environment variables so values do not enter process arguments.

Use a pre-issued bearer token:

picket scan --registry-image ghcr.io/example/private-app:latest --registry-token-env PICKET_REGISTRY_TOKEN --redact=100

Use Basic authentication with a username and password or personal access token:

picket scan --registry-image registry.example/team/app:latest --registry-username-env PICKET_REGISTRY_USERNAME --registry-password-env PICKET_REGISTRY_PASSWORD --redact=100

The token form and Basic form are mutually exclusive. For a cross-host bearer challenge that needs Basic credentials, set the trusted token service explicitly:

picket scan --registry-image registry.example/team/app:latest --registry-username-env PICKET_REGISTRY_USERNAME --registry-password-env PICKET_REGISTRY_PASSWORD --registry-auth-endpoint https://auth.registry.example/token --redact=100

Use --registry-endpoint for a registry mirror or self-hosted API endpoint that differs from the host in the image name.

Provenance

Registry paths include the requested reference and immutable resolved digest:

registry/ghcr.io/example/app/tags/latest/resolved/sha256/<root-digest>/manifests/sha256/<manifest-digest>/manifest.json
registry/ghcr.io/example/app/tags/latest/resolved/sha256/<root-digest>/blobs/sha256/<layer-digest>/layer.tar.gz!app/settings.txt

Picket verifies descriptor and Docker-Content-Digest SHA-256 values before scanning content. It requests layers through the registry blob endpoint and does not follow external URLs embedded in descriptors.

Limits and Endpoint Policy

Option	Behavior
--registry-max-image-megabytes	Caps aggregate unique manifest, config, and layer downloads. The default is 512 decimal MB.
--max-target-megabytes	Caps each remote object and yielded file. The remote default is 100 decimal MB.
--max-archive-depth	Limits nested archive traversal inside layers.
--max-archive-entries	Caps extracted entries across the image.
--max-archive-megabytes	Caps decompressed bytes across the image.
--max-archive-ratio	Caps compressed-layer expansion.
--timeout	Cancels source enumeration and scanning at the configured deadline.

Remote byte caps must be positive. Registry manifests have a separate 10 decimal MB cap, image indexes are limited to 128 manifests, and image manifests are limited to 512 layers.

Zstandard decoding applies a native window limit before expansion. When no per-target byte limit is configured, the maximum window is 64 MiB; an explicit target limit derives the decoder window from that bound.

When registry layer traversal is enabled, archive entry, decompressed-byte, and expansion-ratio caps must also be positive. Set --max-archive-depth 0 for a metadata-only registry scan that intentionally skips every layer.

HTTPS and public endpoints are required by default. --allow-non-public-source-endpoints and --allow-insecure-source-endpoints are explicit exceptions for controlled development environments.

Blob downloads follow at most one redirect. Registry authorization is retained only for a same-origin redirect and is removed before any cross-origin request. Registry-provided token realms and blob redirects may use public CDN hosts; every discovered connection is still resolved once and checked against the endpoint guard before the socket opens.

Only one native source provider can be selected for a scan. Container archive and registry flags cannot be combined with source-host or object-store source flags.