fix tests. new product advisories enhancements
This commit is contained in:
master
287
docs/modules/attestor/tuf-integration.md
Normal file
287
docs/modules/attestor/tuf-integration.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# TUF Integration Guide
|
||||
|
||||
This guide explains how StellaOps uses The Update Framework (TUF) for secure trust
|
||||
distribution and how to configure TUF-based trust management.
|
||||
|
||||
## Overview
|
||||
|
||||
TUF provides a secure method for distributing and updating trust anchors (public keys,
|
||||
service endpoints) without requiring client reconfiguration. StellaOps uses TUF to:
|
||||
|
||||
- Distribute Rekor public keys for checkpoint verification
|
||||
- Distribute Fulcio certificate chains for keyless signing
|
||||
- Provide service endpoint discovery (Rekor, Fulcio URLs)
|
||||
- Enable secure key rotation with grace periods
|
||||
- Support offline verification with bundled trust state
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TUF Trust Hierarchy │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────┐ │
|
||||
│ │ Root │ ← Offline, rotates rarely (yearly) │
|
||||
│ │ Key │ │
|
||||
│ └────┬────┘ │
|
||||
│ │ │
|
||||
│ ┌────┴────────────────────────────┐ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Snapshot │ │Timestamp │ │ Targets │ │
|
||||
│ │ Key │ │ Key │ │ Key │ │
|
||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ snapshot.json timestamp.json targets.json │
|
||||
│ │ │ │
|
||||
│ │ ├── rekor-key-v1.pub │
|
||||
│ │ ├── rekor-key-v2.pub │
|
||||
│ │ ├── fulcio-chain.pem │
|
||||
│ │ └── sigstore-services-v1.json │
|
||||
│ │ │
|
||||
│ └── Refreshed frequently (daily) │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## TUF Roles
|
||||
|
||||
### Root
|
||||
- Signs the root metadata containing all role keys
|
||||
- Highest trust level, rotates rarely
|
||||
- Should be kept offline in secure storage (HSM, air-gapped system)
|
||||
- Used only for initial setup and key rotation ceremonies
|
||||
|
||||
### Timestamp
|
||||
- Signs timestamp metadata indicating freshness
|
||||
- Must be refreshed frequently (default: daily)
|
||||
- Clients reject metadata older than expiration
|
||||
- Can be automated with short-lived credentials
|
||||
|
||||
### Snapshot
|
||||
- Signs snapshot metadata listing current target versions
|
||||
- Updated when targets change
|
||||
- Prevents rollback attacks
|
||||
|
||||
### Targets
|
||||
- Signs metadata for actual target files
|
||||
- Lists hashes and sizes for verification
|
||||
- Supports delegations for large repositories
|
||||
|
||||
## Configuration
|
||||
|
||||
### Attestor Configuration
|
||||
|
||||
```yaml
|
||||
attestor:
|
||||
trust_repo:
|
||||
enabled: true
|
||||
tuf_url: https://trust.yourcompany.com/tuf/
|
||||
refresh_interval_minutes: 60
|
||||
freshness_threshold_days: 7
|
||||
offline_mode: false
|
||||
local_cache_path: /var/lib/stellaops/tuf-cache
|
||||
service_map_target: sigstore-services-v1
|
||||
rekor_key_targets:
|
||||
- rekor-key-v1
|
||||
- rekor-key-v2
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `enabled` | Enable TUF-based trust distribution | `false` |
|
||||
| `tuf_url` | URL to TUF repository root | Required |
|
||||
| `refresh_interval_minutes` | How often to check for updates | `60` |
|
||||
| `freshness_threshold_days` | Max age before rejecting metadata | `7` |
|
||||
| `offline_mode` | Use bundled metadata only | `false` |
|
||||
| `local_cache_path` | Local metadata cache directory | OS-specific |
|
||||
| `service_map_target` | TUF target name for service map | `sigstore-services-v1` |
|
||||
| `rekor_key_targets` | TUF target names for Rekor keys | `["rekor-key-v1"]` |
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `STELLA_TUF_ROOT_URL` | Override TUF repository URL |
|
||||
| `STELLA_SIGSTORE_SERVICE_MAP` | Path to local service map override |
|
||||
| `STELLA_TUF_OFFLINE_MODE` | Force offline mode (`true`/`false`) |
|
||||
|
||||
## CLI Usage
|
||||
|
||||
### Initialize Trust
|
||||
|
||||
```bash
|
||||
# Initialize with a TUF repository
|
||||
stella trust init \
|
||||
--tuf-url https://trust.yourcompany.com/tuf/ \
|
||||
--service-map sigstore-services-v1 \
|
||||
--pin rekor-key-v1 rekor-key-v2
|
||||
|
||||
# Initialize in offline mode with bundled metadata
|
||||
stella trust init \
|
||||
--tuf-url file:///path/to/bundled-trust/ \
|
||||
--offline
|
||||
```
|
||||
|
||||
### Sync Metadata
|
||||
|
||||
```bash
|
||||
# Refresh TUF metadata
|
||||
stella trust sync
|
||||
|
||||
# Force refresh even if fresh
|
||||
stella trust sync --force
|
||||
```
|
||||
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
# Show current trust state
|
||||
stella trust status
|
||||
|
||||
# Show with key details
|
||||
stella trust status --show-keys --show-endpoints
|
||||
```
|
||||
|
||||
### Export for Offline Use
|
||||
|
||||
```bash
|
||||
# Export trust state
|
||||
stella trust export --out ./trust-bundle/
|
||||
|
||||
# Create sealed snapshot with tiles
|
||||
stella trust snapshot export \
|
||||
--out ./snapshots/2026-01-25.tar.zst \
|
||||
--depth 10000
|
||||
```
|
||||
|
||||
### Import Offline Bundle
|
||||
|
||||
```bash
|
||||
# Import trust bundle
|
||||
stella trust import ./snapshots/2026-01-25.tar.zst \
|
||||
--verify-manifest \
|
||||
--reject-if-stale 7d
|
||||
```
|
||||
|
||||
## Service Map
|
||||
|
||||
The service map (`sigstore-services-v1.json`) contains endpoint URLs for Sigstore
|
||||
services. This enables endpoint changes without client reconfiguration.
|
||||
|
||||
### Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"rekor": {
|
||||
"url": "https://rekor.sigstore.dev",
|
||||
"log_id": "c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d",
|
||||
"public_key_target": "rekor-key-v1"
|
||||
},
|
||||
"fulcio": {
|
||||
"url": "https://fulcio.sigstore.dev",
|
||||
"root_cert_target": "fulcio-chain.pem"
|
||||
},
|
||||
"overrides": {
|
||||
"staging": {
|
||||
"rekor_url": "https://rekor.sigstage.dev"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Site-Local Overrides
|
||||
|
||||
Organizations can define environment-specific overrides:
|
||||
|
||||
```yaml
|
||||
attestor:
|
||||
trust_repo:
|
||||
environment: staging # Use staging overrides from service map
|
||||
```
|
||||
|
||||
## Key Rotation
|
||||
|
||||
TUF supports secure key rotation with grace periods:
|
||||
|
||||
1. **Add new key**: Publish new key while keeping old key active
|
||||
2. **Grace period**: Clients sync and receive both keys
|
||||
3. **Verify**: Ensure all clients have new key
|
||||
4. **Revoke old key**: Remove old key from active set
|
||||
|
||||
See [Key Rotation Runbook](../../operations/key-rotation-runbook.md) for detailed procedures.
|
||||
|
||||
## Offline Mode
|
||||
|
||||
For air-gapped environments, StellaOps can operate with bundled TUF metadata:
|
||||
|
||||
1. Export trust state on connected system:
|
||||
```bash
|
||||
stella trust snapshot export --out ./bundle.tar.zst
|
||||
```
|
||||
|
||||
2. Transfer bundle to air-gapped system
|
||||
|
||||
3. Import on air-gapped system:
|
||||
```bash
|
||||
stella trust import ./bundle.tar.zst --offline
|
||||
```
|
||||
|
||||
4. Verify attestations using bundled trust:
|
||||
```bash
|
||||
stella attest verify ./attestation.json --offline
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "TUF metadata expired"
|
||||
|
||||
The timestamp hasn't been refreshed. On the TUF repository:
|
||||
```bash
|
||||
./scripts/update-timestamp.sh
|
||||
```
|
||||
|
||||
### "Unknown target"
|
||||
|
||||
The requested target doesn't exist in the repository:
|
||||
```bash
|
||||
./scripts/add-target.sh /path/to/target target-name
|
||||
```
|
||||
|
||||
### "Signature verification failed"
|
||||
|
||||
Keys may have rotated. Force a sync:
|
||||
```bash
|
||||
stella trust sync --force
|
||||
```
|
||||
|
||||
### "Service map not found"
|
||||
|
||||
Ensure the service map target name matches configuration:
|
||||
```bash
|
||||
stella trust status # Check service_map_target value
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Root Key Security**: Keep root key offline. Only use for initial setup and rotations.
|
||||
|
||||
2. **Timestamp Automation**: Automate timestamp updates but use short-lived credentials.
|
||||
|
||||
3. **Monitoring**: Monitor for failed TUF fetches - may indicate MITM or repository issues.
|
||||
|
||||
4. **Rollback Protection**: TUF prevents rollback attacks through version tracking.
|
||||
|
||||
5. **Freshness**: Configure appropriate freshness thresholds for your security requirements.
|
||||
|
||||
## References
|
||||
|
||||
- [TUF Specification](https://theupdateframework.github.io/specification/latest/)
|
||||
- [Sigstore Trust Root](https://github.com/sigstore/root-signing)
|
||||
- [StellaOps Trust Repository Template](../../../devops/trust-repo-template/)
|
||||
Reference in New Issue
Block a user