git.stella-ops.org/docs/modules/cli/guides/attest.md

CLI Attest Guide (DOCS-ATTEST-74-004)

How to verify and inspect attestations via CLI.

Verify DSSE

stella attest verify --envelope bundle.dsse.json --policy policy.json \
  --root keys/root.pem --transparency-checkpoint checkpoints/rekor.json

• Offline verification uses bundled roots and checkpoints; transparency optional.

List attestations

stella attest list --tenant default --issuer dev-kms --format table

Show attestation

stella attest show --id a1b2c3 --output json

---

Verify Offline (Air-Gapped Environments)

Verify attestation bundles completely offline without network access.

Synopsis

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

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

   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:

   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

# .github/workflows/verify-attestation.yml
name: Verify Attestation

on:
  workflow_dispatch:
    inputs:
      artifact_path:
        description: 'Path to artifact with attestation'
        required: true

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: signed-artifact
          path: ./artifacts

      - name: Install StellaOps CLI
        run: |
          dotnet tool install --global StellaOps.Cli

      - name: Verify attestation
        run: |
          stella attest verify \
            --envelope ./artifacts/attestation.dsse.json \
            --policy ./policy/verify-policy.json \
            --root ./keys/trusted-root.pem \
            --output ./verification-report.json

      - name: Upload verification report
        uses: actions/upload-artifact@v4
        with:
          name: verification-report
          path: ./verification-report.json

GitLab CI

# .gitlab-ci.yml
verify-attestation:
  stage: verify
  image: mcr.microsoft.com/dotnet/sdk:10.0
  before_script:
    - dotnet tool install --global StellaOps.Cli
    - export PATH="$PATH:$HOME/.dotnet/tools"
  script:
    - |
      stella attest verify \
        --envelope ./artifacts/attestation.dsse.json \
        --policy ./policy/verify-policy.json \
        --root ./keys/trusted-root.pem \
        --output ./verification-report.json
  artifacts:
    paths:
      - verification-report.json
    expire_in: 1 week
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Notes

• No network access required in sealed mode.
• All commands emit deterministic JSON; timestamps in UTC.
• Exit codes: 0 success, 2 verification failed, 4 input error.