# 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