fix tests. new product advisories enhancements
This commit is contained in:
master
248
docs/operations/bootstrap-guide.md
Normal file
248
docs/operations/bootstrap-guide.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# StellaOps Trust Bootstrap Guide
|
||||
|
||||
> Sprint: SPRINT_20260125_003 - WORKFLOW-001
|
||||
> Last updated: 2026-01-25
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers the initial trust setup for a new StellaOps deployment. Trust
|
||||
bootstrap establishes the cryptographic foundations for secure attestation and
|
||||
verification.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- StellaOps CLI installed (`stella` command available)
|
||||
- Network access to TUF repository (or offline trust bundle)
|
||||
- Sufficient permissions to create keys in `/etc/stellaops/keys/`
|
||||
- For keyless mode: OIDC identity provider configured
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Online Bootstrap
|
||||
|
||||
```bash
|
||||
# Initialize trust from organization's TUF repository
|
||||
./devops/scripts/bootstrap-trust.sh \
|
||||
--tuf-url https://trust.example.com/tuf/ \
|
||||
--pin rekor-key-v1
|
||||
```
|
||||
|
||||
### Offline Bootstrap (Air-Gapped)
|
||||
|
||||
```bash
|
||||
# Import pre-packaged trust bundle
|
||||
./devops/scripts/bootstrap-trust-offline.sh \
|
||||
/media/usb/trust-bundle-2026-01-25.tar.zst
|
||||
```
|
||||
|
||||
## Detailed Steps
|
||||
|
||||
### Step 1: Generate Signing Keys (Optional)
|
||||
|
||||
If using local signing keys (not keyless/OIDC):
|
||||
|
||||
```bash
|
||||
# Create key directory
|
||||
mkdir -p /etc/stellaops/keys
|
||||
chmod 700 /etc/stellaops/keys
|
||||
|
||||
# Generate ECDSA P-256 signing key
|
||||
stella keys generate \
|
||||
--type ecdsa-p256 \
|
||||
--out /etc/stellaops/keys/signing-key.pem
|
||||
|
||||
# Or use OpenSSL
|
||||
openssl ecparam -name prime256v1 -genkey -noout \
|
||||
-out /etc/stellaops/keys/signing-key.pem
|
||||
chmod 600 /etc/stellaops/keys/signing-key.pem
|
||||
```
|
||||
|
||||
### Step 2: Initialize TUF Client
|
||||
|
||||
```bash
|
||||
# Initialize with your organization's TUF repository
|
||||
stella trust init \
|
||||
--tuf-url https://trust.example.com/tuf/ \
|
||||
--service-map sigstore-services-v1 \
|
||||
--pin rekor-key-v1 rekor-key-v2
|
||||
|
||||
# Verify initialization
|
||||
stella trust status
|
||||
```
|
||||
|
||||
The `--pin` option specifies which Rekor keys to trust. Pin multiple keys during
|
||||
rotation periods.
|
||||
|
||||
### Step 3: Verify TUF Metadata
|
||||
|
||||
```bash
|
||||
# Check trust status
|
||||
stella trust status --show-keys --show-endpoints
|
||||
|
||||
# Expected output:
|
||||
# TUF Repository: https://trust.example.com/tuf/
|
||||
# Service Map: sigstore-services-v1
|
||||
# Trusted Keys:
|
||||
# - rekor-key-v1 (expires: 2027-01-01)
|
||||
# - rekor-key-v2 (expires: 2028-01-01)
|
||||
# Endpoints:
|
||||
# - Rekor: https://rekor.sigstore.dev
|
||||
# - Fulcio: https://fulcio.sigstore.dev
|
||||
```
|
||||
|
||||
### Step 4: Test Sign/Verify Cycle
|
||||
|
||||
```bash
|
||||
# Create a test payload
|
||||
echo "StellaOps bootstrap test" > /tmp/test-payload.txt
|
||||
|
||||
# Sign with your key
|
||||
stella sign /tmp/test-payload.txt \
|
||||
--key /etc/stellaops/keys/signing-key.pem \
|
||||
--out /tmp/test.sig
|
||||
|
||||
# Verify signature
|
||||
stella verify /tmp/test-payload.txt \
|
||||
--sig /tmp/test.sig
|
||||
|
||||
# Clean up
|
||||
rm /tmp/test-payload.txt /tmp/test.sig
|
||||
```
|
||||
|
||||
### Step 5: Test Rekor Submission (Online Only)
|
||||
|
||||
```bash
|
||||
# Create and submit an attestation
|
||||
stella attest create /tmp/test-payload.txt \
|
||||
--type stellaops.io/predicates/test@v1 \
|
||||
--rekor-submit
|
||||
|
||||
# Verify inclusion in transparency log
|
||||
stella attest verify /tmp/test-payload.txt \
|
||||
--check-inclusion
|
||||
```
|
||||
|
||||
## Offline Bootstrap
|
||||
|
||||
For air-gapped deployments without network access:
|
||||
|
||||
### Create Trust Bundle (Connected System)
|
||||
|
||||
On a system with network access, create a trust bundle:
|
||||
|
||||
```bash
|
||||
stella trust snapshot export \
|
||||
--include-tiles \
|
||||
--out trust-bundle-$(date +%Y-%m-%d).tar.zst
|
||||
```
|
||||
|
||||
### Transfer and Import (Air-Gapped System)
|
||||
|
||||
```bash
|
||||
# Transfer bundle via USB, DVD, or approved data diode
|
||||
# Then import:
|
||||
./devops/scripts/bootstrap-trust-offline.sh \
|
||||
/media/usb/trust-bundle-2026-01-25.tar.zst
|
||||
|
||||
# Optional: Reject stale bundles
|
||||
./devops/scripts/bootstrap-trust-offline.sh \
|
||||
/media/usb/trust-bundle-2026-01-25.tar.zst \
|
||||
--reject-if-stale 7d
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### TUF Client Configuration
|
||||
|
||||
After bootstrap, TUF client configuration is stored in:
|
||||
`~/.local/share/StellaOps/TufCache/`
|
||||
|
||||
Key files:
|
||||
- `root.json` - Root of trust (only updated via ceremony)
|
||||
- `targets.json` - List of trusted targets
|
||||
- `snapshot.json` - Point-in-time snapshot of targets
|
||||
- `timestamp.json` - Freshness guarantee (regularly updated)
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Override cache directory
|
||||
export STELLAOPS_TUF_CACHE=/custom/path
|
||||
|
||||
# Enable debug logging
|
||||
export STELLAOPS_LOG_LEVEL=debug
|
||||
|
||||
# Offline mode (no network calls)
|
||||
export STELLAOPS_OFFLINE=true
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "TUF metadata verification failed"
|
||||
|
||||
The TUF root key may have been rotated. Obtain the new root.json from your
|
||||
security team and re-bootstrap:
|
||||
|
||||
```bash
|
||||
stella trust init \
|
||||
--tuf-url https://trust.example.com/tuf/ \
|
||||
--root-json /path/to/new/root.json \
|
||||
--force
|
||||
```
|
||||
|
||||
### Error: "Rekor connectivity check failed"
|
||||
|
||||
1. Verify network access to Rekor endpoint
|
||||
2. Check firewall rules for HTTPS (port 443)
|
||||
3. Verify the Rekor URL in service map is correct
|
||||
4. Try forcing a sync: `stella trust sync --force`
|
||||
|
||||
### Error: "Key not found in trust store"
|
||||
|
||||
The pinned key may not exist in the TUF repository. Check available keys:
|
||||
|
||||
```bash
|
||||
stella trust status --show-keys
|
||||
```
|
||||
|
||||
### Offline: "Bundle is stale"
|
||||
|
||||
The trust bundle exceeds the staleness threshold. Obtain a fresh bundle from a
|
||||
connected system:
|
||||
|
||||
```bash
|
||||
# On connected system
|
||||
stella trust snapshot export --out fresh-bundle.tar.zst
|
||||
|
||||
# Transfer and import
|
||||
./devops/scripts/bootstrap-trust-offline.sh fresh-bundle.tar.zst
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Periodic Sync
|
||||
|
||||
Set up a cron job to keep TUF metadata fresh:
|
||||
|
||||
```bash
|
||||
# Every 6 hours
|
||||
0 */6 * * * /usr/local/bin/stella trust sync --quiet
|
||||
```
|
||||
|
||||
### Updating Air-Gap Bundles
|
||||
|
||||
For air-gapped systems, schedule regular bundle updates based on your
|
||||
organization's freshness requirements (typically 7-30 days).
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Configure CI/CD to use the signing key
|
||||
- Set up key rotation procedures (see `key-rotation-runbook.md`)
|
||||
- Configure monitoring for trust state freshness
|
||||
- For air-gap: Establish bundle transfer schedule
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [TUF Integration Guide](../modules/attestor/tuf-integration.md)
|
||||
- [Key Rotation Runbook](key-rotation-runbook.md)
|
||||
- [Disaster Recovery](disaster-recovery.md)
|
||||
Reference in New Issue
Block a user