stella seal — Command Guide

Audience: DevOps engineers and release operators who need tamper-evident baselines for container images. Scope: The stella seal command — creating signed facet seals that capture the state of specific file categories within an image for drift detection.

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, and so on) within an image and produces Merkle roots used 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

stella seal sha256:abc123def456...

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

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

Enforcement Integration

Facet seals are designed to gate deployments. The earlier Kubernetes admission-webhook flow that consumed facet seals is retired; Stella Ops is a non-Kubernetes release control plane, so seal enforcement now runs through the supported release/host-agent path. The enforcement logic is the same regardless of integration point:

Determine whether the image requires a seal (e.g. via a release-policy flag).
Load the seal for the image being deployed.
Verify the seal signature.
Compute drift against the current image state.
Admit or reject the deployment based on the resulting verdict.

See Admission Webhook Configuration for the retired-webhook reference and the supported enforcement path.