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  SECTIONS CHANGED
-----------------------------------------------------------------------------------
/app/bin/myapp                    modified  unknown   0.65        .rodata, .text
/usr/lib/libcrypto.so.3           modified  unknown   0.70        .text
/usr/lib/libssl.so.3              modified  unknown   0.75        .rodata, .text

Summary: 156 binaries analyzed, 3 modified, 153 unchanged
         Added: 0, Removed: 0
         Verdicts: unknown: 3, vanilla: 153

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
Target:   docker://registry.example.com/myapp:1.0.1
Platform: linux/amd64

Binaries: 156 total, 3 modified, 153 unchanged
Added: 0, Removed: 0
Verdicts: unknown: 3, vanilla: 153

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
`vanilla`	Unchanged binary	No action required
`unknown`	Diff detected but classifier is not yet applied	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