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