sprints completion. new product advisories prepared
This commit is contained in:
master
@@ -19,6 +19,131 @@ stella attest list --tenant default --issuer dev-kms --format table
|
||||
stella attest show --id a1b2c3 --output json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verify Offline (Air-Gapped Environments)
|
||||
|
||||
Verify attestation bundles completely offline without network access.
|
||||
|
||||
### Synopsis
|
||||
|
||||
```bash
|
||||
stella attest verify-offline --bundle <path.tar.gz> [options]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Alias | Description |
|
||||
|--------|-------|-------------|
|
||||
| `--bundle <path>` | `-b` | **Required.** Path to attestation bundle (tar.gz). |
|
||||
| `--checkpoint <path>` | `-c` | Path to Rekor checkpoint signature file. |
|
||||
| `--trust-root <dir>` | `-r` | Path to trust root directory containing CA certificates. |
|
||||
| `--artifact <digest>` | `-a` | Expected artifact digest (sha256:...) to verify against. |
|
||||
| `--predicate-type <type>` | `-p` | Expected predicate type (e.g., https://slsa.dev/provenance/v1). |
|
||||
| `--output <file>` | `-o` | Write verification report to file instead of stdout. |
|
||||
| `--format <fmt>` | `-f` | Output format: `json`, `summary` (default), or `html`. |
|
||||
| `--strict` | | Fail if any optional verification step fails. |
|
||||
| `--verbose` | | Show detailed verification progress. |
|
||||
|
||||
### Verification Checks
|
||||
|
||||
The command performs the following verification checks:
|
||||
|
||||
1. **DSSE Envelope Signature**: Validates the DSSE envelope structure and signatures.
|
||||
2. **Merkle Inclusion Proof**: Verifies Rekor transparency log inclusion proof.
|
||||
3. **Checkpoint Signature**: Validates checkpoint signature against trusted keys.
|
||||
4. **Content Hash**: Ensures all file hashes match the manifest.
|
||||
|
||||
### Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Verification passed |
|
||||
| 1 | Verification failed (one or more checks failed) |
|
||||
| 2 | Error (file not found, parse error, etc.) |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Basic offline verification
|
||||
stella attest verify-offline --bundle evidence.tar.gz
|
||||
|
||||
# Full verification with all options
|
||||
stella attest verify-offline \
|
||||
--bundle evidence.tar.gz \
|
||||
--checkpoint checkpoint.sig \
|
||||
--trust-root /path/to/roots/ \
|
||||
--artifact sha256:abc123def456 \
|
||||
--predicate-type https://slsa.dev/provenance/v1
|
||||
|
||||
# Generate JSON verification report
|
||||
stella attest verify-offline \
|
||||
--bundle evidence.tar.gz \
|
||||
--format json \
|
||||
--output report.json
|
||||
|
||||
# Strict mode (fail on optional check failures)
|
||||
stella attest verify-offline --bundle evidence.tar.gz --strict
|
||||
```
|
||||
|
||||
### Sample Output
|
||||
|
||||
```
|
||||
Attestation Verification Report
|
||||
================================
|
||||
Bundle: evidence.tar.gz
|
||||
Status: VERIFIED
|
||||
|
||||
Checks:
|
||||
[PASS] DSSE envelope signature valid
|
||||
[PASS] Merkle inclusion proof verified (log index: 12345)
|
||||
[PASS] Checkpoint signature valid (origin: rekor.sigstore.dev)
|
||||
[PASS] Content hash matches manifest
|
||||
|
||||
Artifact: sha256:abc123...
|
||||
Signed by: identity@example.com
|
||||
Timestamp: 2026-01-14T10:30:00Z
|
||||
```
|
||||
|
||||
### Bundle Format
|
||||
|
||||
The attestation bundle should be a tar.gz archive containing:
|
||||
|
||||
```
|
||||
evidence.tar.gz
|
||||
├── attestation.dsse.json # DSSE envelope with signature
|
||||
├── manifest.json # File inventory with SHA-256 hashes
|
||||
├── metadata.json # Generation timestamp, tool versions
|
||||
├── certs/
|
||||
│ ├── signing-cert.pem # Signing certificate
|
||||
│ └── fulcio-root.pem # Fulcio root CA (optional)
|
||||
└── rekor-proof/ # Transparency log proof (optional)
|
||||
├── inclusion-proof.json
|
||||
└── checkpoint.sig
|
||||
```
|
||||
|
||||
### Air-Gap Workflow
|
||||
|
||||
1. **Export bundle** on connected system:
|
||||
```bash
|
||||
stella evidence export --scan-id <id> --output bundle.tar.gz
|
||||
```
|
||||
|
||||
2. **Transfer bundle** to air-gapped system via secure media.
|
||||
|
||||
3. **Verify offline** on air-gapped system:
|
||||
```bash
|
||||
stella attest verify-offline --bundle bundle.tar.gz --trust-root /roots/
|
||||
```
|
||||
|
||||
### Cross-Platform Determinism
|
||||
|
||||
The verification output is deterministic across platforms:
|
||||
- Line endings normalized to LF
|
||||
- Hex digests always lowercase
|
||||
- Timestamps in ISO 8601 UTC format
|
||||
- Paths use forward slashes
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
- `stella sbom generate --image <ref> [--output sbom.spdx.json] [--offline]`
|
||||
- `stella sbom compose --fragment <path> --output composition.json --offline`
|
||||
- `stella sbom verify --file <sbom> --signature <sig> --key <keyfile>`
|
||||
- `stella sbom verify --archive <path.tar.gz> [--offline] [--trust-root <dir>]` — Verify signed SBOM archive
|
||||
|
||||
## Flags (common)
|
||||
- `--offline`: no network pulls; use local cache/OCI archive.
|
||||
@@ -23,3 +24,114 @@
|
||||
## Offline/air-gap notes
|
||||
- With `--offline`, image sources must already be cached (tar/OCI archive); command fails with exit code 5 if it would fetch remotely.
|
||||
- Verification uses local trust roots; no remote key fetch.
|
||||
|
||||
---
|
||||
|
||||
## stella sbom verify — Signed Archive Verification
|
||||
|
||||
### Synopsis
|
||||
|
||||
```bash
|
||||
stella sbom verify --archive <path.tar.gz> [options]
|
||||
```
|
||||
|
||||
Verify a signed SBOM archive (tar.gz) containing SBOM, DSSE envelope, manifest, and verification materials.
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Alias | Description |
|
||||
|--------|-------|-------------|
|
||||
| `--archive <path>` | `-a` | **Required.** Path to signed SBOM archive (tar.gz). |
|
||||
| `--offline` | | Perform offline verification using bundled certificates. |
|
||||
| `--trust-root <dir>` | `-r` | Path to trust root directory containing CA certificates. |
|
||||
| `--output <file>` | `-o` | Write verification report to file instead of stdout. |
|
||||
| `--format <fmt>` | `-f` | Output format: `json`, `summary` (default), or `html`. |
|
||||
| `--strict` | | Fail if any optional verification step fails. |
|
||||
| `--verbose` | | Show detailed verification progress. |
|
||||
|
||||
### Verification Checks
|
||||
|
||||
The command performs the following verification checks:
|
||||
|
||||
1. **Archive Integrity**: Validates all file hashes against `manifest.json`.
|
||||
2. **DSSE Envelope Signature**: Verifies the DSSE envelope structure and signatures.
|
||||
3. **SBOM Schema**: Validates SBOM content against SPDX or CycloneDX schemas.
|
||||
4. **Tool Version**: Verifies tool version metadata is present and valid.
|
||||
5. **Timestamp Validity**: Checks generation timestamp is within acceptable window.
|
||||
|
||||
### Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Verification passed |
|
||||
| 1 | Verification failed (one or more checks failed) |
|
||||
| 2 | Error (file not found, parse error, etc.) |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Verify a signed SBOM archive with summary output
|
||||
stella sbom verify --archive signed-sbom-sha256-abc123.tar.gz
|
||||
|
||||
# Verify offline with custom trust root
|
||||
stella sbom verify --archive signed-sbom.tar.gz --offline --trust-root /path/to/roots/
|
||||
|
||||
# Generate JSON verification report
|
||||
stella sbom verify --archive signed-sbom.tar.gz --format json --output report.json
|
||||
|
||||
# Generate HTML report for sharing
|
||||
stella sbom verify --archive signed-sbom.tar.gz --format html --output report.html
|
||||
|
||||
# Strict mode (fail on optional check failures)
|
||||
stella sbom verify --archive signed-sbom.tar.gz --strict
|
||||
```
|
||||
|
||||
### Sample Output
|
||||
|
||||
```
|
||||
SBOM Verification Report
|
||||
========================
|
||||
Archive: signed-sbom-sha256-abc123.tar.gz
|
||||
Status: VERIFIED
|
||||
|
||||
Checks:
|
||||
[PASS] Archive integrity (All 4 file hashes verified)
|
||||
[PASS] DSSE envelope signature (Valid, 1 signature(s))
|
||||
[PASS] SBOM schema (Valid, SPDX 2.3)
|
||||
[PASS] Tool version (Suite: 2027.Q1, Scanner: 1.2.3)
|
||||
[PASS] Timestamp validity (Within validity window, 2026-01-15)
|
||||
|
||||
SBOM Details:
|
||||
Format: SPDX 2.3
|
||||
Components: 142
|
||||
Artifact: sha256:abc123def456
|
||||
Generated: 2026-01-15T10:30:00Z
|
||||
Tool: StellaOps Scanner v2027.Q1
|
||||
```
|
||||
|
||||
### Archive Format
|
||||
|
||||
The signed SBOM archive follows the format defined in `SPRINT_20260112_016_SCANNER_signed_sbom_archive_spec`:
|
||||
|
||||
```
|
||||
signed-sbom-{digest}-{timestamp}.tar.gz
|
||||
├── sbom.spdx.json (or sbom.cdx.json)
|
||||
├── sbom.dsse.json
|
||||
├── manifest.json
|
||||
├── metadata.json
|
||||
├── certs/
|
||||
│ ├── signing-cert.pem
|
||||
│ └── fulcio-root.pem
|
||||
├── rekor-proof/
|
||||
│ ├── inclusion-proof.json
|
||||
│ └── checkpoint.sig
|
||||
├── schemas/
|
||||
│ └── ...
|
||||
└── VERIFY.md
|
||||
```
|
||||
|
||||
### Related Commands
|
||||
|
||||
- `stella sbom generate` — Generate SBOM from container image
|
||||
- `stella attest verify --offline` — Verify attestation bundles offline
|
||||
- `stella evidence export` — Export evidence bundle with signed SBOM
|
||||
|
||||
@@ -38,3 +38,113 @@ observability:
|
||||
|
||||
## Profiles (planned)
|
||||
- Profiles will live under `profiles/<name>.yaml` and can be selected with `--profile <name>`; until shipped, stick to the single default config file.
|
||||
|
||||
---
|
||||
|
||||
## Config Inspection Commands
|
||||
|
||||
> **Sprint:** SPRINT_20260112_014_CLI_config_viewer
|
||||
|
||||
The CLI provides unified config inspection across all StellaOps modules.
|
||||
|
||||
### List All Config Paths
|
||||
|
||||
```bash
|
||||
# List all supported config paths
|
||||
stella config list
|
||||
|
||||
# Output:
|
||||
# Path Alias Module
|
||||
# ────────────────────────────────────────────────────────────────────────
|
||||
# policy.determinization policy:determinization Policy
|
||||
# policy.confidenceweights policy:weights Policy
|
||||
# scanner scanner Scanner
|
||||
# scanner.reachability.prgate scanner:prgate Scanner
|
||||
# attestor.rekor attestor:rekor Attestor
|
||||
# signals.evidenceweightedscore signals:ews Signals
|
||||
# ...
|
||||
|
||||
# Filter by module
|
||||
stella config list --module policy
|
||||
|
||||
# Output as JSON
|
||||
stella config list --output json
|
||||
```
|
||||
|
||||
### Show Effective Config
|
||||
|
||||
```bash
|
||||
# Show effective config for a path
|
||||
stella config policy.determinization show
|
||||
|
||||
# Output:
|
||||
# Effective Determinization Config
|
||||
# ─────────────────────────────────
|
||||
# Source: Service (api/v1/policy/config/determinization)
|
||||
#
|
||||
# Reanalysis Triggers:
|
||||
# epssDeltaThreshold: 0.2
|
||||
# triggerOnThresholdCrossing: true
|
||||
# triggerOnRekorEntry: true
|
||||
# triggerOnVexStatusChange: true
|
||||
# triggerOnRuntimeTelemetryChange: true
|
||||
# triggerOnPatchProofAdded: true
|
||||
# triggerOnDsseValidationChange: true
|
||||
# triggerOnToolVersionChange: false
|
||||
#
|
||||
# Conflict Handling:
|
||||
# vexReachabilityContradiction: RequireManualReview
|
||||
# ...
|
||||
|
||||
# Use path alias
|
||||
stella config policy:determinization show
|
||||
|
||||
# Output as JSON
|
||||
stella config policy.determinization show --output json
|
||||
|
||||
# Show from config file (bypass service)
|
||||
stella config policy.determinization show --config /etc/stella/config.yaml
|
||||
```
|
||||
|
||||
### Config Path Normalization
|
||||
|
||||
Path matching is case-insensitive with flexible separators:
|
||||
|
||||
| Input | Normalized | Valid |
|
||||
|-------|------------|-------|
|
||||
| `policy.determinization` | `policy.determinization` | ✓ |
|
||||
| `Policy:Determinization` | `policy.determinization` | ✓ |
|
||||
| `POLICY.DETERMINIZATION` | `policy.determinization` | ✓ |
|
||||
| `policy:determinization` | `policy.determinization` | ✓ |
|
||||
|
||||
### Secret Redaction
|
||||
|
||||
Secrets are automatically redacted in config output:
|
||||
|
||||
```bash
|
||||
stella config database show
|
||||
|
||||
# Output:
|
||||
# database:
|
||||
# host: pg.stella.local
|
||||
# port: 5432
|
||||
# database: stella
|
||||
# username: stella_app
|
||||
# password: ******** # Redacted
|
||||
# connectionString: ******** # Redacted
|
||||
```
|
||||
|
||||
### Popular Config Paths
|
||||
|
||||
| Path | Description |
|
||||
|------|-------------|
|
||||
| `policy.determinization` | Determinization triggers and thresholds |
|
||||
| `policy.confidenceweights` | Evidence confidence weight values |
|
||||
| `scanner` | Core scanner settings |
|
||||
| `attestor.rekor` | Rekor transparency log settings |
|
||||
| `signals.evidenceweightedscore` | EWS calculation settings |
|
||||
| `excititor.mirror` | VEX mirror configuration |
|
||||
| `airgap.bundlesigning` | Offline kit bundle signing |
|
||||
| `signer.keyless` | Sigstore keyless signing |
|
||||
|
||||
See the full config inventory in `docs/implplan/SPRINT_20260112_014_CLI_config_viewer.md`.
|
||||
|
||||
Reference in New Issue
Block a user