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

stella seal - Command Guide

Sprint: SPRINT_20260105_002_004_CLI Task: CLI-016 - Facet seal command documentation

Overview

The stella seal command creates cryptographic seals for container image facets. A facet seal captures the state of specific file categories (binaries, libraries, configs, etc.) within an image and produces Merkle roots for tamper detection and drift analysis.

Commands

stella seal

Create a facet seal for an image.

stella seal <IMAGE> [OPTIONS]

Arguments

Argument	Description
IMAGE	Image reference or digest to seal (required)

Options

Option	Alias	Description	Default
--output <PATH>	-o	Output file path for seal	stdout
--store	-s	Store seal in remote API	true
--sign		Sign seal with DSSE	true
--key <PATH>	-k	Private key path for signing	configured key
--facets <LIST>	-f	Specific facets to seal (comma-separated)	all
--format <FMT>		Output format: json, yaml, compact	json
--verbose	-v	Enable verbose output	false

Examples

Seal all facets

stella seal sha256:abc123def456...

Seal specific facets

stella seal myregistry.io/app:v1.0 --facets runtime,config

Output to file

stella seal myregistry.io/app:v1.0 --output seal.json

Seal without storing remotely

stella seal sha256:abc123 --no-store --output local-seal.json

Seal with custom signing key

stella seal sha256:abc123 --key /path/to/private.key

---

Built-in Facets

Facet ID	Name	Description	File Patterns
runtime	Runtime Binaries	Executable binaries and shared libraries	*.so, *.dll, /usr/bin/*
config	Configuration	Configuration files	*.conf, *.yaml, *.json, /etc/*
static	Static Assets	Static web assets	*.css, *.js, *.html
scripts	Scripts	Script files	*.sh, *.py, *.rb
data	Data Files	Data and cache files	*.db, *.sqlite, /var/lib/*

---

Output Formats

JSON Format (Default)

{
  "imageDigest": "sha256:abc123...",
  "createdAt": "2026-01-05T10:30:00Z",
  "combinedMerkleRoot": "sha256:combined...",
  "facets": [
    {
      "facetId": "runtime",
      "name": "Runtime Binaries",
      "merkleRoot": "sha256:facet...",
      "fileCount": 42,
      "totalBytes": 15728640
    }
  ],
  "signature": {
    "payloadType": "application/vnd.stellaops.facetseal+json",
    "signatures": [...]
  }
}

YAML Format

imageDigest: sha256:abc123...
createdAt: 2026-01-05T10:30:00Z
combinedMerkleRoot: sha256:combined...
facets:
  - facetId: runtime
    merkleRoot: sha256:facet...
    fileCount: 42

Compact Format

Single-line format for scripting:

sha256:abc123...|sha256:combined...|5

Format: imageDigest|combinedRoot|facetCount

---

Exit Codes

Code	Description
0	Success
1	General error
2	Image resolution failed
3	Signing failed
4	Storage failed

---

Environment Variables

Variable	Description
STELLAOPS_BACKEND_URL	Backend API URL for seal storage
STELLAOPS_SIGNING_KEY	Default signing key path
STELLAOPS_TRUST_ROOTS	Trust roots for verification

---

CI/CD Integration

GitHub Actions

- name: Seal Container Image
  run: |
    stella seal ${{ env.IMAGE_DIGEST }} \
      --output seal.json \
      --store

- name: Upload Seal Artifact
  uses: actions/upload-artifact@v4
  with:
    name: facet-seal
    path: seal.json

GitLab CI

seal-image:
  script:
    - stella seal $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --output seal.json
  artifacts:
    paths:
      - seal.json

---

Admission Integration

When Kubernetes admission is configured with facet seal validation, the webhook will:

1. Check if namespace has stellaops.io/facet-seal-required=true annotation
2. Load the seal for the image being deployed
3. Verify the seal signature
4. Compute drift against current image state
5. Admit/reject based on quota verdicts

See Admission Webhook Configuration for setup details.

---

Related Documentation

• Facet Drift Analysis
• VEX Generation from Drift
• Admission Webhook