144 lines
3.5 KiB
Markdown
144 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# Ensure stella CLI is installed
|
|
stella --version
|
|
|
|
# Verify registry access
|
|
stella registry ping docker://registry.example.com
|
|
```
|
|
|
|
## Basic Comparison
|
|
|
|
### Table Output (Default)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](./sample-outputs/diff.json) for a complete example.
|
|
|
|
### Summary Output
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
stella scan diff \
|
|
--base myapp:1.0.0 \
|
|
--target myapp:1.0.1 \
|
|
--include-unchanged
|
|
```
|
|
|
|
## Verbose Output
|
|
|
|
For debugging or detailed progress:
|
|
|
|
```bash
|
|
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](./dsse-attestation.md) for audit trail
|
|
- [Integrate with Policy](./policy-integration.md) for automated gates
|
|
- [Add to CI/CD](./ci-cd-integration.md) for continuous verification
|