audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories
This commit is contained in:
master
204
docs/modules/cli/guides/commands/seal.md
Normal file
204
docs/modules/cli/guides/commands/seal.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
stella seal sha256:abc123def456...
|
||||
```
|
||||
|
||||
##### Seal specific facets
|
||||
|
||||
```bash
|
||||
stella seal myregistry.io/app:v1.0 --facets runtime,config
|
||||
```
|
||||
|
||||
##### Output to file
|
||||
|
||||
```bash
|
||||
stella seal myregistry.io/app:v1.0 --output seal.json
|
||||
```
|
||||
|
||||
##### Seal without storing remotely
|
||||
|
||||
```bash
|
||||
stella seal sha256:abc123 --no-store --output local-seal.json
|
||||
```
|
||||
|
||||
##### Seal with custom signing key
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```yaml
|
||||
- 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
|
||||
|
||||
```yaml
|
||||
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](../admin/admission-webhook.md) for setup details.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Facet Drift Analysis](./facet-drift.md)
|
||||
- [VEX Generation from Drift](./vex.md#stella-vex-gen---from-drift)
|
||||
- [Admission Webhook](../admin/admission-webhook.md)
|
||||
Reference in New Issue
Block a user