stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/operations/bootstrap-guide.md

5.8 KiB
Raw Permalink Blame History

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

# 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)

# 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):

# 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

# 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

# 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

# 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)

# 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:

stella trust snapshot export \
  --include-tiles \
  --out trust-bundle-$(date +%Y-%m-%d).tar.zst

Transfer and Import (Air-Gapped System)

# 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

# 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:

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:

stella trust status --show-keys

Offline: "Bundle is stale"

The trust bundle exceeds the staleness threshold. Obtain a fresh bundle from a connected system:

# 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:

# 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