finish off sprint advisories and sprints
This commit is contained in:
master
223
docs/modules/cli/guides/delta-attestation-workflow.md
Normal file
223
docs/modules/cli/guides/delta-attestation-workflow.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# Delta Attestation Workflow Guide
|
||||
|
||||
> **Audience:** CI/CD engineers, release operators, security auditors
|
||||
>
|
||||
> **Purpose:** End-to-end guide for generating, signing, attaching, verifying, and exporting delta-sig attestations.
|
||||
>
|
||||
> **Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline
|
||||
|
||||
## Overview
|
||||
|
||||
The delta attestation workflow provides verifiable evidence of binary-level changes between releases. It covers the full lifecycle from generating a delta-sig predicate through to offline bundle verification.
|
||||
|
||||
```
|
||||
diff → attest → attach → verify → export → offline-verify
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `stella` CLI installed and configured
|
||||
- EC signing key (PEM format) for attestation signing
|
||||
- Access to target OCI registry (for attach/verify)
|
||||
- (Optional) Rekor transparency log URL for public verifiability
|
||||
|
||||
## Step 1: Generate Delta-Sig Predicate
|
||||
|
||||
Compare two binary builds to produce a delta-sig predicate describing function-level changes:
|
||||
|
||||
```bash
|
||||
stella binary delta-sig diff \
|
||||
--old /path/to/old-binary \
|
||||
--new /path/to/new-binary \
|
||||
--output delta-predicate.json \
|
||||
--arch linux-amd64
|
||||
```
|
||||
|
||||
The predicate JSON follows the `https://stellaops.dev/delta-sig/v1` schema and includes:
|
||||
- `subject[]` - Old and new binary references with digests
|
||||
- `delta[]` - Function-level changes (added, removed, modified)
|
||||
- `summary` - Aggregate change statistics
|
||||
- `tooling` - Lifter and diff algorithm metadata
|
||||
- `largeBlobs[]` - References to binary patches or SBOM fragments (optional)
|
||||
- `sbomDigest` - Digest of the associated canonical SBOM (optional)
|
||||
|
||||
## Step 2: Sign and Attest
|
||||
|
||||
Sign the predicate with an EC key, producing a DSSE envelope. Optionally submit to a Rekor transparency log:
|
||||
|
||||
```bash
|
||||
stella binary delta-sig attest \
|
||||
--predicate delta-predicate.json \
|
||||
--key signing-key.pem \
|
||||
--output signed-envelope.dsse.json \
|
||||
--rekor-url https://rekor.sigstore.dev \
|
||||
--receipt rekor-receipt.json \
|
||||
--verbose
|
||||
```
|
||||
|
||||
**Output:**
|
||||
- `signed-envelope.dsse.json` - DSSE envelope with in-toto v1 statement
|
||||
- `rekor-receipt.json` - Rekor inclusion proof (UUID, log index, integrated time)
|
||||
|
||||
**Without Rekor (air-gapped environments):**
|
||||
|
||||
```bash
|
||||
stella binary delta-sig attest \
|
||||
--predicate delta-predicate.json \
|
||||
--key signing-key.pem \
|
||||
--output signed-envelope.dsse.json
|
||||
```
|
||||
|
||||
## Step 3: Attach to OCI Image
|
||||
|
||||
Attach the signed attestation to the target OCI image via ORAS referrers:
|
||||
|
||||
```bash
|
||||
stella attest attach \
|
||||
--image registry.example.com/app:v1.2 \
|
||||
--attestation signed-envelope.dsse.json \
|
||||
--verbose
|
||||
```
|
||||
|
||||
The attestation is stored as a referrer artifact in the registry, discoverable by image digest.
|
||||
|
||||
## Step 4: Verify Attestations
|
||||
|
||||
Verify that attestations are properly attached and valid:
|
||||
|
||||
```bash
|
||||
stella attest verify \
|
||||
--image registry.example.com/app:v1.2 \
|
||||
--predicate-type "https://stellaops.dev/delta-sig/v1" \
|
||||
--require-rekor \
|
||||
--verbose
|
||||
```
|
||||
|
||||
This checks:
|
||||
- DSSE envelope signature validity
|
||||
- Predicate type matches expected schema
|
||||
- Rekor annotations are present and valid (when `--require-rekor`)
|
||||
|
||||
## Step 5: Export Evidence Bundle
|
||||
|
||||
Export all attestation evidence for offline environments:
|
||||
|
||||
```bash
|
||||
# Light mode (metadata only, small size)
|
||||
stella evidence export-bundle \
|
||||
--image registry.example.com/app:v1.2 \
|
||||
--output evidence-light.tar.gz
|
||||
|
||||
# Full mode (includes binary blobs for replay)
|
||||
stella evidence export-bundle \
|
||||
--image registry.example.com/app:v1.2 \
|
||||
--output evidence-full.tar.gz \
|
||||
--full
|
||||
```
|
||||
|
||||
### Bundle Contents
|
||||
|
||||
**Light bundle:**
|
||||
```
|
||||
bundle/
|
||||
├── manifest.json # exportMode: "light"
|
||||
└── attestations/
|
||||
└── delta-sig.dsse.json
|
||||
```
|
||||
|
||||
**Full bundle:**
|
||||
```
|
||||
bundle/
|
||||
├── manifest.json # exportMode: "full"
|
||||
├── attestations/
|
||||
│ └── delta-sig.dsse.json
|
||||
└── blobs/
|
||||
├── sha256-<hex1> # Binary patch
|
||||
└── sha256-<hex2> # SBOM fragment
|
||||
```
|
||||
|
||||
## Step 6: Offline Bundle Verification
|
||||
|
||||
Verify the exported bundle in air-gapped environments:
|
||||
|
||||
```bash
|
||||
# Full bundle: self-contained verification with blob replay
|
||||
stella bundle verify \
|
||||
--bundle evidence-full.tar.gz \
|
||||
--offline \
|
||||
--trust-root /etc/stellaops/tsa-root.pem \
|
||||
--replay \
|
||||
--verbose
|
||||
|
||||
# Light bundle: provide local blob source for replay
|
||||
stella bundle verify \
|
||||
--bundle evidence-light.tar.gz \
|
||||
--offline \
|
||||
--replay \
|
||||
--blob-source /path/to/cached-blobs/
|
||||
```
|
||||
|
||||
### Verification Steps
|
||||
|
||||
| Step | Check | Failure Behavior |
|
||||
|------|-------|------------------|
|
||||
| 1 | Manifest checksum | Fatal |
|
||||
| 2 | Blob digests | Fatal |
|
||||
| 3 | DSSE signatures | Fatal |
|
||||
| 4 | Rekor proofs | Fatal (if checkpoint provided) |
|
||||
| 5 | RFC 3161 timestamps | Fatal (in strict mode) |
|
||||
| 6 | Payload type expectations | Warning (fatal in strict) |
|
||||
| 7 | Blob replay | Fatal (when `--replay` enabled) |
|
||||
|
||||
## CI/CD Integration Example
|
||||
|
||||
```yaml
|
||||
# .gitea/workflows/release.yaml
|
||||
jobs:
|
||||
attest:
|
||||
steps:
|
||||
- name: Generate delta predicate
|
||||
run: |
|
||||
stella binary delta-sig diff \
|
||||
--old ${{ steps.build.outputs.old_binary }} \
|
||||
--new ${{ steps.build.outputs.new_binary }} \
|
||||
--output delta-predicate.json
|
||||
|
||||
- name: Sign and submit to Rekor
|
||||
run: |
|
||||
stella binary delta-sig attest \
|
||||
--predicate delta-predicate.json \
|
||||
--key ${{ secrets.SIGNING_KEY_PATH }} \
|
||||
--output envelope.dsse.json \
|
||||
--rekor-url https://rekor.sigstore.dev \
|
||||
--receipt rekor-receipt.json
|
||||
|
||||
- name: Attach to image
|
||||
run: |
|
||||
stella attest attach \
|
||||
--image ${{ env.REGISTRY }}/${{ env.IMAGE }}:${{ env.TAG }} \
|
||||
--attestation envelope.dsse.json
|
||||
|
||||
- name: Export full bundle for auditors
|
||||
run: |
|
||||
stella evidence export-bundle \
|
||||
--image ${{ env.REGISTRY }}/${{ env.IMAGE }}:${{ env.TAG }} \
|
||||
--output evidence-bundle.tar.gz \
|
||||
--full
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| `Blob Replay ✗` | Missing blobs in light bundle | Use `--blob-source` or export with `--full` |
|
||||
| `DSSE signature ✗` | Key mismatch | Verify signing key matches trusted keys |
|
||||
| `Rekor proof ✗` | No checkpoint provided | Add `--rekor-checkpoint` for offline |
|
||||
| Exit code 2 | Invalid predicate JSON | Check required fields: subject, delta, summary, tooling, computedAt |
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Commands Reference](commands/reference.md)
|
||||
- [Offline Verification Guide](../../attestor/guides/offline-verification.md)
|
||||
- [BinaryIndex Architecture](../../binary-index/architecture.md)
|
||||
- [Audit Bundle Format](audit-bundle-format.md)
|
||||
Reference in New Issue
Block a user