Restructure solution layout by module
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
This commit is contained in:
root
@@ -1,208 +1,208 @@
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Task Pack Authoring Guide
|
||||
|
||||
This guide teaches engineers how to design, validate, and publish Task Packs that align with the Sprint 43 specification. Follow these steps to ensure deterministic behaviour, secure approvals, and smooth hand-off to operators.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Prerequisites
|
||||
|
||||
- StellaOps CLI `>= 2025.10.0` with pack commands enabled.
|
||||
- Authority client configured with `Packs.Write` (publish) and `Packs.Run` (local testing) scopes.
|
||||
- Access to Task Runner staging environment for validation runs.
|
||||
- Familiarity with the [Task Pack Specification](spec.md) and [Packs Registry](registry.md).
|
||||
- Optional: connection to DevOps staging registry or Offline Kit mirror for publishing.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Design Checklist
|
||||
|
||||
1. **Define objective.** Document the operational need, inputs, expected outputs, and rollback strategy.
|
||||
2. **Identify approvals.** Determine which scopes/roles must sign off (`Packs.Approve` assignments).
|
||||
3. **Plan security posture.** Limit secrets usage, set tenant visibility, and note network constraints (sealed mode).
|
||||
4. **Model observability.** Decide which metrics, logs, and evidence artifacts are critical for post-run audits.
|
||||
5. **Reuse libraries.** Prefer built-in modules or shared pack fragments to reduce drift.
|
||||
|
||||
Capture the above in `docs/summary.md` (optional but recommended) for future maintainers.
|
||||
|
||||
---
|
||||
|
||||
## 3 · Authoring Workflow
|
||||
|
||||
### 3.1 Scaffold project
|
||||
|
||||
```bash
|
||||
mkdir my-pack
|
||||
cd my-pack
|
||||
stella pack init --name sbom-remediation
|
||||
```
|
||||
|
||||
`stella pack init` creates baseline files:
|
||||
|
||||
- `pack.yaml` with metadata placeholders.
|
||||
- `schemas/inputs.schema.json` (sample).
|
||||
- `docs/usage.md` (template for human instructions).
|
||||
- `.packignore` to exclude build artifacts.
|
||||
|
||||
### 3.2 Define inputs & schemas
|
||||
|
||||
- Use JSON Schema (`draft-2020-12`) for input validation.
|
||||
- Avoid optional inputs unless there is a deterministic default.
|
||||
- Store schemas under `schemas/` and reference via relative paths.
|
||||
|
||||
### 3.3 Compose steps
|
||||
|
||||
- Break workflow into small deterministic steps.
|
||||
- Name each step with stable `id`.
|
||||
- Wrap scripts/tools using built-in modules; copy scripts to `assets/` if necessary.
|
||||
- Use `when` expressions for branch logic; ensure expressions rely solely on inputs or previous outputs.
|
||||
- For loops, adopt `map` with capped iteration count; avoid data-dependent randomness.
|
||||
|
||||
### 3.4 Configure approvals
|
||||
|
||||
- Add `spec.approvals` entries for each required review.
|
||||
- Provide informative `reasonTemplate` with placeholders.
|
||||
- Set `expiresAfter` to match operational policy (e.g., 4 h for security reviews).
|
||||
- Document fallback contacts in `docs/runbook.md`.
|
||||
|
||||
### 3.5 Manage secrets
|
||||
|
||||
- Declare secrets under `spec.secrets`.
|
||||
- Reference secrets via expressions (e.g., `{{ secrets.jiraToken.value }}`) inside modules that support secure injection.
|
||||
- Never bake secrets or tokens into pack assets.
|
||||
- If secret optional, set `optional: true` and handle absence in step logic.
|
||||
|
||||
### 3.6 Document outputs
|
||||
|
||||
- List expected artifacts under `spec.outputs`.
|
||||
- Include human-friendly docs (Markdown) describing each output and how to access it through CLI or Console.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Validation
|
||||
|
||||
### 4.1 Static validation
|
||||
|
||||
```bash
|
||||
stella pack validate
|
||||
```
|
||||
|
||||
Checks performed:
|
||||
|
||||
- Schema compliance (YAML, JSON Schema).
|
||||
- Determinism guard (forbidden functions, clock usage, network allowlist).
|
||||
- Reference integrity (assets, schemas, documentation).
|
||||
- Approval/secret scope availability.
|
||||
|
||||
### 4.2 Simulation & plan hash
|
||||
|
||||
```bash
|
||||
stella pack plan --inputs samples/inputs.json --output .artifacts/plan.json
|
||||
stella pack simulate --inputs samples/inputs.json --output .artifacts/sim.json
|
||||
```
|
||||
|
||||
- Review plan graph to ensure step ordering and gating align with expectations.
|
||||
- Store simulation output with pack metadata for future audits.
|
||||
|
||||
### 4.3 Local rehearsal
|
||||
|
||||
```bash
|
||||
stella pack run \
|
||||
--inputs samples/inputs.json \
|
||||
--secrets jiraToken=@secrets/jira.txt \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
- Use `--dry-run` to verify approvals and outputs without side effects.
|
||||
- Real runs require `Packs.Run` and all approval gates satisfied (e.g., via CLI prompts or Console).
|
||||
|
||||
### 4.4 Unit tests (optional but encouraged)
|
||||
|
||||
- Create a `tests/` folder with CLI-driven regression scripts (e.g., using `stella pack plan` + `jq` assertions).
|
||||
- Integrate into CI pipelines; ensure tests run offline using cached assets.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Publishing
|
||||
|
||||
### 5.1 Build bundle
|
||||
|
||||
```bash
|
||||
stella pack build \
|
||||
--output dist/sbom-remediation-1.3.0.stella-pack.tgz \
|
||||
--manifest pack.yaml
|
||||
```
|
||||
|
||||
### 5.2 Sign bundle
|
||||
|
||||
```bash
|
||||
cosign sign-blob \
|
||||
--yes \
|
||||
--output-signature dist/sbom-remediation-1.3.0.sig \
|
||||
dist/sbom-remediation-1.3.0.stella-pack.tgz
|
||||
```
|
||||
|
||||
Store signature alongside bundle; DSSE optional but recommended (see [security guidance](../security/pack-signing-and-rbac.md)).
|
||||
|
||||
### 5.3 Publish to registry
|
||||
|
||||
```bash
|
||||
stella pack push \
|
||||
registry.stella-ops.org/packs/sbom-remediation:1.3.0 \
|
||||
--bundle dist/sbom-remediation-1.3.0.stella-pack.tgz \
|
||||
--signature dist/sbom-remediation-1.3.0.sig
|
||||
```
|
||||
|
||||
Registry verifies signature, stores provenance, and updates index.
|
||||
|
||||
### 5.4 Offline distribution
|
||||
|
||||
- Export bundle + signature + provenance into Offline Kit using `stella pack bundle export`.
|
||||
- Update mirror manifest (`manifest/offline-manifest.json`) with new pack entries.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Versioning & Compatibility
|
||||
|
||||
- Follow SemVer (increment major when breaking schema/behaviour).
|
||||
- Document compatibility in `docs/compatibility.md` (recommended).
|
||||
- Registry retains immutable history; use `metadata.deprecated: true` to indicate retirement.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Best Practices
|
||||
|
||||
- **Keep steps idempotent.** Support manual retries without side effects.
|
||||
- **Surface evidence early.** Export intermediate artifacts (plans, logs) for operators.
|
||||
- **Localize messages.** Provide `locales/en-US.json` for CLI/Console strings (Sprint 43 requirement).
|
||||
- **Avoid long-running commands.** Split heavy tasks into smaller steps with progress telemetry.
|
||||
- **Guard network usage.** Use `when: "{{ env.isSealed }}"` to block disallowed network operations or provide offline instructions.
|
||||
- **Document fallbacks.** Include manual recovery instructions in `docs/runbook.md`.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Hand-off & Review
|
||||
|
||||
- Submit PR including pack bundle metadata, docs, and validation evidence.
|
||||
- Request review from Task Runner + Security + DevOps stakeholders.
|
||||
- Attach `stella pack plan` output and signature digest to review notes.
|
||||
- After approval, update change log (`docs/CHANGELOG.md`) and notify Task Runner operations.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Compliance Checklist
|
||||
|
||||
- [ ] Metadata, inputs, steps, approvals, secrets, and outputs defined per spec.
|
||||
- [ ] Schemas provided for all object inputs and outputs.
|
||||
- [ ] Determinism validation (`stella pack validate`) executed with evidence stored.
|
||||
- [ ] Plan + simulation artifacts committed in `.artifacts/` or CI evidence store.
|
||||
- [ ] Bundle signed (cosign/DSSE) and signature recorded.
|
||||
- [ ] Runbook and troubleshooting notes documented.
|
||||
- [ ] Offline distribution steps prepared (bundle export + manifest update).
|
||||
- [ ] Imposed rule reminder retained at top.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Task Pack Authoring Guide
|
||||
|
||||
This guide teaches engineers how to design, validate, and publish Task Packs that align with the Sprint 43 specification. Follow these steps to ensure deterministic behaviour, secure approvals, and smooth hand-off to operators.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Prerequisites
|
||||
|
||||
- StellaOps CLI `>= 2025.10.0` with pack commands enabled.
|
||||
- Authority client configured with `Packs.Write` (publish) and `Packs.Run` (local testing) scopes.
|
||||
- Access to Task Runner staging environment for validation runs.
|
||||
- Familiarity with the [Task Pack Specification](spec.md) and [Packs Registry](registry.md).
|
||||
- Optional: connection to DevOps staging registry or Offline Kit mirror for publishing.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Design Checklist
|
||||
|
||||
1. **Define objective.** Document the operational need, inputs, expected outputs, and rollback strategy.
|
||||
2. **Identify approvals.** Determine which scopes/roles must sign off (`Packs.Approve` assignments).
|
||||
3. **Plan security posture.** Limit secrets usage, set tenant visibility, and note network constraints (sealed mode).
|
||||
4. **Model observability.** Decide which metrics, logs, and evidence artifacts are critical for post-run audits.
|
||||
5. **Reuse libraries.** Prefer built-in modules or shared pack fragments to reduce drift.
|
||||
|
||||
Capture the above in `docs/summary.md` (optional but recommended) for future maintainers.
|
||||
|
||||
---
|
||||
|
||||
## 3 · Authoring Workflow
|
||||
|
||||
### 3.1 Scaffold project
|
||||
|
||||
```bash
|
||||
mkdir my-pack
|
||||
cd my-pack
|
||||
stella pack init --name sbom-remediation
|
||||
```
|
||||
|
||||
`stella pack init` creates baseline files:
|
||||
|
||||
- `pack.yaml` with metadata placeholders.
|
||||
- `schemas/inputs.schema.json` (sample).
|
||||
- `docs/usage.md` (template for human instructions).
|
||||
- `.packignore` to exclude build artifacts.
|
||||
|
||||
### 3.2 Define inputs & schemas
|
||||
|
||||
- Use JSON Schema (`draft-2020-12`) for input validation.
|
||||
- Avoid optional inputs unless there is a deterministic default.
|
||||
- Store schemas under `schemas/` and reference via relative paths.
|
||||
|
||||
### 3.3 Compose steps
|
||||
|
||||
- Break workflow into small deterministic steps.
|
||||
- Name each step with stable `id`.
|
||||
- Wrap scripts/tools using built-in modules; copy scripts to `assets/` if necessary.
|
||||
- Use `when` expressions for branch logic; ensure expressions rely solely on inputs or previous outputs.
|
||||
- For loops, adopt `map` with capped iteration count; avoid data-dependent randomness.
|
||||
|
||||
### 3.4 Configure approvals
|
||||
|
||||
- Add `spec.approvals` entries for each required review.
|
||||
- Provide informative `reasonTemplate` with placeholders.
|
||||
- Set `expiresAfter` to match operational policy (e.g., 4 h for security reviews).
|
||||
- Document fallback contacts in `docs/runbook.md`.
|
||||
|
||||
### 3.5 Manage secrets
|
||||
|
||||
- Declare secrets under `spec.secrets`.
|
||||
- Reference secrets via expressions (e.g., `{{ secrets.jiraToken.value }}`) inside modules that support secure injection.
|
||||
- Never bake secrets or tokens into pack assets.
|
||||
- If secret optional, set `optional: true` and handle absence in step logic.
|
||||
|
||||
### 3.6 Document outputs
|
||||
|
||||
- List expected artifacts under `spec.outputs`.
|
||||
- Include human-friendly docs (Markdown) describing each output and how to access it through CLI or Console.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Validation
|
||||
|
||||
### 4.1 Static validation
|
||||
|
||||
```bash
|
||||
stella pack validate
|
||||
```
|
||||
|
||||
Checks performed:
|
||||
|
||||
- Schema compliance (YAML, JSON Schema).
|
||||
- Determinism guard (forbidden functions, clock usage, network allowlist).
|
||||
- Reference integrity (assets, schemas, documentation).
|
||||
- Approval/secret scope availability.
|
||||
|
||||
### 4.2 Simulation & plan hash
|
||||
|
||||
```bash
|
||||
stella pack plan --inputs samples/inputs.json --output .artifacts/plan.json
|
||||
stella pack simulate --inputs samples/inputs.json --output .artifacts/sim.json
|
||||
```
|
||||
|
||||
- Review plan graph to ensure step ordering and gating align with expectations.
|
||||
- Store simulation output with pack metadata for future audits.
|
||||
|
||||
### 4.3 Local rehearsal
|
||||
|
||||
```bash
|
||||
stella pack run \
|
||||
--inputs samples/inputs.json \
|
||||
--secrets jiraToken=@secrets/jira.txt \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
- Use `--dry-run` to verify approvals and outputs without side effects.
|
||||
- Real runs require `Packs.Run` and all approval gates satisfied (e.g., via CLI prompts or Console).
|
||||
|
||||
### 4.4 Unit tests (optional but encouraged)
|
||||
|
||||
- Create a `tests/` folder with CLI-driven regression scripts (e.g., using `stella pack plan` + `jq` assertions).
|
||||
- Integrate into CI pipelines; ensure tests run offline using cached assets.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Publishing
|
||||
|
||||
### 5.1 Build bundle
|
||||
|
||||
```bash
|
||||
stella pack build \
|
||||
--output dist/sbom-remediation-1.3.0.stella-pack.tgz \
|
||||
--manifest pack.yaml
|
||||
```
|
||||
|
||||
### 5.2 Sign bundle
|
||||
|
||||
```bash
|
||||
cosign sign-blob \
|
||||
--yes \
|
||||
--output-signature dist/sbom-remediation-1.3.0.sig \
|
||||
dist/sbom-remediation-1.3.0.stella-pack.tgz
|
||||
```
|
||||
|
||||
Store signature alongside bundle; DSSE optional but recommended (see [security guidance](../security/pack-signing-and-rbac.md)).
|
||||
|
||||
### 5.3 Publish to registry
|
||||
|
||||
```bash
|
||||
stella pack push \
|
||||
registry.stella-ops.org/packs/sbom-remediation:1.3.0 \
|
||||
--bundle dist/sbom-remediation-1.3.0.stella-pack.tgz \
|
||||
--signature dist/sbom-remediation-1.3.0.sig
|
||||
```
|
||||
|
||||
Registry verifies signature, stores provenance, and updates index.
|
||||
|
||||
### 5.4 Offline distribution
|
||||
|
||||
- Export bundle + signature + provenance into Offline Kit using `stella pack bundle export`.
|
||||
- Update mirror manifest (`manifest/offline-manifest.json`) with new pack entries.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Versioning & Compatibility
|
||||
|
||||
- Follow SemVer (increment major when breaking schema/behaviour).
|
||||
- Document compatibility in `docs/compatibility.md` (recommended).
|
||||
- Registry retains immutable history; use `metadata.deprecated: true` to indicate retirement.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Best Practices
|
||||
|
||||
- **Keep steps idempotent.** Support manual retries without side effects.
|
||||
- **Surface evidence early.** Export intermediate artifacts (plans, logs) for operators.
|
||||
- **Localize messages.** Provide `locales/en-US.json` for CLI/Console strings (Sprint 43 requirement).
|
||||
- **Avoid long-running commands.** Split heavy tasks into smaller steps with progress telemetry.
|
||||
- **Guard network usage.** Use `when: "{{ env.isSealed }}"` to block disallowed network operations or provide offline instructions.
|
||||
- **Document fallbacks.** Include manual recovery instructions in `docs/runbook.md`.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Hand-off & Review
|
||||
|
||||
- Submit PR including pack bundle metadata, docs, and validation evidence.
|
||||
- Request review from Task Runner + Security + DevOps stakeholders.
|
||||
- Attach `stella pack plan` output and signature digest to review notes.
|
||||
- After approval, update change log (`docs/CHANGELOG.md`) and notify Task Runner operations.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Compliance Checklist
|
||||
|
||||
- [ ] Metadata, inputs, steps, approvals, secrets, and outputs defined per spec.
|
||||
- [ ] Schemas provided for all object inputs and outputs.
|
||||
- [ ] Determinism validation (`stella pack validate`) executed with evidence stored.
|
||||
- [ ] Plan + simulation artifacts committed in `.artifacts/` or CI evidence store.
|
||||
- [ ] Bundle signed (cosign/DSSE) and signature recorded.
|
||||
- [ ] Runbook and troubleshooting notes documented.
|
||||
- [ ] Offline distribution steps prepared (bundle export + manifest update).
|
||||
- [ ] Imposed rule reminder retained at top.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
|
||||
@@ -1,174 +1,174 @@
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Packs Registry Architecture & Operations
|
||||
|
||||
The Packs Registry stores, verifies, and serves Task Pack bundles across environments. It integrates with Authority for RBAC, Task Runner for execution, DevOps for release automation, and Offline Kit for air-gapped distribution.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Service Overview
|
||||
|
||||
- **Service name:** `StellaOps.PacksRegistry`
|
||||
- **Interfaces:** REST/GraphQL API, OCI-compatible registry endpoints, event streams for mirroring.
|
||||
- **Data stores:** MongoDB (`packs`, `pack_versions`, `pack_provenance`), object storage (bundle blobs, signatures), timeline events.
|
||||
- **Dependencies:** Authority scopes (`Packs.*`), Export Center (manifests), DevOps signing service, Notifications (optional).
|
||||
|
||||
---
|
||||
|
||||
## 2 · Core Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| **Pack record** | Immutable entry representing a pack version; includes metadata, digest, signatures, tenant visibility. |
|
||||
| **Channel** | Logical distribution channel (`stable`, `edge`, `beta`, custom). Controls mirroring/promotion flows. |
|
||||
| **Provenance** | DSSE statements + SBOM linking pack bundle to source repo, CLI build, and Task Runner compatibility. |
|
||||
| **Mirroring policy** | Rules specifying which packs replicate to downstream registries or Offline Kit bundles. |
|
||||
| **Audit trail** | Append-only log capturing publish/update/delete actions, approvals, and policy evaluations. |
|
||||
|
||||
---
|
||||
|
||||
## 3 · API Surface
|
||||
|
||||
### 3.1 REST Endpoints
|
||||
|
||||
| Method | Path | Description | Scopes |
|
||||
|--------|------|-------------|--------|
|
||||
| `GET` | `/api/packs` | List packs with filters (`name`, `channel`, `tenant`, `tag`). | `Packs.Read` |
|
||||
| `GET` | `/api/packs/{packId}/versions` | List versions with metadata, provenance. | `Packs.Read` |
|
||||
| `GET` | `/api/packs/{packId}/versions/{version}` | Retrieve manifest, signatures, compatibility matrix. | `Packs.Read` |
|
||||
| `POST` | `/api/packs/{packId}/versions` | Publish new version (bundle upload or OCI reference). | `Packs.Write` |
|
||||
| `POST` | `/api/packs/{packId}/promote` | Promote version between channels (edge→stable). | `Packs.Write` + approval policy |
|
||||
| `DELETE` | `/api/packs/{packId}/versions/{version}` | Deprecate version (soft delete, immutability preserved). | `Packs.Write` |
|
||||
| `GET` | `/api/packs/{packId}/events` | Stream audit events (SSE). | `Packs.Read` |
|
||||
|
||||
### 3.2 OCI Endpoints
|
||||
|
||||
The registry exposes OCI-compatible endpoints (`/v2/<namespace>/<pack>/...`) supporting:
|
||||
|
||||
- `PUT`/`PATCH`/`GET` for manifests and blobs.
|
||||
- Content-addressed digests using SHA-256.
|
||||
- Annotations for pack metadata (`org.opencontainers.image.title`, `io.stellaops.pack.metadata`).
|
||||
|
||||
### 3.3 GraphQL (Optional)
|
||||
|
||||
GraphQL endpoint (`/api/graphql`) enables advanced queries (filter by approvals, tags, compatibility). Under active development; reference API schema once published.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Publishing Workflow
|
||||
|
||||
1. CLI/CI calls `POST /api/packs/{id}/versions` with signed bundle.
|
||||
2. Registry verifies:
|
||||
- Manifest schema compliance.
|
||||
- Signature (cosign/DSSE) validity.
|
||||
- Authority scopes (`Packs.Write`).
|
||||
- Tenant visibility constraints.
|
||||
3. On success, registry stores bundle, provenance, and emits event (`pack.version.published`).
|
||||
4. Optional promotion requires additional approvals or integration with DevOps release boards.
|
||||
|
||||
All actions recorded in audit log:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "evt_01HF...",
|
||||
"type": "pack.version.published",
|
||||
"packId": "sbom-remediation",
|
||||
"version": "1.3.0",
|
||||
"actor": "user:alice",
|
||||
"tenant": "west-prod",
|
||||
"source": "cli/2025.10.0",
|
||||
"signatures": ["sha256:..."],
|
||||
"metadataHash": "sha256:..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5 · Mirroring & Offline Support
|
||||
|
||||
- **Automatic mirroring:** Configure policies to push packs to secondary registries (edge clusters, regional mirrors) or object stores.
|
||||
- **Offline Kit integration:** `ops/offline-kit` pipeline pulls packs matching specified channels and writes them to `offline/packs/manifest.json` with signatures.
|
||||
- **Checksum manifest:** Registry maintains `digestmap.json` listing pack digests + signatures; offline installers verify before import.
|
||||
- **Sealed mode:** Registry can operate in read-only mode for sealed environments; publishing disabled except via offline import command (`stella pack mirror import`).
|
||||
|
||||
---
|
||||
|
||||
## 6 · Security & Compliance
|
||||
|
||||
- Enforce Authority scopes; tokens without tenant or required scope are rejected (`ERR_PACK_SCOPE`).
|
||||
- Signatures verified using trusted Fulcio/KMS roots; optional mirror trust bundles configured via `registry.trustBundle`.
|
||||
- RBAC mapping:
|
||||
|
||||
| Role | Scopes | Capabilities |
|
||||
|------|--------|--------------|
|
||||
| `PackViewer` | `Packs.Read` | Browse, fetch manifests/bundles. |
|
||||
| `PackPublisher` | `Packs.Read`, `Packs.Write` | Publish/promote, manage channels (subject to policy). |
|
||||
| `PackApprover` | `Packs.Read`, `Packs.Approve` | Approve promotions, override tenant visibility (with audit logging). |
|
||||
| `PackOperator` | `Packs.Read`, `Packs.Run` | Execute packs (via CLI/Task Runner). |
|
||||
|
||||
- Audit events forwarded to Authority + Evidence Locker.
|
||||
- Built-in malware/secret scanning runs on bundle upload (configurable via DevOps pipeline).
|
||||
|
||||
See [pack signing & RBAC guidance](../security/pack-signing-and-rbac.md) for deeper controls.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Observability
|
||||
|
||||
- Metrics (`registry` namespace):
|
||||
- `pack_publish_total{result}` – success/failure counts.
|
||||
- `pack_signature_verify_seconds` – verification latency.
|
||||
- `pack_channel_promotions_total` – promotions per channel.
|
||||
- `pack_mirror_queue_depth` – pending mirror jobs.
|
||||
- Logs (structured JSON with `packId`, `version`, `actor`, `tenant`, `digest`).
|
||||
- Traces instrument bundle verification, storage writes, and mirror pushes.
|
||||
- Alerting suggestions:
|
||||
- Publish failure rate > 5 % (5 m window) triggers DevOps escalation.
|
||||
- Mirror lag > 15 m surfaces to Ops dashboard.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Schema & Metadata Extensions
|
||||
|
||||
- Default metadata stored under `metadata.*` from manifest.
|
||||
- Registry supplements with:
|
||||
- `compatibility.cli` (supported CLI versions).
|
||||
- `compatibility.runner` (Task Runner build requirements).
|
||||
- `provenance.attestations[]` (URIs).
|
||||
- `channels[]` (current channel assignments).
|
||||
- `tenantVisibility[]`.
|
||||
- `deprecated` flag + replacement hints.
|
||||
|
||||
Extensions must be deterministic and derived from signed bundle data.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Operations
|
||||
|
||||
- **Backups:** Daily snapshots of Mongo collections + object storage, retained for 30 days.
|
||||
- **Retention:** Old versions retained indefinitely; mark as `deprecated` instead of deleting.
|
||||
- **Maintenance:**
|
||||
- Run `registry vacuum` weekly to prune orphaned blobs.
|
||||
- Rotate signing keys per security policy (document in `pack-signing-and-rbac`).
|
||||
- Validate trust bundles quarterly.
|
||||
- **Disaster recovery:**
|
||||
- Restore database + object storage.
|
||||
- Rebuild OCI indexes (`registry rebuild-index`).
|
||||
- Replay audit events for downstream systems.
|
||||
|
||||
---
|
||||
|
||||
## 10 · Compliance Checklist
|
||||
|
||||
- [ ] REST + OCI endpoints documented with required scopes.
|
||||
- [ ] Publishing flow covers signature verification, audit logging, and promotion policies.
|
||||
- [ ] Mirroring/offline strategy recorded (policies, manifests, sealed mode notes).
|
||||
- [ ] RBAC roles and scope mapping defined.
|
||||
- [ ] Observability metrics, logs, and alerts described.
|
||||
- [ ] Operations guidance covers backups, rotation, disaster recovery.
|
||||
- [ ] Imposed rule reminder included at top of document.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Packs Registry Architecture & Operations
|
||||
|
||||
The Packs Registry stores, verifies, and serves Task Pack bundles across environments. It integrates with Authority for RBAC, Task Runner for execution, DevOps for release automation, and Offline Kit for air-gapped distribution.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Service Overview
|
||||
|
||||
- **Service name:** `StellaOps.PacksRegistry`
|
||||
- **Interfaces:** REST/GraphQL API, OCI-compatible registry endpoints, event streams for mirroring.
|
||||
- **Data stores:** MongoDB (`packs`, `pack_versions`, `pack_provenance`), object storage (bundle blobs, signatures), timeline events.
|
||||
- **Dependencies:** Authority scopes (`Packs.*`), Export Center (manifests), DevOps signing service, Notifications (optional).
|
||||
|
||||
---
|
||||
|
||||
## 2 · Core Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| **Pack record** | Immutable entry representing a pack version; includes metadata, digest, signatures, tenant visibility. |
|
||||
| **Channel** | Logical distribution channel (`stable`, `edge`, `beta`, custom). Controls mirroring/promotion flows. |
|
||||
| **Provenance** | DSSE statements + SBOM linking pack bundle to source repo, CLI build, and Task Runner compatibility. |
|
||||
| **Mirroring policy** | Rules specifying which packs replicate to downstream registries or Offline Kit bundles. |
|
||||
| **Audit trail** | Append-only log capturing publish/update/delete actions, approvals, and policy evaluations. |
|
||||
|
||||
---
|
||||
|
||||
## 3 · API Surface
|
||||
|
||||
### 3.1 REST Endpoints
|
||||
|
||||
| Method | Path | Description | Scopes |
|
||||
|--------|------|-------------|--------|
|
||||
| `GET` | `/api/packs` | List packs with filters (`name`, `channel`, `tenant`, `tag`). | `Packs.Read` |
|
||||
| `GET` | `/api/packs/{packId}/versions` | List versions with metadata, provenance. | `Packs.Read` |
|
||||
| `GET` | `/api/packs/{packId}/versions/{version}` | Retrieve manifest, signatures, compatibility matrix. | `Packs.Read` |
|
||||
| `POST` | `/api/packs/{packId}/versions` | Publish new version (bundle upload or OCI reference). | `Packs.Write` |
|
||||
| `POST` | `/api/packs/{packId}/promote` | Promote version between channels (edge→stable). | `Packs.Write` + approval policy |
|
||||
| `DELETE` | `/api/packs/{packId}/versions/{version}` | Deprecate version (soft delete, immutability preserved). | `Packs.Write` |
|
||||
| `GET` | `/api/packs/{packId}/events` | Stream audit events (SSE). | `Packs.Read` |
|
||||
|
||||
### 3.2 OCI Endpoints
|
||||
|
||||
The registry exposes OCI-compatible endpoints (`/v2/<namespace>/<pack>/...`) supporting:
|
||||
|
||||
- `PUT`/`PATCH`/`GET` for manifests and blobs.
|
||||
- Content-addressed digests using SHA-256.
|
||||
- Annotations for pack metadata (`org.opencontainers.image.title`, `io.stellaops.pack.metadata`).
|
||||
|
||||
### 3.3 GraphQL (Optional)
|
||||
|
||||
GraphQL endpoint (`/api/graphql`) enables advanced queries (filter by approvals, tags, compatibility). Under active development; reference API schema once published.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Publishing Workflow
|
||||
|
||||
1. CLI/CI calls `POST /api/packs/{id}/versions` with signed bundle.
|
||||
2. Registry verifies:
|
||||
- Manifest schema compliance.
|
||||
- Signature (cosign/DSSE) validity.
|
||||
- Authority scopes (`Packs.Write`).
|
||||
- Tenant visibility constraints.
|
||||
3. On success, registry stores bundle, provenance, and emits event (`pack.version.published`).
|
||||
4. Optional promotion requires additional approvals or integration with DevOps release boards.
|
||||
|
||||
All actions recorded in audit log:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "evt_01HF...",
|
||||
"type": "pack.version.published",
|
||||
"packId": "sbom-remediation",
|
||||
"version": "1.3.0",
|
||||
"actor": "user:alice",
|
||||
"tenant": "west-prod",
|
||||
"source": "cli/2025.10.0",
|
||||
"signatures": ["sha256:..."],
|
||||
"metadataHash": "sha256:..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5 · Mirroring & Offline Support
|
||||
|
||||
- **Automatic mirroring:** Configure policies to push packs to secondary registries (edge clusters, regional mirrors) or object stores.
|
||||
- **Offline Kit integration:** `ops/offline-kit` pipeline pulls packs matching specified channels and writes them to `offline/packs/manifest.json` with signatures.
|
||||
- **Checksum manifest:** Registry maintains `digestmap.json` listing pack digests + signatures; offline installers verify before import.
|
||||
- **Sealed mode:** Registry can operate in read-only mode for sealed environments; publishing disabled except via offline import command (`stella pack mirror import`).
|
||||
|
||||
---
|
||||
|
||||
## 6 · Security & Compliance
|
||||
|
||||
- Enforce Authority scopes; tokens without tenant or required scope are rejected (`ERR_PACK_SCOPE`).
|
||||
- Signatures verified using trusted Fulcio/KMS roots; optional mirror trust bundles configured via `registry.trustBundle`.
|
||||
- RBAC mapping:
|
||||
|
||||
| Role | Scopes | Capabilities |
|
||||
|------|--------|--------------|
|
||||
| `PackViewer` | `Packs.Read` | Browse, fetch manifests/bundles. |
|
||||
| `PackPublisher` | `Packs.Read`, `Packs.Write` | Publish/promote, manage channels (subject to policy). |
|
||||
| `PackApprover` | `Packs.Read`, `Packs.Approve` | Approve promotions, override tenant visibility (with audit logging). |
|
||||
| `PackOperator` | `Packs.Read`, `Packs.Run` | Execute packs (via CLI/Task Runner). |
|
||||
|
||||
- Audit events forwarded to Authority + Evidence Locker.
|
||||
- Built-in malware/secret scanning runs on bundle upload (configurable via DevOps pipeline).
|
||||
|
||||
See [pack signing & RBAC guidance](../security/pack-signing-and-rbac.md) for deeper controls.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Observability
|
||||
|
||||
- Metrics (`registry` namespace):
|
||||
- `pack_publish_total{result}` – success/failure counts.
|
||||
- `pack_signature_verify_seconds` – verification latency.
|
||||
- `pack_channel_promotions_total` – promotions per channel.
|
||||
- `pack_mirror_queue_depth` – pending mirror jobs.
|
||||
- Logs (structured JSON with `packId`, `version`, `actor`, `tenant`, `digest`).
|
||||
- Traces instrument bundle verification, storage writes, and mirror pushes.
|
||||
- Alerting suggestions:
|
||||
- Publish failure rate > 5 % (5 m window) triggers DevOps escalation.
|
||||
- Mirror lag > 15 m surfaces to Ops dashboard.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Schema & Metadata Extensions
|
||||
|
||||
- Default metadata stored under `metadata.*` from manifest.
|
||||
- Registry supplements with:
|
||||
- `compatibility.cli` (supported CLI versions).
|
||||
- `compatibility.runner` (Task Runner build requirements).
|
||||
- `provenance.attestations[]` (URIs).
|
||||
- `channels[]` (current channel assignments).
|
||||
- `tenantVisibility[]`.
|
||||
- `deprecated` flag + replacement hints.
|
||||
|
||||
Extensions must be deterministic and derived from signed bundle data.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Operations
|
||||
|
||||
- **Backups:** Daily snapshots of Mongo collections + object storage, retained for 30 days.
|
||||
- **Retention:** Old versions retained indefinitely; mark as `deprecated` instead of deleting.
|
||||
- **Maintenance:**
|
||||
- Run `registry vacuum` weekly to prune orphaned blobs.
|
||||
- Rotate signing keys per security policy (document in `pack-signing-and-rbac`).
|
||||
- Validate trust bundles quarterly.
|
||||
- **Disaster recovery:**
|
||||
- Restore database + object storage.
|
||||
- Rebuild OCI indexes (`registry rebuild-index`).
|
||||
- Replay audit events for downstream systems.
|
||||
|
||||
---
|
||||
|
||||
## 10 · Compliance Checklist
|
||||
|
||||
- [ ] REST + OCI endpoints documented with required scopes.
|
||||
- [ ] Publishing flow covers signature verification, audit logging, and promotion policies.
|
||||
- [ ] Mirroring/offline strategy recorded (policies, manifests, sealed mode notes).
|
||||
- [ ] RBAC roles and scope mapping defined.
|
||||
- [ ] Observability metrics, logs, and alerts described.
|
||||
- [ ] Operations guidance covers backups, rotation, disaster recovery.
|
||||
- [ ] Imposed rule reminder included at top of document.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
|
||||
@@ -1,162 +1,162 @@
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Task Pack Operations Runbook
|
||||
|
||||
This runbook guides SREs and on-call engineers through executing, monitoring, and troubleshooting Task Packs using the Task Runner service, Packs Registry, and StellaOps CLI. It aligns with Sprint 43 deliverables (approvals workflow, notifications, chaos resilience).
|
||||
|
||||
---
|
||||
|
||||
## 1 · Quick Reference
|
||||
|
||||
| Action | Command / UI | Notes |
|
||||
|--------|--------------|-------|
|
||||
| Validate pack | `stella pack validate --bundle <file>` | Run before publishing or importing. |
|
||||
| Plan pack run | `stella pack plan --inputs inputs.json` | Outputs plan hash, required approvals, secret summary. |
|
||||
| Execute pack | `stella pack run --pack <id>:<version>` | Streams logs; prompts for secrets/approvals if allowed. |
|
||||
| Approve gate | Console notifications or `stella pack approve --run <id> --gate <gate>` | Requires `Packs.Approve`. |
|
||||
| View run | Console `/console/packs/runs/:id` or `stella pack runs show <id>` | SSE stream available for live status. |
|
||||
| Export evidence | `stella pack runs export --run <id>` | Produces bundle with plan, logs, artifacts, attestations. |
|
||||
|
||||
---
|
||||
|
||||
## 2 · Run Lifecycle
|
||||
|
||||
1. **Submission**
|
||||
- CLI/Orchestrator submits run with inputs, pack version, tenant context.
|
||||
- Task Runner validates pack hash, scopes, sealed-mode constraints.
|
||||
2. **Plan & Simulation**
|
||||
- Runner caches plan graph; optional simulation diff recorded.
|
||||
3. **Approvals**
|
||||
- Gates emit notifications (`NOTIFY-SVC-40-001`).
|
||||
- Approvers can approve/resume via CLI, Console, or API.
|
||||
4. **Execution**
|
||||
- Steps executed per plan (sequential/parallel).
|
||||
- Logs streamed via SSE (`/task-runner/runs/{id}/logs`).
|
||||
5. **Evidence & Attestation**
|
||||
- On completion, DSSE attestation + evidence bundle stored.
|
||||
- Exports available via Export Center.
|
||||
6. **Cleanup**
|
||||
- Artifacts retained per retention policy (default 30 d).
|
||||
- Mirror pack run manifest to Offline Kit if configured.
|
||||
|
||||
---
|
||||
|
||||
## 3 · Monitoring & Telemetry
|
||||
|
||||
- **Metrics dashboards:** `task-runner` Grafana board.
|
||||
- `pack_run_active` – active runs per tenant.
|
||||
- `pack_step_duration_seconds` – histograms per step type.
|
||||
- `pack_gate_wait_seconds` – approval wait time (alert > 30 m).
|
||||
- `pack_run_success_ratio` – success vs failure rate.
|
||||
- **Logs:** Search by `runId`, `packId`, `tenant`, `stepId`.
|
||||
- **Traces:** Query `taskrunner.run` span in Tempo/Jaeger.
|
||||
- **Notifications:** Subscribe to `pack.run.*` topics via Notifier for Slack/email/PagerDuty hooks.
|
||||
|
||||
Observability configuration referenced in Task Runner tasks (OBS-50-001..55-001).
|
||||
|
||||
---
|
||||
|
||||
## 4 · Approvals Workflow
|
||||
|
||||
- Approvals may be requested via Console banner, CLI prompt, or email/Slack.
|
||||
- Approver roles: `Packs.Approve` + tenant membership.
|
||||
- CLI command:
|
||||
|
||||
```bash
|
||||
stella pack approve \
|
||||
--run run:tenant:timestamp \
|
||||
--gate security-review \
|
||||
--comment "Validated remediation scope; proceeding."
|
||||
```
|
||||
|
||||
- Auto-expiry triggers run cancellation (configurable per gate).
|
||||
- Approval events logged and included in evidence bundle.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Secrets Handling
|
||||
|
||||
- Secrets retrieved via Authority secure channel or CLI profile.
|
||||
- Task Runner injects secrets into isolated environment variables or temp files (auto-shredded).
|
||||
- Logs redact secrets; evidence bundles include only secret metadata (name, scope, last four characters).
|
||||
- For sealed mode, secrets must originate from sealed vault (configured via `TASKRUNNER_SEALED_VAULT_URL`).
|
||||
|
||||
---
|
||||
|
||||
## 6 · Failure Recovery
|
||||
|
||||
| Scenario | Symptom | Resolution |
|
||||
|----------|---------|------------|
|
||||
| **Plan hash mismatch** | Run aborted with `ERR_PACK_HASH_MISMATCH`. | Re-run `stella pack plan`; ensure pack not modified post-plan. |
|
||||
| **Approval timeout** | `ERR_PACK_APPROVAL_TIMEOUT`. | Requeue run with extended TTL or escalate to approver; verify notifications delivered. |
|
||||
| **Secret missing** | Run fails at injection step. | Provide secret via CLI (`--secrets`) or configure profile; check Authority scope. |
|
||||
| **Network blocked (sealed)** | `ERR_PACK_NETWORK_BLOCKED`. | Update pack to avoid external calls or whitelist domain via AirGap policy. |
|
||||
| **Artifact upload failure** | Evidence missing, logs show storage errors. | Retry run with `--resume` (if supported); verify object storage health. |
|
||||
| **Runner chaos trigger** | Run paused with chaos event note. | Review chaos test plan; resume if acceptable or cancel run. |
|
||||
|
||||
`stella pack runs resume --run <id>` resumes paused runs post-remediation (approvals or transient failures).
|
||||
|
||||
---
|
||||
|
||||
## 7 · Chaos & Resilience
|
||||
|
||||
- Chaos hooks pause runs, drop network, or delay approvals to test resilience.
|
||||
- Track chaos events via `pack.chaos.injected` timeline entries.
|
||||
- Post-chaos, ensure metrics return to baseline; record findings in Ops log.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Offline & Air-Gapped Execution
|
||||
|
||||
- Use `stella pack mirror pull` to import packs into sealed registry.
|
||||
- CLI caches bundles under `~/.stella/packs/` for offline runs.
|
||||
- Approvals require offline process:
|
||||
- Generate approval request bundle (`stella pack approve --offline-request`).
|
||||
- Approver signs bundle using offline CLI.
|
||||
- Import approval via `stella pack approve --offline-response`.
|
||||
- Evidence bundles exported to removable media; verify checksums before upload to online systems.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Runbooks for Common Packs
|
||||
|
||||
Maintain per-pack playbooks in `docs/task-packs/runbook/<pack-name>.md`. Include:
|
||||
|
||||
- Purpose and scope.
|
||||
- Required inputs and secrets.
|
||||
- Approval stakeholders.
|
||||
- Pre-checks and post-checks.
|
||||
- Rollback procedures.
|
||||
|
||||
The Docs Guild can use this root runbook as a template.
|
||||
|
||||
---
|
||||
|
||||
## 10 · Escalation Matrix
|
||||
|
||||
| Issue | Primary | Secondary | Notes |
|
||||
|-------|---------|-----------|-------|
|
||||
| Pack validation errors | DevEx/CLI Guild | Task Runner Guild | Provide pack bundle + validation output. |
|
||||
| Approval pipeline failure | Task Runner Guild | Authority Core | Confirm scope/role mapping. |
|
||||
| Registry outage | Packs Registry Guild | DevOps Guild | Use mirror fallback if possible. |
|
||||
| Evidence integrity issues | Evidence Locker Guild | Security Guild | Validate DSSE attestations, escalate if tampered. |
|
||||
|
||||
Escalations must include run ID, tenant, pack version, plan hash, and timestamps.
|
||||
|
||||
---
|
||||
|
||||
## 11 · Compliance Checklist
|
||||
|
||||
- [ ] Run lifecycle documented (submission → evidence).
|
||||
- [ ] Monitoring metrics, logs, traces, and notifications captured.
|
||||
- [ ] Approvals workflow instructions provided (CLI + Console).
|
||||
- [ ] Secret handling, sealed-mode constraints, and offline process described.
|
||||
- [ ] Failure scenarios + recovery steps listed.
|
||||
- [ ] Chaos/resilience guidance included.
|
||||
- [ ] Escalation matrix defined.
|
||||
- [ ] Imposed rule reminder included at top.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Task Pack Operations Runbook
|
||||
|
||||
This runbook guides SREs and on-call engineers through executing, monitoring, and troubleshooting Task Packs using the Task Runner service, Packs Registry, and StellaOps CLI. It aligns with Sprint 43 deliverables (approvals workflow, notifications, chaos resilience).
|
||||
|
||||
---
|
||||
|
||||
## 1 · Quick Reference
|
||||
|
||||
| Action | Command / UI | Notes |
|
||||
|--------|--------------|-------|
|
||||
| Validate pack | `stella pack validate --bundle <file>` | Run before publishing or importing. |
|
||||
| Plan pack run | `stella pack plan --inputs inputs.json` | Outputs plan hash, required approvals, secret summary. |
|
||||
| Execute pack | `stella pack run --pack <id>:<version>` | Streams logs; prompts for secrets/approvals if allowed. |
|
||||
| Approve gate | Console notifications or `stella pack approve --run <id> --gate <gate>` | Requires `Packs.Approve`. |
|
||||
| View run | Console `/console/packs/runs/:id` or `stella pack runs show <id>` | SSE stream available for live status. |
|
||||
| Export evidence | `stella pack runs export --run <id>` | Produces bundle with plan, logs, artifacts, attestations. |
|
||||
|
||||
---
|
||||
|
||||
## 2 · Run Lifecycle
|
||||
|
||||
1. **Submission**
|
||||
- CLI/Orchestrator submits run with inputs, pack version, tenant context.
|
||||
- Task Runner validates pack hash, scopes, sealed-mode constraints.
|
||||
2. **Plan & Simulation**
|
||||
- Runner caches plan graph; optional simulation diff recorded.
|
||||
3. **Approvals**
|
||||
- Gates emit notifications (`NOTIFY-SVC-40-001`).
|
||||
- Approvers can approve/resume via CLI, Console, or API.
|
||||
4. **Execution**
|
||||
- Steps executed per plan (sequential/parallel).
|
||||
- Logs streamed via SSE (`/task-runner/runs/{id}/logs`).
|
||||
5. **Evidence & Attestation**
|
||||
- On completion, DSSE attestation + evidence bundle stored.
|
||||
- Exports available via Export Center.
|
||||
6. **Cleanup**
|
||||
- Artifacts retained per retention policy (default 30 d).
|
||||
- Mirror pack run manifest to Offline Kit if configured.
|
||||
|
||||
---
|
||||
|
||||
## 3 · Monitoring & Telemetry
|
||||
|
||||
- **Metrics dashboards:** `task-runner` Grafana board.
|
||||
- `pack_run_active` – active runs per tenant.
|
||||
- `pack_step_duration_seconds` – histograms per step type.
|
||||
- `pack_gate_wait_seconds` – approval wait time (alert > 30 m).
|
||||
- `pack_run_success_ratio` – success vs failure rate.
|
||||
- **Logs:** Search by `runId`, `packId`, `tenant`, `stepId`.
|
||||
- **Traces:** Query `taskrunner.run` span in Tempo/Jaeger.
|
||||
- **Notifications:** Subscribe to `pack.run.*` topics via Notifier for Slack/email/PagerDuty hooks.
|
||||
|
||||
Observability configuration referenced in Task Runner tasks (OBS-50-001..55-001).
|
||||
|
||||
---
|
||||
|
||||
## 4 · Approvals Workflow
|
||||
|
||||
- Approvals may be requested via Console banner, CLI prompt, or email/Slack.
|
||||
- Approver roles: `Packs.Approve` + tenant membership.
|
||||
- CLI command:
|
||||
|
||||
```bash
|
||||
stella pack approve \
|
||||
--run run:tenant:timestamp \
|
||||
--gate security-review \
|
||||
--comment "Validated remediation scope; proceeding."
|
||||
```
|
||||
|
||||
- Auto-expiry triggers run cancellation (configurable per gate).
|
||||
- Approval events logged and included in evidence bundle.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Secrets Handling
|
||||
|
||||
- Secrets retrieved via Authority secure channel or CLI profile.
|
||||
- Task Runner injects secrets into isolated environment variables or temp files (auto-shredded).
|
||||
- Logs redact secrets; evidence bundles include only secret metadata (name, scope, last four characters).
|
||||
- For sealed mode, secrets must originate from sealed vault (configured via `TASKRUNNER_SEALED_VAULT_URL`).
|
||||
|
||||
---
|
||||
|
||||
## 6 · Failure Recovery
|
||||
|
||||
| Scenario | Symptom | Resolution |
|
||||
|----------|---------|------------|
|
||||
| **Plan hash mismatch** | Run aborted with `ERR_PACK_HASH_MISMATCH`. | Re-run `stella pack plan`; ensure pack not modified post-plan. |
|
||||
| **Approval timeout** | `ERR_PACK_APPROVAL_TIMEOUT`. | Requeue run with extended TTL or escalate to approver; verify notifications delivered. |
|
||||
| **Secret missing** | Run fails at injection step. | Provide secret via CLI (`--secrets`) or configure profile; check Authority scope. |
|
||||
| **Network blocked (sealed)** | `ERR_PACK_NETWORK_BLOCKED`. | Update pack to avoid external calls or whitelist domain via AirGap policy. |
|
||||
| **Artifact upload failure** | Evidence missing, logs show storage errors. | Retry run with `--resume` (if supported); verify object storage health. |
|
||||
| **Runner chaos trigger** | Run paused with chaos event note. | Review chaos test plan; resume if acceptable or cancel run. |
|
||||
|
||||
`stella pack runs resume --run <id>` resumes paused runs post-remediation (approvals or transient failures).
|
||||
|
||||
---
|
||||
|
||||
## 7 · Chaos & Resilience
|
||||
|
||||
- Chaos hooks pause runs, drop network, or delay approvals to test resilience.
|
||||
- Track chaos events via `pack.chaos.injected` timeline entries.
|
||||
- Post-chaos, ensure metrics return to baseline; record findings in Ops log.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Offline & Air-Gapped Execution
|
||||
|
||||
- Use `stella pack mirror pull` to import packs into sealed registry.
|
||||
- CLI caches bundles under `~/.stella/packs/` for offline runs.
|
||||
- Approvals require offline process:
|
||||
- Generate approval request bundle (`stella pack approve --offline-request`).
|
||||
- Approver signs bundle using offline CLI.
|
||||
- Import approval via `stella pack approve --offline-response`.
|
||||
- Evidence bundles exported to removable media; verify checksums before upload to online systems.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Runbooks for Common Packs
|
||||
|
||||
Maintain per-pack playbooks in `docs/task-packs/runbook/<pack-name>.md`. Include:
|
||||
|
||||
- Purpose and scope.
|
||||
- Required inputs and secrets.
|
||||
- Approval stakeholders.
|
||||
- Pre-checks and post-checks.
|
||||
- Rollback procedures.
|
||||
|
||||
The Docs Guild can use this root runbook as a template.
|
||||
|
||||
---
|
||||
|
||||
## 10 · Escalation Matrix
|
||||
|
||||
| Issue | Primary | Secondary | Notes |
|
||||
|-------|---------|-----------|-------|
|
||||
| Pack validation errors | DevEx/CLI Guild | Task Runner Guild | Provide pack bundle + validation output. |
|
||||
| Approval pipeline failure | Task Runner Guild | Authority Core | Confirm scope/role mapping. |
|
||||
| Registry outage | Packs Registry Guild | DevOps Guild | Use mirror fallback if possible. |
|
||||
| Evidence integrity issues | Evidence Locker Guild | Security Guild | Validate DSSE attestations, escalate if tampered. |
|
||||
|
||||
Escalations must include run ID, tenant, pack version, plan hash, and timestamps.
|
||||
|
||||
---
|
||||
|
||||
## 11 · Compliance Checklist
|
||||
|
||||
- [ ] Run lifecycle documented (submission → evidence).
|
||||
- [ ] Monitoring metrics, logs, traces, and notifications captured.
|
||||
- [ ] Approvals workflow instructions provided (CLI + Console).
|
||||
- [ ] Secret handling, sealed-mode constraints, and offline process described.
|
||||
- [ ] Failure scenarios + recovery steps listed.
|
||||
- [ ] Chaos/resilience guidance included.
|
||||
- [ ] Escalation matrix defined.
|
||||
- [ ] Imposed rule reminder included at top.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
|
||||
@@ -1,249 +1,249 @@
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Task Pack Specification (Sprint 43 Draft)
|
||||
|
||||
The Task Pack specification defines a deterministic, auditable format that enables operators to encode multi-step maintenance, validation, and deployment workflows. Packs are executed by the Task Runner service, distributed through the Packs Registry, and invoked via the StellaOps CLI (`stella pack ...`) or Orchestrator integrations.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Goals & Scope
|
||||
|
||||
- **Deterministic execution.** Identical inputs yield identical run graphs, output manifests, and evidence bundles across environments (online, sealed, or offline).
|
||||
- **Secure-by-default.** Pack metadata must capture provenance, signatures, RBAC requirements, and secret usage; execution enforces tenant scopes and approvals.
|
||||
- **Portable.** Packs are distributed as signed OCI artifacts or tarballs that work in connected and air-gapped deployments, including Offline Kit mirrors.
|
||||
- **Composable.** Packs can reference reusable steps, expressions, and shared libraries without sacrificing determinism or auditability.
|
||||
|
||||
Non-goals: full-blown workflow orchestration, unbounded scripting, or remote code injection. All logic is declarative and constrained to Task Runner capabilities.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Terminology
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| **Pack manifest** | Primary YAML document (`pack.yaml`) describing metadata, inputs, steps, policies, and evidence expectations. |
|
||||
| **Step** | Atomic unit of work executed by Task Runner (e.g., command, API call, policy gate, approval). Steps can be sequential or parallel. |
|
||||
| **Expression** | Deterministic evaluation (JMESPath-like) used for branching, templating, and conditionals. |
|
||||
| **Policy gate** | Declarative rule that blocks execution until conditions are met (e.g., approval recorded, external signal received). |
|
||||
| **Artifact** | File, JSON blob, or OCI object produced by a step, referenced in manifests and evidence bundles. |
|
||||
| **Pack bundle** | Distribution archive (`.stella-pack.tgz` or OCI ref) containing manifest, assets, schemas, and provenance metadata. |
|
||||
|
||||
---
|
||||
|
||||
## 3 · Pack Layout
|
||||
|
||||
```
|
||||
my-pack/
|
||||
├─ pack.yaml # Required manifest
|
||||
├─ assets/ # Optional static assets (scripts, templates)
|
||||
├─ schemas/ # JSON schemas for inputs/outputs
|
||||
├─ docs/ # Markdown docs rendered in Console/CLI help
|
||||
├─ provenance/ # DSSE statements, SBOM, attestations
|
||||
└─ README.md # Author-facing summary (optional)
|
||||
```
|
||||
|
||||
Publishing via Packs Registry or OCI ensures the directory is canonical and hashed.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Manifest Schema (v1.0)
|
||||
|
||||
```yaml
|
||||
apiVersion: stellaops.io/pack.v1
|
||||
kind: TaskPack
|
||||
metadata:
|
||||
name: sbom-remediation
|
||||
version: 1.3.0
|
||||
description: >
|
||||
Audit SBOM drift, quiet high-risk findings, and export mitigation evidence.
|
||||
tags: [sbom, remediation, policy]
|
||||
tenantVisibility: ["west-prod", "east-stage"] # optional allowlist
|
||||
maintainers:
|
||||
- name: Jane Doe
|
||||
email: jane@example.com
|
||||
license: AGPL-3.0-or-later
|
||||
annotations:
|
||||
imposedRuleReminder: true
|
||||
|
||||
spec:
|
||||
inputs:
|
||||
- name: sbomBundle
|
||||
type: object
|
||||
schema: schemas/sbom-bundle.schema.json
|
||||
required: true
|
||||
- name: dryRun
|
||||
type: boolean
|
||||
default: false
|
||||
secrets:
|
||||
- name: jiraToken
|
||||
scope: Packs.Run # Authority scope required
|
||||
description: Optional token for ticket automation
|
||||
approvals:
|
||||
- id: security-review
|
||||
grants: ["Packs.Approve"]
|
||||
expiresAfter: PT4H
|
||||
reasonTemplate: "Approve remediation for SBOM {{ inputs.sbomBundle.metadata.image }}"
|
||||
steps:
|
||||
- id: validate-input
|
||||
run:
|
||||
uses: builtin:validate-schema
|
||||
with:
|
||||
target: "{{ inputs.sbomBundle }}"
|
||||
schema: schemas/sbom-bundle.schema.json
|
||||
- id: plan-remediation
|
||||
when: "{{ not inputs.dryRun }}"
|
||||
run:
|
||||
uses: builtin:policy-simulate
|
||||
with:
|
||||
sbom: "{{ inputs.sbomBundle }}"
|
||||
policy: "policies/remediation.yaml"
|
||||
- id: approval-gate
|
||||
gate:
|
||||
approval: security-review
|
||||
message: "Security must approve remediation before changes apply."
|
||||
- id: apply-remediation
|
||||
run:
|
||||
uses: builtin:cli-command
|
||||
with:
|
||||
command: ["stella", "policy", "promote", "--from-pack"]
|
||||
- id: export-evidence
|
||||
run:
|
||||
uses: builtin:evidence-export
|
||||
with:
|
||||
includeArtifacts: ["{{ steps.plan-remediation.outputs.planPath }}"]
|
||||
outputs:
|
||||
- name: evidenceBundle
|
||||
type: file
|
||||
path: "{{ steps.export-evidence.outputs.bundlePath }}"
|
||||
success:
|
||||
message: "Remediation applied; evidence bundle ready."
|
||||
failure:
|
||||
retries:
|
||||
maxAttempts: 1
|
||||
backoffSeconds: 0
|
||||
message: "Remediation failed; see evidence bundle for context."
|
||||
```
|
||||
|
||||
### 4.1 Field Summary
|
||||
|
||||
| Field | Description | Requirements |
|
||||
|-------|-------------|--------------|
|
||||
| `metadata` | Human-facing metadata; used for registry listings and RBAC hints. | `name` (DNS-1123), `version` (SemVer), `description` ≤ 2048 chars. |
|
||||
| `spec.inputs` | Declarative inputs validated at plan time. | Must include type; custom schema optional but recommended. |
|
||||
| `spec.secrets` | Secrets requested at runtime; never stored in pack bundle. | Each secret references Authority scope; CLI prompts or injects from profiles. |
|
||||
| `spec.approvals` | Named approval gates with required grants and TTL. | ID unique per pack; `grants` map to Authority roles. |
|
||||
| `spec.steps` | Execution graph; each step is `run`, `gate`, `parallel`, or `map`. | Steps must declare deterministic `uses` module and `id`. |
|
||||
| `spec.outputs` | Declared artifacts for downstream automation. | `type` can be `file`, `object`, or `url`; path/expression required. |
|
||||
| `success` / `failure` | Messages + retry policy. | `failure.retries.maxAttempts` + `backoffSeconds` default to 0. |
|
||||
|
||||
---
|
||||
|
||||
## 5 · Step Types
|
||||
|
||||
| Type | Schema | Notes |
|
||||
|------|--------|-------|
|
||||
| `run` | Executes a built-in module (`builtin:*`) or registry-provided module. | Modules must be deterministic, side-effect constrained, and versioned. |
|
||||
| `parallel` | Executes sub-steps concurrently; `maxParallel` optional. | Results aggregated; failures trigger abort unless `continueOnError`. |
|
||||
| `map` | Iterates over deterministic list; each iteration spawns sub-step. | Sequence derived from expression result; ordering stable. |
|
||||
| `gate.approval` | Blocks until approval recorded with required grants. | Supports `autoExpire` to cancel run on timeout. |
|
||||
| `gate.policy` | Calls Policy Engine to ensure criteria met (e.g., no critical findings). | Fails run if gate not satisfied. |
|
||||
|
||||
`when` expressions must be pure (no side effects) and rely only on declared inputs or prior outputs.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Determinism & Validation
|
||||
|
||||
1. **Plan phase** (`stella pack plan`, `TaskRunner.Plan` API) parses manifest, resolves expressions, validates schemas, and emits canonical graph with hash.
|
||||
2. **Simulation** compares plan vs dry-run results, capturing differences in `planDiff`. Required for approvals in sealed environments.
|
||||
3. **Execution** uses plan hash to ensure runtime graph matches simulation. Divergence aborts run.
|
||||
4. **Evidence**: Task Runner emits DSSE attestation referencing plan hash, input digests, and output artifacts.
|
||||
|
||||
Validation pipeline:
|
||||
|
||||
```text
|
||||
pack.yaml ──▶ schema validation ──▶ expression audit ──▶ determinism guard ──▶ signing
|
||||
```
|
||||
|
||||
Packs must pass CLI validation before publishing.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Signatures & Provenance
|
||||
|
||||
- Pack bundles are signed with **cosign** (keyless Fulcio/KMS supported) and optionally DSSE envelopes.
|
||||
- `provenance/` directory stores signed statements (SLSA Build L1+) linking source repo, CI run, and manifest hash.
|
||||
- Registry verifies signatures on push/pull; Task Runner refuses unsigned packs unless in development mode.
|
||||
- Attestations include:
|
||||
- Pack manifest digest (`sha256`)
|
||||
- Pack bundle digest
|
||||
- Build metadata (`git.ref`, `ci.workflow`, `cli.version`)
|
||||
|
||||
---
|
||||
|
||||
## 8 · RBAC & Scopes
|
||||
|
||||
Authority scopes introduced by `AUTH-PACKS-41-001`:
|
||||
|
||||
| Scope | Purpose |
|
||||
|-------|---------|
|
||||
| `Packs.Read` | Discover packs, download manifests. |
|
||||
| `Packs.Write` | Publish/update packs in registry (requires signature). |
|
||||
| `Packs.Run` | Execute packs via CLI/Task Runner. |
|
||||
| `Packs.Approve` | Fulfil approval gates defined in packs. |
|
||||
|
||||
Task Runner enforces scopes per tenant; pack metadata may further restrict tenant visibility (`metadata.tenantVisibility`).
|
||||
|
||||
---
|
||||
|
||||
## 9 · Observability & Evidence
|
||||
|
||||
- Metrics: `pack_run_duration_seconds`, `pack_step_retry_total`, `pack_gate_wait_seconds`.
|
||||
- Logs: Structured JSON per step with scrubbed inputs (`secretMask` applied).
|
||||
- Timeline events: `pack.started`, `pack.approval.requested`, `pack.approval.granted`, `pack.completed`.
|
||||
- Evidence bundle includes:
|
||||
- Plan manifest (canonical JSON)
|
||||
- Step transcripts (redacted)
|
||||
- Artifacts manifest (sha256, size)
|
||||
- Attestations references
|
||||
|
||||
---
|
||||
|
||||
## 10 · Compatibility Matrix
|
||||
|
||||
| CLI Version | Pack API | Task Runner | Notes |
|
||||
|-------------|----------|-------------|-------|
|
||||
| 2025.10.x | `pack.v1` | Runner build `>=2025.10.0` | Approvals optional, loops disabled. |
|
||||
| 2025.12.x | `pack.v1` | Runner build `>=2025.12.0` | Approvals resume, secrets injection, localization strings. |
|
||||
| Future | `pack.v2` | TBD | Will introduce typed outputs & partial replay (track in Epic 13). |
|
||||
|
||||
CLI enforces compatibility: running pack with unsupported features yields `ERR_PACK_UNSUPPORTED`.
|
||||
|
||||
---
|
||||
|
||||
## 11 · Publishing Workflow
|
||||
|
||||
1. Author pack (`pack.yaml`, assets, docs).
|
||||
2. Run `stella pack validate` (schema + determinism).
|
||||
3. Generate bundle: `stella pack build --output my-pack.stella-pack.tgz`.
|
||||
4. Sign: `cosign sign-blob my-pack.stella-pack.tgz`.
|
||||
5. Publish: `stella pack push registry.example.com/org/my-pack:1.3.0`.
|
||||
6. Registry verifies signature, records provenance, and exposes pack via API.
|
||||
|
||||
---
|
||||
|
||||
## 12 · Compliance Checklist
|
||||
|
||||
- [ ] Manifest schema documented for all fields, including approvals, secrets, and outputs.
|
||||
- [ ] Determinism requirements outlined with plan/simulate semantics and CLI validation steps.
|
||||
- [ ] Signing + provenance expectations spelled out with cosign/DSSE references.
|
||||
- [ ] RBAC scopes (`Packs.*`) and tenant visibility rules captured.
|
||||
- [ ] Observability (metrics, logs, evidence) described for Task Runner integrations.
|
||||
- [ ] Compatibility matrix enumerates CLI/Runner requirements.
|
||||
- [ ] Publishing workflow documented with CLI commands.
|
||||
- [ ] Imposed rule reminder included at top of document.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Task Pack Specification (Sprint 43 Draft)
|
||||
|
||||
The Task Pack specification defines a deterministic, auditable format that enables operators to encode multi-step maintenance, validation, and deployment workflows. Packs are executed by the Task Runner service, distributed through the Packs Registry, and invoked via the StellaOps CLI (`stella pack ...`) or Orchestrator integrations.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Goals & Scope
|
||||
|
||||
- **Deterministic execution.** Identical inputs yield identical run graphs, output manifests, and evidence bundles across environments (online, sealed, or offline).
|
||||
- **Secure-by-default.** Pack metadata must capture provenance, signatures, RBAC requirements, and secret usage; execution enforces tenant scopes and approvals.
|
||||
- **Portable.** Packs are distributed as signed OCI artifacts or tarballs that work in connected and air-gapped deployments, including Offline Kit mirrors.
|
||||
- **Composable.** Packs can reference reusable steps, expressions, and shared libraries without sacrificing determinism or auditability.
|
||||
|
||||
Non-goals: full-blown workflow orchestration, unbounded scripting, or remote code injection. All logic is declarative and constrained to Task Runner capabilities.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Terminology
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| **Pack manifest** | Primary YAML document (`pack.yaml`) describing metadata, inputs, steps, policies, and evidence expectations. |
|
||||
| **Step** | Atomic unit of work executed by Task Runner (e.g., command, API call, policy gate, approval). Steps can be sequential or parallel. |
|
||||
| **Expression** | Deterministic evaluation (JMESPath-like) used for branching, templating, and conditionals. |
|
||||
| **Policy gate** | Declarative rule that blocks execution until conditions are met (e.g., approval recorded, external signal received). |
|
||||
| **Artifact** | File, JSON blob, or OCI object produced by a step, referenced in manifests and evidence bundles. |
|
||||
| **Pack bundle** | Distribution archive (`.stella-pack.tgz` or OCI ref) containing manifest, assets, schemas, and provenance metadata. |
|
||||
|
||||
---
|
||||
|
||||
## 3 · Pack Layout
|
||||
|
||||
```
|
||||
my-pack/
|
||||
├─ pack.yaml # Required manifest
|
||||
├─ assets/ # Optional static assets (scripts, templates)
|
||||
├─ schemas/ # JSON schemas for inputs/outputs
|
||||
├─ docs/ # Markdown docs rendered in Console/CLI help
|
||||
├─ provenance/ # DSSE statements, SBOM, attestations
|
||||
└─ README.md # Author-facing summary (optional)
|
||||
```
|
||||
|
||||
Publishing via Packs Registry or OCI ensures the directory is canonical and hashed.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Manifest Schema (v1.0)
|
||||
|
||||
```yaml
|
||||
apiVersion: stellaops.io/pack.v1
|
||||
kind: TaskPack
|
||||
metadata:
|
||||
name: sbom-remediation
|
||||
version: 1.3.0
|
||||
description: >
|
||||
Audit SBOM drift, quiet high-risk findings, and export mitigation evidence.
|
||||
tags: [sbom, remediation, policy]
|
||||
tenantVisibility: ["west-prod", "east-stage"] # optional allowlist
|
||||
maintainers:
|
||||
- name: Jane Doe
|
||||
email: jane@example.com
|
||||
license: AGPL-3.0-or-later
|
||||
annotations:
|
||||
imposedRuleReminder: true
|
||||
|
||||
spec:
|
||||
inputs:
|
||||
- name: sbomBundle
|
||||
type: object
|
||||
schema: schemas/sbom-bundle.schema.json
|
||||
required: true
|
||||
- name: dryRun
|
||||
type: boolean
|
||||
default: false
|
||||
secrets:
|
||||
- name: jiraToken
|
||||
scope: Packs.Run # Authority scope required
|
||||
description: Optional token for ticket automation
|
||||
approvals:
|
||||
- id: security-review
|
||||
grants: ["Packs.Approve"]
|
||||
expiresAfter: PT4H
|
||||
reasonTemplate: "Approve remediation for SBOM {{ inputs.sbomBundle.metadata.image }}"
|
||||
steps:
|
||||
- id: validate-input
|
||||
run:
|
||||
uses: builtin:validate-schema
|
||||
with:
|
||||
target: "{{ inputs.sbomBundle }}"
|
||||
schema: schemas/sbom-bundle.schema.json
|
||||
- id: plan-remediation
|
||||
when: "{{ not inputs.dryRun }}"
|
||||
run:
|
||||
uses: builtin:policy-simulate
|
||||
with:
|
||||
sbom: "{{ inputs.sbomBundle }}"
|
||||
policy: "policies/remediation.yaml"
|
||||
- id: approval-gate
|
||||
gate:
|
||||
approval: security-review
|
||||
message: "Security must approve remediation before changes apply."
|
||||
- id: apply-remediation
|
||||
run:
|
||||
uses: builtin:cli-command
|
||||
with:
|
||||
command: ["stella", "policy", "promote", "--from-pack"]
|
||||
- id: export-evidence
|
||||
run:
|
||||
uses: builtin:evidence-export
|
||||
with:
|
||||
includeArtifacts: ["{{ steps.plan-remediation.outputs.planPath }}"]
|
||||
outputs:
|
||||
- name: evidenceBundle
|
||||
type: file
|
||||
path: "{{ steps.export-evidence.outputs.bundlePath }}"
|
||||
success:
|
||||
message: "Remediation applied; evidence bundle ready."
|
||||
failure:
|
||||
retries:
|
||||
maxAttempts: 1
|
||||
backoffSeconds: 0
|
||||
message: "Remediation failed; see evidence bundle for context."
|
||||
```
|
||||
|
||||
### 4.1 Field Summary
|
||||
|
||||
| Field | Description | Requirements |
|
||||
|-------|-------------|--------------|
|
||||
| `metadata` | Human-facing metadata; used for registry listings and RBAC hints. | `name` (DNS-1123), `version` (SemVer), `description` ≤ 2048 chars. |
|
||||
| `spec.inputs` | Declarative inputs validated at plan time. | Must include type; custom schema optional but recommended. |
|
||||
| `spec.secrets` | Secrets requested at runtime; never stored in pack bundle. | Each secret references Authority scope; CLI prompts or injects from profiles. |
|
||||
| `spec.approvals` | Named approval gates with required grants and TTL. | ID unique per pack; `grants` map to Authority roles. |
|
||||
| `spec.steps` | Execution graph; each step is `run`, `gate`, `parallel`, or `map`. | Steps must declare deterministic `uses` module and `id`. |
|
||||
| `spec.outputs` | Declared artifacts for downstream automation. | `type` can be `file`, `object`, or `url`; path/expression required. |
|
||||
| `success` / `failure` | Messages + retry policy. | `failure.retries.maxAttempts` + `backoffSeconds` default to 0. |
|
||||
|
||||
---
|
||||
|
||||
## 5 · Step Types
|
||||
|
||||
| Type | Schema | Notes |
|
||||
|------|--------|-------|
|
||||
| `run` | Executes a built-in module (`builtin:*`) or registry-provided module. | Modules must be deterministic, side-effect constrained, and versioned. |
|
||||
| `parallel` | Executes sub-steps concurrently; `maxParallel` optional. | Results aggregated; failures trigger abort unless `continueOnError`. |
|
||||
| `map` | Iterates over deterministic list; each iteration spawns sub-step. | Sequence derived from expression result; ordering stable. |
|
||||
| `gate.approval` | Blocks until approval recorded with required grants. | Supports `autoExpire` to cancel run on timeout. |
|
||||
| `gate.policy` | Calls Policy Engine to ensure criteria met (e.g., no critical findings). | Fails run if gate not satisfied. |
|
||||
|
||||
`when` expressions must be pure (no side effects) and rely only on declared inputs or prior outputs.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Determinism & Validation
|
||||
|
||||
1. **Plan phase** (`stella pack plan`, `TaskRunner.Plan` API) parses manifest, resolves expressions, validates schemas, and emits canonical graph with hash.
|
||||
2. **Simulation** compares plan vs dry-run results, capturing differences in `planDiff`. Required for approvals in sealed environments.
|
||||
3. **Execution** uses plan hash to ensure runtime graph matches simulation. Divergence aborts run.
|
||||
4. **Evidence**: Task Runner emits DSSE attestation referencing plan hash, input digests, and output artifacts.
|
||||
|
||||
Validation pipeline:
|
||||
|
||||
```text
|
||||
pack.yaml ──▶ schema validation ──▶ expression audit ──▶ determinism guard ──▶ signing
|
||||
```
|
||||
|
||||
Packs must pass CLI validation before publishing.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Signatures & Provenance
|
||||
|
||||
- Pack bundles are signed with **cosign** (keyless Fulcio/KMS supported) and optionally DSSE envelopes.
|
||||
- `provenance/` directory stores signed statements (SLSA Build L1+) linking source repo, CI run, and manifest hash.
|
||||
- Registry verifies signatures on push/pull; Task Runner refuses unsigned packs unless in development mode.
|
||||
- Attestations include:
|
||||
- Pack manifest digest (`sha256`)
|
||||
- Pack bundle digest
|
||||
- Build metadata (`git.ref`, `ci.workflow`, `cli.version`)
|
||||
|
||||
---
|
||||
|
||||
## 8 · RBAC & Scopes
|
||||
|
||||
Authority scopes introduced by `AUTH-PACKS-41-001`:
|
||||
|
||||
| Scope | Purpose |
|
||||
|-------|---------|
|
||||
| `Packs.Read` | Discover packs, download manifests. |
|
||||
| `Packs.Write` | Publish/update packs in registry (requires signature). |
|
||||
| `Packs.Run` | Execute packs via CLI/Task Runner. |
|
||||
| `Packs.Approve` | Fulfil approval gates defined in packs. |
|
||||
|
||||
Task Runner enforces scopes per tenant; pack metadata may further restrict tenant visibility (`metadata.tenantVisibility`).
|
||||
|
||||
---
|
||||
|
||||
## 9 · Observability & Evidence
|
||||
|
||||
- Metrics: `pack_run_duration_seconds`, `pack_step_retry_total`, `pack_gate_wait_seconds`.
|
||||
- Logs: Structured JSON per step with scrubbed inputs (`secretMask` applied).
|
||||
- Timeline events: `pack.started`, `pack.approval.requested`, `pack.approval.granted`, `pack.completed`.
|
||||
- Evidence bundle includes:
|
||||
- Plan manifest (canonical JSON)
|
||||
- Step transcripts (redacted)
|
||||
- Artifacts manifest (sha256, size)
|
||||
- Attestations references
|
||||
|
||||
---
|
||||
|
||||
## 10 · Compatibility Matrix
|
||||
|
||||
| CLI Version | Pack API | Task Runner | Notes |
|
||||
|-------------|----------|-------------|-------|
|
||||
| 2025.10.x | `pack.v1` | Runner build `>=2025.10.0` | Approvals optional, loops disabled. |
|
||||
| 2025.12.x | `pack.v1` | Runner build `>=2025.12.0` | Approvals resume, secrets injection, localization strings. |
|
||||
| Future | `pack.v2` | TBD | Will introduce typed outputs & partial replay (track in Epic 13). |
|
||||
|
||||
CLI enforces compatibility: running pack with unsupported features yields `ERR_PACK_UNSUPPORTED`.
|
||||
|
||||
---
|
||||
|
||||
## 11 · Publishing Workflow
|
||||
|
||||
1. Author pack (`pack.yaml`, assets, docs).
|
||||
2. Run `stella pack validate` (schema + determinism).
|
||||
3. Generate bundle: `stella pack build --output my-pack.stella-pack.tgz`.
|
||||
4. Sign: `cosign sign-blob my-pack.stella-pack.tgz`.
|
||||
5. Publish: `stella pack push registry.example.com/org/my-pack:1.3.0`.
|
||||
6. Registry verifies signature, records provenance, and exposes pack via API.
|
||||
|
||||
---
|
||||
|
||||
## 12 · Compliance Checklist
|
||||
|
||||
- [ ] Manifest schema documented for all fields, including approvals, secrets, and outputs.
|
||||
- [ ] Determinism requirements outlined with plan/simulate semantics and CLI validation steps.
|
||||
- [ ] Signing + provenance expectations spelled out with cosign/DSSE references.
|
||||
- [ ] RBAC scopes (`Packs.*`) and tenant visibility rules captured.
|
||||
- [ ] Observability (metrics, logs, evidence) described for Task Runner integrations.
|
||||
- [ ] Compatibility matrix enumerates CLI/Runner requirements.
|
||||
- [ ] Publishing workflow documented with CLI commands.
|
||||
- [ ] Imposed rule reminder included at top of document.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
|
||||
Reference in New Issue
Block a user