git.stella-ops.org/docs/operations/bootstrap-guide.md

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