Basic Binary Comparison

This example demonstrates how to perform a basic binary diff between two container image versions.

Scenario

You have deployed myapp:1.0.0 and want to understand what binary changes are in myapp:1.0.1 before upgrading.

Prerequisites

# Ensure stella CLI is installed
stella --version

# Verify registry access
stella registry ping docker://registry.example.com

Basic Comparison

Table Output (Default)

stella scan diff \
  --base docker://registry.example.com/myapp:1.0.0 \
  --target docker://registry.example.com/myapp:1.0.1

Output:

Binary Diff: docker://registry.example.com/myapp:1.0.0 -> docker://registry.example.com/myapp:1.0.1
Platform: linux/amd64
Analysis Mode: ELF Section Hashes

PATH                              CHANGE      VERDICT    CONFIDENCE
--------------------------------------------------------------------------------
/usr/lib/libssl.so.3              modified    patched    0.95
/usr/lib/libcrypto.so.3           modified    patched    0.92
/app/bin/myapp                    modified    vanilla    0.98

Summary: 156 binaries analyzed, 3 modified, 153 unchanged

JSON Output

stella scan diff \
  --base docker://registry.example.com/myapp:1.0.0 \
  --target docker://registry.example.com/myapp:1.0.1 \
  --format=json > diff.json

The JSON output contains detailed section-level information. See sample-outputs/diff.json for a complete example.

Summary Output

stella scan diff \
  --base docker://registry.example.com/myapp:1.0.0 \
  --target docker://registry.example.com/myapp:1.0.1 \
  --format=summary

Output:

Binary Diff Summary
-------------------
Base:     docker://registry.example.com/myapp:1.0.0 (sha256:abc123...)
Target:   docker://registry.example.com/myapp:1.0.1 (sha256:def456...)
Platform: linux/amd64

Binaries: 156 total, 3 modified, 153 unchanged
Verdicts: 2 patched, 1 vanilla

Using Digest References

For immutable references, use digests instead of tags:

stella scan diff \
  --base docker://registry.example.com/myapp@sha256:abc123... \
  --target docker://registry.example.com/myapp@sha256:def456...

Filtering by Platform

For multi-arch images, specify the platform:

# Linux AMD64 only
stella scan diff \
  --base myapp:1.0.0 \
  --target myapp:1.0.1 \
  --platform=linux/amd64

# Linux ARM64
stella scan diff \
  --base myapp:1.0.0 \
  --target myapp:1.0.1 \
  --platform=linux/arm64

Including Unchanged Binaries

By default, unchanged binaries are excluded from output. To include them:

stella scan diff \
  --base myapp:1.0.0 \
  --target myapp:1.0.1 \
  --include-unchanged

Verbose Output

For debugging or detailed progress:

stella scan diff \
  --base myapp:1.0.0 \
  --target myapp:1.0.1 \
  --verbose

Output includes:

Layer download progress
Binary detection details
Section hash computation progress

Understanding Verdicts

Verdict	Meaning	Action
`patched`	High confidence that a security patch was applied	Review changelog, consider safe to upgrade
`vanilla`	Standard code change, no backport evidence	Normal release update
`unknown`	Cannot determine patch status	Manual review recommended

Next Steps

Generate DSSE Attestations for audit trail
Integrate with Policy for automated gates
Add to CI/CD for continuous verification

3.5 KiB Raw Blame History