Restructure solution layout by module
This commit is contained in:
master
@@ -1,16 +1,16 @@
|
||||
# Policy Examples
|
||||
|
||||
Sample `stella-dsl@1` policies illustrating common deployment personas. Each example includes commentary, CLI usage hints, and a compliance checklist.
|
||||
|
||||
| Example | Description |
|
||||
|---------|-------------|
|
||||
| [Baseline](baseline.md) | Balanced production defaults (block critical, respect strong VEX). |
|
||||
| [Serverless](serverless.md) | Aggressive blocking for serverless workloads (no High+, pinned base images). |
|
||||
| [Internal Only](internal-only.md) | Lenient policy for internal/dev environments with KEV safeguards. |
|
||||
|
||||
Policy source files (`*.stella`) live alongside the documentation so you can copy/paste or use `stella policy new --from file://...`.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26.*
|
||||
|
||||
# Policy Examples
|
||||
|
||||
Sample `stella-dsl@1` policies illustrating common deployment personas. Each example includes commentary, CLI usage hints, and a compliance checklist.
|
||||
|
||||
| Example | Description |
|
||||
|---------|-------------|
|
||||
| [Baseline](baseline.md) | Balanced production defaults (block critical, respect strong VEX). |
|
||||
| [Serverless](serverless.md) | Aggressive blocking for serverless workloads (no High+, pinned base images). |
|
||||
| [Internal Only](internal-only.md) | Lenient policy for internal/dev environments with KEV safeguards. |
|
||||
|
||||
Policy source files (`*.stella`) live alongside the documentation so you can copy/paste or use `stella policy new --from file://...`.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26.*
|
||||
|
||||
|
||||
@@ -1,79 +1,79 @@
|
||||
# Baseline Policy Example (`baseline.stella`)
|
||||
|
||||
This sample policy provides a balanced default for production workloads: block critical findings, require strong VEX justifications to suppress advisories, and warn on deprecated runtimes. Use it as a starting point for tenants that want guardrails without excessive noise.
|
||||
|
||||
```dsl
|
||||
policy "Baseline Production Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Block critical, escalate high, enforce VEX justifications."
|
||||
tags = ["baseline","production"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
map vendor_weight {
|
||||
source "GHSA" => +0.5
|
||||
source "OSV" => +0.0
|
||||
source "VendorX" => -0.2
|
||||
}
|
||||
env exposure_adjustments {
|
||||
if env.exposure == "internet" then +0.5
|
||||
if env.runtime == "legacy" then +0.3
|
||||
}
|
||||
}
|
||||
|
||||
rule block_critical priority 5 {
|
||||
when severity.normalized >= "Critical"
|
||||
then status := "blocked"
|
||||
because "Critical severity must be remediated before deploy."
|
||||
}
|
||||
|
||||
rule escalate_high_internet {
|
||||
when severity.normalized == "High"
|
||||
and env.exposure == "internet"
|
||||
then escalate to severity_band("Critical")
|
||||
because "High severity on internet-exposed asset escalates to critical."
|
||||
}
|
||||
|
||||
rule require_vex_justification {
|
||||
when vex.any(status in ["not_affected","fixed"])
|
||||
and vex.justification in ["component_not_present","vulnerable_code_not_present"]
|
||||
then status := vex.status
|
||||
annotate winning_statement := vex.latest().statementId
|
||||
because "Respect strong vendor VEX claims."
|
||||
}
|
||||
|
||||
rule alert_warn_eol_runtime priority 1 {
|
||||
when severity.normalized <= "Medium"
|
||||
and sbom.has_tag("runtime:eol")
|
||||
then warn message "Runtime marked as EOL; upgrade recommended."
|
||||
because "Deprecated runtime should be upgraded."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Commentary
|
||||
|
||||
- **Severity profile** tightens vendor weights and applies exposure modifiers so internet-facing/high severity pairs escalate automatically.
|
||||
- **VEX rule** only honours strong justifications, preventing weaker claims from hiding issues.
|
||||
- **Warnings first** – The `alert_warn_eol_runtime` rule name ensures it sorts before the require-VEX rule, keeping alerts visible without flipping to `RequiresVex`.
|
||||
- Works well as shared `tenant-global` baseline; use tenant overrides for stricter tolerant environments.
|
||||
|
||||
## Try it out
|
||||
|
||||
```bash
|
||||
stella policy new --policy-id P-baseline --template blank --open
|
||||
stella policy lint examples/policies/baseline.stella
|
||||
stella policy simulate P-baseline --candidate 1 --sbom sbom:sample-prod
|
||||
```
|
||||
|
||||
## Compliance checklist
|
||||
|
||||
- [ ] Policy compiled via `stella policy lint` without diagnostics.
|
||||
- [ ] Simulation diff reviewed against golden SBOM set.
|
||||
- [ ] Approval note documents rationale before promoting to production.
|
||||
- [ ] EOL runtime tags kept up to date in SBOM metadata.
|
||||
- [ ] VEX vendor allow-list reviewed quarterly.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26.*
|
||||
# Baseline Policy Example (`baseline.stella`)
|
||||
|
||||
This sample policy provides a balanced default for production workloads: block critical findings, require strong VEX justifications to suppress advisories, and warn on deprecated runtimes. Use it as a starting point for tenants that want guardrails without excessive noise.
|
||||
|
||||
```dsl
|
||||
policy "Baseline Production Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Block critical, escalate high, enforce VEX justifications."
|
||||
tags = ["baseline","production"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
map vendor_weight {
|
||||
source "GHSA" => +0.5
|
||||
source "OSV" => +0.0
|
||||
source "VendorX" => -0.2
|
||||
}
|
||||
env exposure_adjustments {
|
||||
if env.exposure == "internet" then +0.5
|
||||
if env.runtime == "legacy" then +0.3
|
||||
}
|
||||
}
|
||||
|
||||
rule block_critical priority 5 {
|
||||
when severity.normalized >= "Critical"
|
||||
then status := "blocked"
|
||||
because "Critical severity must be remediated before deploy."
|
||||
}
|
||||
|
||||
rule escalate_high_internet {
|
||||
when severity.normalized == "High"
|
||||
and env.exposure == "internet"
|
||||
then escalate to severity_band("Critical")
|
||||
because "High severity on internet-exposed asset escalates to critical."
|
||||
}
|
||||
|
||||
rule require_vex_justification {
|
||||
when vex.any(status in ["not_affected","fixed"])
|
||||
and vex.justification in ["component_not_present","vulnerable_code_not_present"]
|
||||
then status := vex.status
|
||||
annotate winning_statement := vex.latest().statementId
|
||||
because "Respect strong vendor VEX claims."
|
||||
}
|
||||
|
||||
rule alert_warn_eol_runtime priority 1 {
|
||||
when severity.normalized <= "Medium"
|
||||
and sbom.has_tag("runtime:eol")
|
||||
then warn message "Runtime marked as EOL; upgrade recommended."
|
||||
because "Deprecated runtime should be upgraded."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Commentary
|
||||
|
||||
- **Severity profile** tightens vendor weights and applies exposure modifiers so internet-facing/high severity pairs escalate automatically.
|
||||
- **VEX rule** only honours strong justifications, preventing weaker claims from hiding issues.
|
||||
- **Warnings first** – The `alert_warn_eol_runtime` rule name ensures it sorts before the require-VEX rule, keeping alerts visible without flipping to `RequiresVex`.
|
||||
- Works well as shared `tenant-global` baseline; use tenant overrides for stricter tolerant environments.
|
||||
|
||||
## Try it out
|
||||
|
||||
```bash
|
||||
stella policy new --policy-id P-baseline --template blank --open
|
||||
stella policy lint examples/policies/baseline.stella
|
||||
stella policy simulate P-baseline --candidate 1 --sbom sbom:sample-prod
|
||||
```
|
||||
|
||||
## Compliance checklist
|
||||
|
||||
- [ ] Policy compiled via `stella policy lint` without diagnostics.
|
||||
- [ ] Simulation diff reviewed against golden SBOM set.
|
||||
- [ ] Approval note documents rationale before promoting to production.
|
||||
- [ ] EOL runtime tags kept up to date in SBOM metadata.
|
||||
- [ ] VEX vendor allow-list reviewed quarterly.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26.*
|
||||
|
||||
@@ -1,46 +1,46 @@
|
||||
policy "Baseline Production Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Block critical, escalate high, enforce VEX justifications."
|
||||
tags = ["baseline","production"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
map vendor_weight {
|
||||
source "GHSA" => +0.5
|
||||
source "OSV" => +0.0
|
||||
source "VendorX" => -0.2
|
||||
}
|
||||
env exposure_adjustments {
|
||||
if env.exposure == "internet" then +0.5
|
||||
if env.runtime == "legacy" then +0.3
|
||||
}
|
||||
}
|
||||
|
||||
rule block_critical priority 5 {
|
||||
when severity.normalized >= "Critical"
|
||||
then status := "blocked"
|
||||
because "Critical severity must be remediated before deploy."
|
||||
}
|
||||
|
||||
rule escalate_high_internet {
|
||||
when severity.normalized == "High"
|
||||
and env.exposure == "internet"
|
||||
then escalate to severity_band("Critical")
|
||||
because "High severity on internet-exposed asset escalates to critical."
|
||||
}
|
||||
|
||||
rule require_vex_justification {
|
||||
when vex.any(status in ["not_affected","fixed"])
|
||||
and vex.justification in ["component_not_present","vulnerable_code_not_present"]
|
||||
then status := vex.status
|
||||
annotate winning_statement := vex.latest().statementId
|
||||
because "Respect strong vendor VEX claims."
|
||||
}
|
||||
|
||||
rule alert_warn_eol_runtime priority 1 {
|
||||
when severity.normalized <= "Medium"
|
||||
and sbom.has_tag("runtime:eol")
|
||||
then warn message "Runtime marked as EOL; upgrade recommended."
|
||||
because "Deprecated runtime should be upgraded."
|
||||
}
|
||||
}
|
||||
policy "Baseline Production Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Block critical, escalate high, enforce VEX justifications."
|
||||
tags = ["baseline","production"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
map vendor_weight {
|
||||
source "GHSA" => +0.5
|
||||
source "OSV" => +0.0
|
||||
source "VendorX" => -0.2
|
||||
}
|
||||
env exposure_adjustments {
|
||||
if env.exposure == "internet" then +0.5
|
||||
if env.runtime == "legacy" then +0.3
|
||||
}
|
||||
}
|
||||
|
||||
rule block_critical priority 5 {
|
||||
when severity.normalized >= "Critical"
|
||||
then status := "blocked"
|
||||
because "Critical severity must be remediated before deploy."
|
||||
}
|
||||
|
||||
rule escalate_high_internet {
|
||||
when severity.normalized == "High"
|
||||
and env.exposure == "internet"
|
||||
then escalate to severity_band("Critical")
|
||||
because "High severity on internet-exposed asset escalates to critical."
|
||||
}
|
||||
|
||||
rule require_vex_justification {
|
||||
when vex.any(status in ["not_affected","fixed"])
|
||||
and vex.justification in ["component_not_present","vulnerable_code_not_present"]
|
||||
then status := vex.status
|
||||
annotate winning_statement := vex.latest().statementId
|
||||
because "Respect strong vendor VEX claims."
|
||||
}
|
||||
|
||||
rule alert_warn_eol_runtime priority 1 {
|
||||
when severity.normalized <= "Medium"
|
||||
and sbom.has_tag("runtime:eol")
|
||||
then warn message "Runtime marked as EOL; upgrade recommended."
|
||||
because "Deprecated runtime should be upgraded."
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,34 +1,34 @@
|
||||
version: "1.0"
|
||||
metadata:
|
||||
description: Baseline production policy
|
||||
tags:
|
||||
- baseline
|
||||
- production
|
||||
rules:
|
||||
- name: Block Critical
|
||||
severity: [Critical]
|
||||
action: block
|
||||
|
||||
- name: Escalate High Internet
|
||||
severity: [High]
|
||||
environments: [internet]
|
||||
action:
|
||||
type: escalate
|
||||
escalate:
|
||||
minimumSeverity: Critical
|
||||
|
||||
- name: Require VEX justification
|
||||
sources: [NVD, GHSA]
|
||||
action:
|
||||
type: requireVex
|
||||
requireVex:
|
||||
vendors: [VendorX, VendorY]
|
||||
justifications:
|
||||
- component_not_present
|
||||
- vulnerable_code_not_present
|
||||
|
||||
- name: Alert warn EOL runtime
|
||||
priority: 1
|
||||
severity: [Low, Medium]
|
||||
tags: [runtime:eol]
|
||||
action: warn
|
||||
version: "1.0"
|
||||
metadata:
|
||||
description: Baseline production policy
|
||||
tags:
|
||||
- baseline
|
||||
- production
|
||||
rules:
|
||||
- name: Block Critical
|
||||
severity: [Critical]
|
||||
action: block
|
||||
|
||||
- name: Escalate High Internet
|
||||
severity: [High]
|
||||
environments: [internet]
|
||||
action:
|
||||
type: escalate
|
||||
escalate:
|
||||
minimumSeverity: Critical
|
||||
|
||||
- name: Require VEX justification
|
||||
sources: [NVD, GHSA]
|
||||
action:
|
||||
type: requireVex
|
||||
requireVex:
|
||||
vendors: [VendorX, VendorY]
|
||||
justifications:
|
||||
- component_not_present
|
||||
- vulnerable_code_not_present
|
||||
|
||||
- name: Alert warn EOL runtime
|
||||
priority: 1
|
||||
severity: [Low, Medium]
|
||||
tags: [runtime:eol]
|
||||
action: warn
|
||||
|
||||
@@ -1,72 +1,72 @@
|
||||
# Internal-Only Policy Example (`internal-only.stella`)
|
||||
|
||||
A relaxed profile for internal services and development environments: allow Medium severities with warnings, rely on VEX more heavily, but still block KEV/actively exploited advisories.
|
||||
|
||||
```dsl
|
||||
policy "Internal Only Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Lenient policy for internal / dev tenants."
|
||||
tags = ["internal","dev"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
env exposure_adjustments {
|
||||
if env.exposure == "internal" then -0.4
|
||||
if env.stage == "dev" then -0.6
|
||||
}
|
||||
}
|
||||
|
||||
rule block_kev priority 1 {
|
||||
when advisory.has_tag("kev")
|
||||
then status := "blocked"
|
||||
because "Known exploited vulnerabilities must be remediated."
|
||||
}
|
||||
|
||||
rule allow_medium_with_warning {
|
||||
when severity.normalized == "Medium"
|
||||
and env.exposure == "internal"
|
||||
then warn message "Medium severity permitted in internal environments."
|
||||
because "Allow Medium findings with warning for internal workloads."
|
||||
}
|
||||
|
||||
rule accept_vendor_vex {
|
||||
when vex.any(status in ["not_affected","fixed"])
|
||||
then status := vex.status
|
||||
annotate justification := vex.latest().justification
|
||||
because "Trust vendor VEX statements for internal scope."
|
||||
}
|
||||
|
||||
rule quiet_low_priority {
|
||||
when severity.normalized <= "Low"
|
||||
then ignore until "2026-01-01T00:00:00Z"
|
||||
because "Quiet low severity until next annual remediation sweep."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Commentary
|
||||
|
||||
- Suitable for staging/dev tenants with lower blast radius.
|
||||
- KEV advisories override lenient behaviour to maintain minimum security bar.
|
||||
- Warnings ensure Medium findings stay visible in dashboards and CLI outputs.
|
||||
- Quiet rule enforces planned clean-up date; update before expiry.
|
||||
|
||||
## Try it out
|
||||
|
||||
```bash
|
||||
stella policy lint examples/policies/internal-only.stella
|
||||
stella policy simulate P-internal --candidate 1 \
|
||||
--sbom sbom:internal-service --env exposure=internal --env stage=dev
|
||||
```
|
||||
|
||||
## Compliance checklist
|
||||
|
||||
- [ ] Tenant classified as internal-only with documented risk acceptance.
|
||||
- [ ] KEV feed synced (Concelier) and tags confirmed before relying on rule.
|
||||
- [ ] Quiet expiry tracked; remediation backlog updated prior to deadline.
|
||||
- [ ] Developers informed that warnings still affect quality score.
|
||||
- [ ] Policy not used for production or internet-exposed services.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26.*
|
||||
# Internal-Only Policy Example (`internal-only.stella`)
|
||||
|
||||
A relaxed profile for internal services and development environments: allow Medium severities with warnings, rely on VEX more heavily, but still block KEV/actively exploited advisories.
|
||||
|
||||
```dsl
|
||||
policy "Internal Only Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Lenient policy for internal / dev tenants."
|
||||
tags = ["internal","dev"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
env exposure_adjustments {
|
||||
if env.exposure == "internal" then -0.4
|
||||
if env.stage == "dev" then -0.6
|
||||
}
|
||||
}
|
||||
|
||||
rule block_kev priority 1 {
|
||||
when advisory.has_tag("kev")
|
||||
then status := "blocked"
|
||||
because "Known exploited vulnerabilities must be remediated."
|
||||
}
|
||||
|
||||
rule allow_medium_with_warning {
|
||||
when severity.normalized == "Medium"
|
||||
and env.exposure == "internal"
|
||||
then warn message "Medium severity permitted in internal environments."
|
||||
because "Allow Medium findings with warning for internal workloads."
|
||||
}
|
||||
|
||||
rule accept_vendor_vex {
|
||||
when vex.any(status in ["not_affected","fixed"])
|
||||
then status := vex.status
|
||||
annotate justification := vex.latest().justification
|
||||
because "Trust vendor VEX statements for internal scope."
|
||||
}
|
||||
|
||||
rule quiet_low_priority {
|
||||
when severity.normalized <= "Low"
|
||||
then ignore until "2026-01-01T00:00:00Z"
|
||||
because "Quiet low severity until next annual remediation sweep."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Commentary
|
||||
|
||||
- Suitable for staging/dev tenants with lower blast radius.
|
||||
- KEV advisories override lenient behaviour to maintain minimum security bar.
|
||||
- Warnings ensure Medium findings stay visible in dashboards and CLI outputs.
|
||||
- Quiet rule enforces planned clean-up date; update before expiry.
|
||||
|
||||
## Try it out
|
||||
|
||||
```bash
|
||||
stella policy lint examples/policies/internal-only.stella
|
||||
stella policy simulate P-internal --candidate 1 \
|
||||
--sbom sbom:internal-service --env exposure=internal --env stage=dev
|
||||
```
|
||||
|
||||
## Compliance checklist
|
||||
|
||||
- [ ] Tenant classified as internal-only with documented risk acceptance.
|
||||
- [ ] KEV feed synced (Concelier) and tags confirmed before relying on rule.
|
||||
- [ ] Quiet expiry tracked; remediation backlog updated prior to deadline.
|
||||
- [ ] Developers informed that warnings still affect quality score.
|
||||
- [ ] Policy not used for production or internet-exposed services.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26.*
|
||||
|
||||
@@ -1,39 +1,39 @@
|
||||
policy "Internal Only Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Lenient policy for internal / dev tenants."
|
||||
tags = ["internal","dev"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
env exposure_adjustments {
|
||||
if env.exposure == "internal" then -0.4
|
||||
if env.stage == "dev" then -0.6
|
||||
}
|
||||
}
|
||||
|
||||
rule block_kev priority 1 {
|
||||
when advisory.has_tag("kev")
|
||||
then status := "blocked"
|
||||
because "Known exploited vulnerabilities must be remediated."
|
||||
}
|
||||
|
||||
rule allow_medium_with_warning {
|
||||
when severity.normalized == "Medium"
|
||||
and env.exposure == "internal"
|
||||
then warn message "Medium severity permitted in internal environments."
|
||||
because "Allow Medium findings with warning for internal workloads."
|
||||
}
|
||||
|
||||
rule accept_vendor_vex {
|
||||
when vex.any(status in ["not_affected","fixed"])
|
||||
then status := vex.status
|
||||
annotate justification := vex.latest().justification
|
||||
because "Trust vendor VEX statements for internal scope."
|
||||
}
|
||||
|
||||
rule quiet_low_priority {
|
||||
when severity.normalized <= "Low"
|
||||
then ignore until "2026-01-01T00:00:00Z"
|
||||
because "Quiet low severity until next annual remediation sweep."
|
||||
}
|
||||
}
|
||||
policy "Internal Only Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Lenient policy for internal / dev tenants."
|
||||
tags = ["internal","dev"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
env exposure_adjustments {
|
||||
if env.exposure == "internal" then -0.4
|
||||
if env.stage == "dev" then -0.6
|
||||
}
|
||||
}
|
||||
|
||||
rule block_kev priority 1 {
|
||||
when advisory.has_tag("kev")
|
||||
then status := "blocked"
|
||||
because "Known exploited vulnerabilities must be remediated."
|
||||
}
|
||||
|
||||
rule allow_medium_with_warning {
|
||||
when severity.normalized == "Medium"
|
||||
and env.exposure == "internal"
|
||||
then warn message "Medium severity permitted in internal environments."
|
||||
because "Allow Medium findings with warning for internal workloads."
|
||||
}
|
||||
|
||||
rule accept_vendor_vex {
|
||||
when vex.any(status in ["not_affected","fixed"])
|
||||
then status := vex.status
|
||||
annotate justification := vex.latest().justification
|
||||
because "Trust vendor VEX statements for internal scope."
|
||||
}
|
||||
|
||||
rule quiet_low_priority {
|
||||
when severity.normalized <= "Low"
|
||||
then ignore until "2026-01-01T00:00:00Z"
|
||||
because "Quiet low severity until next annual remediation sweep."
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,31 +1,31 @@
|
||||
version: "1.0"
|
||||
metadata:
|
||||
description: Relaxed internal/development policy
|
||||
tags:
|
||||
- internal
|
||||
- dev
|
||||
rules:
|
||||
- name: Block KEV advisories
|
||||
tags: [kev]
|
||||
action: block
|
||||
|
||||
- name: Warn medium severity
|
||||
severity: [Medium]
|
||||
environments: [internal]
|
||||
action: warn
|
||||
|
||||
- name: Accept vendor VEX
|
||||
action:
|
||||
type: require_vex
|
||||
requireVex:
|
||||
vendors: [VendorX, VendorY]
|
||||
justifications:
|
||||
- component_not_present
|
||||
- vulnerable_code_not_present
|
||||
|
||||
- name: Quiet low severity
|
||||
severity: [Low, Informational]
|
||||
action:
|
||||
type: ignore
|
||||
until: 2026-01-01T00:00:00Z
|
||||
justification: "Deferred to annual remediation cycle"
|
||||
version: "1.0"
|
||||
metadata:
|
||||
description: Relaxed internal/development policy
|
||||
tags:
|
||||
- internal
|
||||
- dev
|
||||
rules:
|
||||
- name: Block KEV advisories
|
||||
tags: [kev]
|
||||
action: block
|
||||
|
||||
- name: Warn medium severity
|
||||
severity: [Medium]
|
||||
environments: [internal]
|
||||
action: warn
|
||||
|
||||
- name: Accept vendor VEX
|
||||
action:
|
||||
type: require_vex
|
||||
requireVex:
|
||||
vendors: [VendorX, VendorY]
|
||||
justifications:
|
||||
- component_not_present
|
||||
- vulnerable_code_not_present
|
||||
|
||||
- name: Quiet low severity
|
||||
severity: [Low, Informational]
|
||||
action:
|
||||
type: ignore
|
||||
until: 2026-01-01T00:00:00Z
|
||||
justification: "Deferred to annual remediation cycle"
|
||||
|
||||
@@ -1,72 +1,72 @@
|
||||
# Serverless Policy Example (`serverless.stella`)
|
||||
|
||||
Optimised for short-lived serverless workloads: focus on runtime integrity, disallow vulnerable layers entirely, and permit temporary suppressions only with strict justification windows.
|
||||
|
||||
```dsl
|
||||
policy "Serverless Tight Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Aggressive blocking for serverless runtimes."
|
||||
tags = ["serverless","prod","strict"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
env runtime_overrides {
|
||||
if env.runtime == "serverless" then +0.7
|
||||
if env.runtime == "batch" then +0.2
|
||||
}
|
||||
}
|
||||
|
||||
rule block_any_high {
|
||||
when severity.normalized >= "High"
|
||||
then status := "blocked"
|
||||
because "Serverless workloads block High+ severities."
|
||||
}
|
||||
|
||||
rule forbid_unpinned_base {
|
||||
when sbom.has_tag("image:latest-tag")
|
||||
then status := "blocked"
|
||||
because "Base image must be pinned (no :latest)."
|
||||
}
|
||||
|
||||
rule zero_tolerance_vex {
|
||||
when vex.any(status == "not_affected")
|
||||
then requireVex { vendors = ["VendorX","VendorY"], justifications = ["component_not_present"] }
|
||||
because "Allow not_affected only from trusted vendors with strongest justification."
|
||||
}
|
||||
|
||||
rule temporary_quiet {
|
||||
when env.deployment == "canary"
|
||||
and severity.normalized == "Medium"
|
||||
then ignore until coalesce(env.quietUntil, "2025-12-31T00:00:00Z")
|
||||
because "Allow short canary quiet window while fix rolls out."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Commentary
|
||||
|
||||
- Designed for serverless tenants where redeploy cost is low and failing fast is preferred.
|
||||
- `forbid_unpinned_base` enforces supply-chain best practices.
|
||||
- `temporary_quiet` ensures quiet windows expire automatically; require deployments to set `env.quietUntil`.
|
||||
- Intended to be layered on top of baseline (override per tenant) or used standalone for serverless-only accounts.
|
||||
|
||||
## Try it out
|
||||
|
||||
```bash
|
||||
stella policy lint examples/policies/serverless.stella
|
||||
stella policy simulate P-serverless --candidate 1 \
|
||||
--sbom sbom:lambda-hello --env runtime=serverless --env deployment=canary
|
||||
```
|
||||
|
||||
## Compliance checklist
|
||||
|
||||
- [ ] Quiet window expirations tracked and documented.
|
||||
- [ ] Trusted VEX vendor list reviewed quarterly.
|
||||
- [ ] Deployment pipeline enforces pinned base images before approval.
|
||||
- [ ] Canary deployments monitored for recurrence before ignoring Medium severity.
|
||||
- [ ] Serverless teams acknowledge runbook for blocked deployments.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26.*
|
||||
|
||||
# Serverless Policy Example (`serverless.stella`)
|
||||
|
||||
Optimised for short-lived serverless workloads: focus on runtime integrity, disallow vulnerable layers entirely, and permit temporary suppressions only with strict justification windows.
|
||||
|
||||
```dsl
|
||||
policy "Serverless Tight Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Aggressive blocking for serverless runtimes."
|
||||
tags = ["serverless","prod","strict"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
env runtime_overrides {
|
||||
if env.runtime == "serverless" then +0.7
|
||||
if env.runtime == "batch" then +0.2
|
||||
}
|
||||
}
|
||||
|
||||
rule block_any_high {
|
||||
when severity.normalized >= "High"
|
||||
then status := "blocked"
|
||||
because "Serverless workloads block High+ severities."
|
||||
}
|
||||
|
||||
rule forbid_unpinned_base {
|
||||
when sbom.has_tag("image:latest-tag")
|
||||
then status := "blocked"
|
||||
because "Base image must be pinned (no :latest)."
|
||||
}
|
||||
|
||||
rule zero_tolerance_vex {
|
||||
when vex.any(status == "not_affected")
|
||||
then requireVex { vendors = ["VendorX","VendorY"], justifications = ["component_not_present"] }
|
||||
because "Allow not_affected only from trusted vendors with strongest justification."
|
||||
}
|
||||
|
||||
rule temporary_quiet {
|
||||
when env.deployment == "canary"
|
||||
and severity.normalized == "Medium"
|
||||
then ignore until coalesce(env.quietUntil, "2025-12-31T00:00:00Z")
|
||||
because "Allow short canary quiet window while fix rolls out."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Commentary
|
||||
|
||||
- Designed for serverless tenants where redeploy cost is low and failing fast is preferred.
|
||||
- `forbid_unpinned_base` enforces supply-chain best practices.
|
||||
- `temporary_quiet` ensures quiet windows expire automatically; require deployments to set `env.quietUntil`.
|
||||
- Intended to be layered on top of baseline (override per tenant) or used standalone for serverless-only accounts.
|
||||
|
||||
## Try it out
|
||||
|
||||
```bash
|
||||
stella policy lint examples/policies/serverless.stella
|
||||
stella policy simulate P-serverless --candidate 1 \
|
||||
--sbom sbom:lambda-hello --env runtime=serverless --env deployment=canary
|
||||
```
|
||||
|
||||
## Compliance checklist
|
||||
|
||||
- [ ] Quiet window expirations tracked and documented.
|
||||
- [ ] Trusted VEX vendor list reviewed quarterly.
|
||||
- [ ] Deployment pipeline enforces pinned base images before approval.
|
||||
- [ ] Canary deployments monitored for recurrence before ignoring Medium severity.
|
||||
- [ ] Serverless teams acknowledge runbook for blocked deployments.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26.*
|
||||
|
||||
|
||||
@@ -1,39 +1,39 @@
|
||||
policy "Serverless Tight Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Aggressive blocking for serverless runtimes."
|
||||
tags = ["serverless","prod","strict"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
env runtime_overrides {
|
||||
if env.runtime == "serverless" then +0.7
|
||||
if env.runtime == "batch" then +0.2
|
||||
}
|
||||
}
|
||||
|
||||
rule block_any_high {
|
||||
when severity.normalized >= "High"
|
||||
then status := "blocked"
|
||||
because "Serverless workloads block High+ severities."
|
||||
}
|
||||
|
||||
rule forbid_unpinned_base {
|
||||
when sbom.has_tag("image:latest-tag")
|
||||
then status := "blocked"
|
||||
because "Base image must be pinned (no :latest)."
|
||||
}
|
||||
|
||||
rule zero_tolerance_vex {
|
||||
when vex.any(status == "not_affected")
|
||||
then requireVex { vendors = ["VendorX","VendorY"], justifications = ["component_not_present"] }
|
||||
because "Allow not_affected only from trusted vendors with strongest justification."
|
||||
}
|
||||
|
||||
rule temporary_quiet {
|
||||
when env.deployment == "canary"
|
||||
and severity.normalized == "Medium"
|
||||
then ignore until coalesce(env.quietUntil, "2025-12-31T00:00:00Z")
|
||||
because "Allow short canary quiet window while fix rolls out."
|
||||
}
|
||||
}
|
||||
|
||||
policy "Serverless Tight Policy" syntax "stella-dsl@1" {
|
||||
metadata {
|
||||
description = "Aggressive blocking for serverless runtimes."
|
||||
tags = ["serverless","prod","strict"]
|
||||
}
|
||||
|
||||
profile severity {
|
||||
env runtime_overrides {
|
||||
if env.runtime == "serverless" then +0.7
|
||||
if env.runtime == "batch" then +0.2
|
||||
}
|
||||
}
|
||||
|
||||
rule block_any_high {
|
||||
when severity.normalized >= "High"
|
||||
then status := "blocked"
|
||||
because "Serverless workloads block High+ severities."
|
||||
}
|
||||
|
||||
rule forbid_unpinned_base {
|
||||
when sbom.has_tag("image:latest-tag")
|
||||
then status := "blocked"
|
||||
because "Base image must be pinned (no :latest)."
|
||||
}
|
||||
|
||||
rule zero_tolerance_vex {
|
||||
when vex.any(status == "not_affected")
|
||||
then requireVex { vendors = ["VendorX","VendorY"], justifications = ["component_not_present"] }
|
||||
because "Allow not_affected only from trusted vendors with strongest justification."
|
||||
}
|
||||
|
||||
rule temporary_quiet {
|
||||
when env.deployment == "canary"
|
||||
and severity.normalized == "Medium"
|
||||
then ignore until coalesce(env.quietUntil, "2025-12-31T00:00:00Z")
|
||||
because "Allow short canary quiet window while fix rolls out."
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -1,41 +1,41 @@
|
||||
version: "1.0"
|
||||
metadata:
|
||||
description: Strict policy for serverless workloads
|
||||
tags:
|
||||
- serverless
|
||||
- prod
|
||||
- strict
|
||||
exceptions:
|
||||
effects:
|
||||
- id: suppress-canary
|
||||
name: Canary Freeze
|
||||
effect: suppress
|
||||
routingTemplate: secops-approvers
|
||||
maxDurationDays: 14
|
||||
routingTemplates:
|
||||
- id: secops-approvers
|
||||
authorityRouteId: governance.secops
|
||||
requireMfa: true
|
||||
rules:
|
||||
- name: Block High And Above
|
||||
severity: [High, Critical]
|
||||
action: block
|
||||
|
||||
- name: Forbid Unpinned Base Images
|
||||
tags: [image:latest-tag]
|
||||
action: block
|
||||
|
||||
- name: Require Trusted VEX
|
||||
action:
|
||||
type: require_vex
|
||||
requireVex:
|
||||
vendors: [VendorX, VendorY]
|
||||
justifications: [component_not_present]
|
||||
|
||||
- name: Quiet Medium Canary
|
||||
severity: [Medium]
|
||||
environments: [canary]
|
||||
action:
|
||||
type: ignore
|
||||
until: 2025-12-31T00:00:00Z
|
||||
justification: "Temporary canary exception"
|
||||
version: "1.0"
|
||||
metadata:
|
||||
description: Strict policy for serverless workloads
|
||||
tags:
|
||||
- serverless
|
||||
- prod
|
||||
- strict
|
||||
exceptions:
|
||||
effects:
|
||||
- id: suppress-canary
|
||||
name: Canary Freeze
|
||||
effect: suppress
|
||||
routingTemplate: secops-approvers
|
||||
maxDurationDays: 14
|
||||
routingTemplates:
|
||||
- id: secops-approvers
|
||||
authorityRouteId: governance.secops
|
||||
requireMfa: true
|
||||
rules:
|
||||
- name: Block High And Above
|
||||
severity: [High, Critical]
|
||||
action: block
|
||||
|
||||
- name: Forbid Unpinned Base Images
|
||||
tags: [image:latest-tag]
|
||||
action: block
|
||||
|
||||
- name: Require Trusted VEX
|
||||
action:
|
||||
type: require_vex
|
||||
requireVex:
|
||||
vendors: [VendorX, VendorY]
|
||||
justifications: [component_not_present]
|
||||
|
||||
- name: Quiet Medium Canary
|
||||
severity: [Medium]
|
||||
environments: [canary]
|
||||
action:
|
||||
type: ignore
|
||||
until: 2025-12-31T00:00:00Z
|
||||
justification: "Temporary canary exception"
|
||||
|
||||
@@ -1,154 +1,154 @@
|
||||
# StellaOps Console – Guided Tours (Sprint 23)
|
||||
|
||||
> **Audience:** Field enablement, Docs Guild writers, Console product leads, and onboarding facilitators.
|
||||
> **Scope:** Ready-to-run walkthrough scripts that showcase the Console’s critical workflows—triage, audit evidence, and policy rollout—while reinforcing CLI parity, tenancy, and offline expectations.
|
||||
|
||||
These tours stitch together the primary Console workspaces so trainers can deliver consistent demos or capture annotated media (screenshots/GIFs). Each tour lists prerequisites, live steps, CLI fallbacks, and assets to capture. Use them alongside the workspace dossiers in `/docs/ui/*.md` when preparing customer sessions or internal dry runs.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Prerequisites & Setup
|
||||
|
||||
- **Environment:** Console deployed per [deployment guide](../deploy/console.md) with Scheduler, Policy Engine, Concelier, Excititor, SBOM Service, and Downloads manifest available.
|
||||
- **Tenant & data:** Sample tenant populated with recent scans, findings, runs, and export bundles. Ensure Offline Kit snapshot exists for offline callouts.
|
||||
- **Scopes:** Presenter identity must hold `ui.read`, `findings.read`, `policy:*` (read/write/simulate/approve), `runs.read`, `downloads.read`, `aoc:verify`, and `ui.telemetry` to surface telemetry banners.
|
||||
- **Browser tooling:** Enable screen recording (1920×1080 @ 60 fps) and keyboard overlay if capturing walkthroughs.
|
||||
- **CLI parity:** Have `stella` CLI configured against the same tenant; keep terminal window ready for parity steps.
|
||||
- **Assets directory:** Store captures under `docs/assets/ui/tours/` (see [`README`](../assets/ui/tours/README.md)) with the naming convention `<tour>-step-<nn>.png` and `<tour>-flow.gif`.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Tour A — Critical Finding Triage
|
||||
|
||||
**Persona:** Security analyst responding to a fresh high-severity finding.
|
||||
**Goal:** Navigate from dashboard signal to remediation decision, highlighting explain trails and run evidence.
|
||||
|
||||
### 2.1 Key references
|
||||
- [Console overview](../ui/console-overview.md) – tenant switching, status ticker.
|
||||
- [Navigation](../ui/navigation.md) – command palette, shortcuts.
|
||||
- [Findings workspace](../ui/findings.md) – filters, explain drawer, exports.
|
||||
- [Runs workspace](../ui/runs.md) – live progress, evidence downloads.
|
||||
|
||||
### 2.2 Live walkthrough
|
||||
1. **Start on Dashboard:** Show status ticker surfacing new `Critical` badge. Call out tenant pill and offline banner behaviour (§3 of console overview).
|
||||
2. **Command palette jump:** Press `Ctrl/Cmd+K`, type `Findings`, hit `Enter`. Narrate keyboard accessibility from navigation guide.
|
||||
3. **Apply global filters:** Open filter tray (`Shift+F`), set `Severity = Critical`, `Status = affected`, time window `Last 24h`. Mention saved view presets triggered with `Ctrl/Cmd+1`.
|
||||
4. **Open explain drawer:** Select top finding, trigger `Explain` tab. Highlight rule chain, VEX impact, and evidence references (§5 of findings doc).
|
||||
5. **Dive into related run:** Click `Run ID` link inside explain drawer → opens Runs detail drawer filtered by run ID. Show segmented progress SSE updates.
|
||||
6. **Capture evidence:** In Runs drawer, download evidence bundle; note CLI parity `stella runs export --run <id>`. Mention offline fallback (download queue offline banner from runs doc §10).
|
||||
7. **Escalate / create ticket:** Use bulk action or comment (if configured) to demonstrate optional integration; mention Authority audit log tie-in.
|
||||
8. **Wrap with CLI:** Pop terminal and run `stella findings explain --policy <id> --finding <key> --format markdown` to show reproducibility.
|
||||
|
||||
### 2.3 Capture checklist
|
||||
- `docs/assets/ui/tours/triage-step-01.png` — dashboard ticker highlighting new criticals.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-03.png` — filter tray with severity/time window applied.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-04.png` — explain drawer evidence tab.
|
||||
|
||||
- `docs/assets/ui/tours/triage-flow.gif` — 20 s screen recording of steps 1–5 with annotations.
|
||||
|
||||
|
||||
### 2.4 Talking points & callouts
|
||||
- Call out Aggregation-Only boundaries: findings reference Concelier/Excititor provenance, UI stays read-only.
|
||||
- Mention `ui_route_render_seconds` telemetry for demos (see [observability guide](../observability/ui-telemetry.md)).
|
||||
- Offline note: highlight offline banner that appears if `/console/status` heartbeat fails (§6 of console overview).
|
||||
|
||||
---
|
||||
|
||||
## 3 · Tour B — Audit Evidence Export
|
||||
|
||||
**Persona:** Compliance lead compiling artefacts for an external audit.
|
||||
**Goal:** Retrieve signed manifests, export run/finding evidence, and verify parity with Offline Kit.
|
||||
|
||||
### 3.1 Key references
|
||||
- [Downloads workspace](../ui/downloads.md) – manifest, parity, export queue.
|
||||
- [Runs workspace](../ui/runs.md) – evidence panel.
|
||||
- [Console security posture](../security/console-security.md) – evidence handling.
|
||||
- [CLI vs UI parity matrix](../cli-vs-ui-parity.md).
|
||||
|
||||
### 3.2 Live walkthrough
|
||||
1. **Open Downloads:** Use left rail or command palette to reach `/console/downloads`. Point out snapshot banner, cosign verification status.
|
||||
2. **Verify manifest:** Click “Verify signature” quick action; narrate parity with `cosign verify --key <key> manifest.json` from downloads doc §3.
|
||||
3. **Compare Offline Kit:** Switch to “Offline Kits” tab, run parity check to ensure kit digest matches manifest. Demonstrate offline guidance (downloads doc §6).
|
||||
4. **Queue evidence bundle:** Navigate to Runs workspace, choose relevant run, trigger “Bundle for offline” (runs doc §8).
|
||||
5. **Return to Downloads → Exports tab:** Show newly generated evidence bundle with retention countdown.
|
||||
6. **Download & inspect:** Open detail drawer, copy CLI command `stella runs export --run <id> --bundle`. Mention location for storing evidence.
|
||||
7. **Log parity results:** Use notes or tags to flag audit package completion (if notifications configured).
|
||||
8. **CLI parity close-out:** Run `stella downloads manifest --channel stable` to mirror UI manifest retrieval. Confirm digests match.
|
||||
|
||||
### 3.3 Capture checklist
|
||||
- `docs/assets/ui/tours/audit-step-02.png` — manifest verification banner (green).
|
||||
|
||||
- `docs/assets/ui/tours/audit-step-05.png` — exports tab showing evidence bundle ready.
|
||||
|
||||
- `docs/assets/ui/tours/audit-flow.gif` — 25 s capture from manifest view through export download.
|
||||
|
||||
|
||||
### 3.4 Talking points & callouts
|
||||
- Stress deterministic manifests and Cosign signatures; reference deployment doc for TLS/CSP alignment.
|
||||
- Highlight audit trail: downloads actions recorded via `ui.download.commandCopied` logs and Authority audit entries.
|
||||
- Offline note: show guidance when parity check detects stale manifest; mention CLI fallback for sealed networks.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Tour C — Policy Rollout & Promotion
|
||||
|
||||
**Persona:** Policy owner preparing and promoting a new ruleset.
|
||||
**Goal:** Draft review, simulation, approval, and promotion within Console, with CLI parity.
|
||||
|
||||
### 4.1 Key references
|
||||
- [Policies workspace](../ui/policies.md) – simulations, approvals, promotion.
|
||||
- [Policy editor](../ui/policy-editor.md) – Monaco editor, linting.
|
||||
- [Runs workspace](../ui/runs.md) – policy run monitoring.
|
||||
- [Security posture](../security/console-security.md) – fresh-auth and scopes.
|
||||
|
||||
### 4.2 Live walkthrough
|
||||
1. **Policy overview:** Open `/console/policies`, filter by “Staged” state. Highlight list columns (owners, pending approvals).
|
||||
2. **Enter draft:** Select policy → open editor view. Show checklist sidebar (lint, simulation, determinism).
|
||||
3. **Run lint & simulation:** Hit `Run lint`, then `Run simulation`. Narrate asynchronous progress with SSE ticker; reference CLI `stella policy simulate`.
|
||||
4. **Review diff:** Open simulation diff view to compare Active vs Staged; highlight severity up/down badges (§6 of policies doc).
|
||||
5. **Approval workflow:** Assign reviewer, show comment thread. Trigger fresh-auth prompt when clicking “Submit for review” (security doc §1.2).
|
||||
6. **Promote policy:** After approvals, open promotion dialog, choose “Full run”. Emphasise policy run scheduling and RBAC.
|
||||
7. **Monitor run:** Jump to Runs workspace, filter by policy run; show progress segments and findings delta metrics.
|
||||
8. **Publish CLI parity:** Execute `stella policy promote --policy <id> --revision <rev> --run-mode full` to reinforce reproducibility.
|
||||
|
||||
### 4.3 Capture checklist
|
||||
- `docs/assets/ui/tours/policy-step-02.png` — editor checklist with lint/simulation statuses.
|
||||
|
||||
- `docs/assets/ui/tours/policy-step-04.png` — simulation diff comparing Active vs Staged.
|
||||
|
||||
- `docs/assets/ui/tours/policy-flow.gif` — 30 s clip from draft view through promotion confirmation.
|
||||
|
||||
|
||||
### 4.4 Talking points & callouts
|
||||
- Stress governance: approvals logged with correlation IDs, fresh-auth enforced.
|
||||
- Mention telemetry metrics (`ui_tenant_switch_total`, policy run charts) for monitoring adoption.
|
||||
- Offline note: show how promotion dialog surfaces CLI script when in sealed mode; reference offline guidance in policies doc §10.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Production Tips & Media Hygiene
|
||||
|
||||
- **Script timing:** Keep each tour ≤ 3 minutes live demo, ≤ 30 s GIF. Include captions for accessibility.
|
||||
- **Annotations:** Use consistent callouts (numbered badges, short labels) overlayed in post-processing; ensure final media compressed but legible (< 2 MB PNG, < 8 MB GIF). See `docs/assets/ui/tours/README.md` for shared template guidance.
|
||||
- **Versioning:** Annotated assets should include Console build hash in metadata or caption (align with `/console/downloads` manifest version).
|
||||
- **Storage:** Commit final media under `docs/assets/ui/tours/` and update `.gitattributes` if smudge filters required. Note large GIFs may need Git LFS depending on repository policy.
|
||||
- **Review cadence:** Re-run tours whenever workspaces change navigation or introduce new buttons; log updates in `docs/updates/<date>-console-tours.md` (create if absent).
|
||||
|
||||
---
|
||||
|
||||
## 6 · Compliance Checklist
|
||||
|
||||
- [x] Tour scripts cover triage, audit evidence, and policy rollout scenarios requested in DOCS-CONSOLE-23-017.
|
||||
- [x] Each tour references authoritative workspace docs and CLI parity commands.
|
||||
- [x] Capture checklist names align with `docs/assets/ui/tours/` convention.
|
||||
- [x] Offline and sealed-mode notes included for every flow.
|
||||
- [x] Security considerations (scopes, fresh-auth, evidence handling) highlighted.
|
||||
- [x] Observability/telemetry pointers surfaced to support Ops follow-up.
|
||||
- [x] Media hygiene guidance documented (assets, compression, versioning).
|
||||
- [x] Document timestamp reflects Sprint 23 delivery.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 23).*
|
||||
# StellaOps Console – Guided Tours (Sprint 23)
|
||||
|
||||
> **Audience:** Field enablement, Docs Guild writers, Console product leads, and onboarding facilitators.
|
||||
> **Scope:** Ready-to-run walkthrough scripts that showcase the Console’s critical workflows—triage, audit evidence, and policy rollout—while reinforcing CLI parity, tenancy, and offline expectations.
|
||||
|
||||
These tours stitch together the primary Console workspaces so trainers can deliver consistent demos or capture annotated media (screenshots/GIFs). Each tour lists prerequisites, live steps, CLI fallbacks, and assets to capture. Use them alongside the workspace dossiers in `/docs/ui/*.md` when preparing customer sessions or internal dry runs.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Prerequisites & Setup
|
||||
|
||||
- **Environment:** Console deployed per [deployment guide](../deploy/console.md) with Scheduler, Policy Engine, Concelier, Excititor, SBOM Service, and Downloads manifest available.
|
||||
- **Tenant & data:** Sample tenant populated with recent scans, findings, runs, and export bundles. Ensure Offline Kit snapshot exists for offline callouts.
|
||||
- **Scopes:** Presenter identity must hold `ui.read`, `findings.read`, `policy:*` (read/write/simulate/approve), `runs.read`, `downloads.read`, `aoc:verify`, and `ui.telemetry` to surface telemetry banners.
|
||||
- **Browser tooling:** Enable screen recording (1920×1080 @ 60 fps) and keyboard overlay if capturing walkthroughs.
|
||||
- **CLI parity:** Have `stella` CLI configured against the same tenant; keep terminal window ready for parity steps.
|
||||
- **Assets directory:** Store captures under `docs/assets/ui/tours/` (see [`README`](../assets/ui/tours/README.md)) with the naming convention `<tour>-step-<nn>.png` and `<tour>-flow.gif`.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Tour A — Critical Finding Triage
|
||||
|
||||
**Persona:** Security analyst responding to a fresh high-severity finding.
|
||||
**Goal:** Navigate from dashboard signal to remediation decision, highlighting explain trails and run evidence.
|
||||
|
||||
### 2.1 Key references
|
||||
- [Console overview](../ui/console-overview.md) – tenant switching, status ticker.
|
||||
- [Navigation](../ui/navigation.md) – command palette, shortcuts.
|
||||
- [Findings workspace](../ui/findings.md) – filters, explain drawer, exports.
|
||||
- [Runs workspace](../ui/runs.md) – live progress, evidence downloads.
|
||||
|
||||
### 2.2 Live walkthrough
|
||||
1. **Start on Dashboard:** Show status ticker surfacing new `Critical` badge. Call out tenant pill and offline banner behaviour (§3 of console overview).
|
||||
2. **Command palette jump:** Press `Ctrl/Cmd+K`, type `Findings`, hit `Enter`. Narrate keyboard accessibility from navigation guide.
|
||||
3. **Apply global filters:** Open filter tray (`Shift+F`), set `Severity = Critical`, `Status = affected`, time window `Last 24h`. Mention saved view presets triggered with `Ctrl/Cmd+1`.
|
||||
4. **Open explain drawer:** Select top finding, trigger `Explain` tab. Highlight rule chain, VEX impact, and evidence references (§5 of findings doc).
|
||||
5. **Dive into related run:** Click `Run ID` link inside explain drawer → opens Runs detail drawer filtered by run ID. Show segmented progress SSE updates.
|
||||
6. **Capture evidence:** In Runs drawer, download evidence bundle; note CLI parity `stella runs export --run <id>`. Mention offline fallback (download queue offline banner from runs doc §10).
|
||||
7. **Escalate / create ticket:** Use bulk action or comment (if configured) to demonstrate optional integration; mention Authority audit log tie-in.
|
||||
8. **Wrap with CLI:** Pop terminal and run `stella findings explain --policy <id> --finding <key> --format markdown` to show reproducibility.
|
||||
|
||||
### 2.3 Capture checklist
|
||||
- `docs/assets/ui/tours/triage-step-01.png` — dashboard ticker highlighting new criticals.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-03.png` — filter tray with severity/time window applied.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-04.png` — explain drawer evidence tab.
|
||||
|
||||
- `docs/assets/ui/tours/triage-flow.gif` — 20 s screen recording of steps 1–5 with annotations.
|
||||
|
||||
|
||||
### 2.4 Talking points & callouts
|
||||
- Call out Aggregation-Only boundaries: findings reference Concelier/Excititor provenance, UI stays read-only.
|
||||
- Mention `ui_route_render_seconds` telemetry for demos (see [observability guide](../observability/ui-telemetry.md)).
|
||||
- Offline note: highlight offline banner that appears if `/console/status` heartbeat fails (§6 of console overview).
|
||||
|
||||
---
|
||||
|
||||
## 3 · Tour B — Audit Evidence Export
|
||||
|
||||
**Persona:** Compliance lead compiling artefacts for an external audit.
|
||||
**Goal:** Retrieve signed manifests, export run/finding evidence, and verify parity with Offline Kit.
|
||||
|
||||
### 3.1 Key references
|
||||
- [Downloads workspace](../ui/downloads.md) – manifest, parity, export queue.
|
||||
- [Runs workspace](../ui/runs.md) – evidence panel.
|
||||
- [Console security posture](../security/console-security.md) – evidence handling.
|
||||
- [CLI vs UI parity matrix](../cli-vs-ui-parity.md).
|
||||
|
||||
### 3.2 Live walkthrough
|
||||
1. **Open Downloads:** Use left rail or command palette to reach `/console/downloads`. Point out snapshot banner, cosign verification status.
|
||||
2. **Verify manifest:** Click “Verify signature” quick action; narrate parity with `cosign verify --key <key> manifest.json` from downloads doc §3.
|
||||
3. **Compare Offline Kit:** Switch to “Offline Kits” tab, run parity check to ensure kit digest matches manifest. Demonstrate offline guidance (downloads doc §6).
|
||||
4. **Queue evidence bundle:** Navigate to Runs workspace, choose relevant run, trigger “Bundle for offline” (runs doc §8).
|
||||
5. **Return to Downloads → Exports tab:** Show newly generated evidence bundle with retention countdown.
|
||||
6. **Download & inspect:** Open detail drawer, copy CLI command `stella runs export --run <id> --bundle`. Mention location for storing evidence.
|
||||
7. **Log parity results:** Use notes or tags to flag audit package completion (if notifications configured).
|
||||
8. **CLI parity close-out:** Run `stella downloads manifest --channel stable` to mirror UI manifest retrieval. Confirm digests match.
|
||||
|
||||
### 3.3 Capture checklist
|
||||
- `docs/assets/ui/tours/audit-step-02.png` — manifest verification banner (green).
|
||||
|
||||
- `docs/assets/ui/tours/audit-step-05.png` — exports tab showing evidence bundle ready.
|
||||
|
||||
- `docs/assets/ui/tours/audit-flow.gif` — 25 s capture from manifest view through export download.
|
||||
|
||||
|
||||
### 3.4 Talking points & callouts
|
||||
- Stress deterministic manifests and Cosign signatures; reference deployment doc for TLS/CSP alignment.
|
||||
- Highlight audit trail: downloads actions recorded via `ui.download.commandCopied` logs and Authority audit entries.
|
||||
- Offline note: show guidance when parity check detects stale manifest; mention CLI fallback for sealed networks.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Tour C — Policy Rollout & Promotion
|
||||
|
||||
**Persona:** Policy owner preparing and promoting a new ruleset.
|
||||
**Goal:** Draft review, simulation, approval, and promotion within Console, with CLI parity.
|
||||
|
||||
### 4.1 Key references
|
||||
- [Policies workspace](../ui/policies.md) – simulations, approvals, promotion.
|
||||
- [Policy editor](../ui/policy-editor.md) – Monaco editor, linting.
|
||||
- [Runs workspace](../ui/runs.md) – policy run monitoring.
|
||||
- [Security posture](../security/console-security.md) – fresh-auth and scopes.
|
||||
|
||||
### 4.2 Live walkthrough
|
||||
1. **Policy overview:** Open `/console/policies`, filter by “Staged” state. Highlight list columns (owners, pending approvals).
|
||||
2. **Enter draft:** Select policy → open editor view. Show checklist sidebar (lint, simulation, determinism).
|
||||
3. **Run lint & simulation:** Hit `Run lint`, then `Run simulation`. Narrate asynchronous progress with SSE ticker; reference CLI `stella policy simulate`.
|
||||
4. **Review diff:** Open simulation diff view to compare Active vs Staged; highlight severity up/down badges (§6 of policies doc).
|
||||
5. **Approval workflow:** Assign reviewer, show comment thread. Trigger fresh-auth prompt when clicking “Submit for review” (security doc §1.2).
|
||||
6. **Promote policy:** After approvals, open promotion dialog, choose “Full run”. Emphasise policy run scheduling and RBAC.
|
||||
7. **Monitor run:** Jump to Runs workspace, filter by policy run; show progress segments and findings delta metrics.
|
||||
8. **Publish CLI parity:** Execute `stella policy promote --policy <id> --revision <rev> --run-mode full` to reinforce reproducibility.
|
||||
|
||||
### 4.3 Capture checklist
|
||||
- `docs/assets/ui/tours/policy-step-02.png` — editor checklist with lint/simulation statuses.
|
||||
|
||||
- `docs/assets/ui/tours/policy-step-04.png` — simulation diff comparing Active vs Staged.
|
||||
|
||||
- `docs/assets/ui/tours/policy-flow.gif` — 30 s clip from draft view through promotion confirmation.
|
||||
|
||||
|
||||
### 4.4 Talking points & callouts
|
||||
- Stress governance: approvals logged with correlation IDs, fresh-auth enforced.
|
||||
- Mention telemetry metrics (`ui_tenant_switch_total`, policy run charts) for monitoring adoption.
|
||||
- Offline note: show how promotion dialog surfaces CLI script when in sealed mode; reference offline guidance in policies doc §10.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Production Tips & Media Hygiene
|
||||
|
||||
- **Script timing:** Keep each tour ≤ 3 minutes live demo, ≤ 30 s GIF. Include captions for accessibility.
|
||||
- **Annotations:** Use consistent callouts (numbered badges, short labels) overlayed in post-processing; ensure final media compressed but legible (< 2 MB PNG, < 8 MB GIF). See `docs/assets/ui/tours/README.md` for shared template guidance.
|
||||
- **Versioning:** Annotated assets should include Console build hash in metadata or caption (align with `/console/downloads` manifest version).
|
||||
- **Storage:** Commit final media under `docs/assets/ui/tours/` and update `.gitattributes` if smudge filters required. Note large GIFs may need Git LFS depending on repository policy.
|
||||
- **Review cadence:** Re-run tours whenever workspaces change navigation or introduce new buttons; log updates in `docs/updates/<date>-console-tours.md` (create if absent).
|
||||
|
||||
---
|
||||
|
||||
## 6 · Compliance Checklist
|
||||
|
||||
- [x] Tour scripts cover triage, audit evidence, and policy rollout scenarios requested in DOCS-CONSOLE-23-017.
|
||||
- [x] Each tour references authoritative workspace docs and CLI parity commands.
|
||||
- [x] Capture checklist names align with `docs/assets/ui/tours/` convention.
|
||||
- [x] Offline and sealed-mode notes included for every flow.
|
||||
- [x] Security considerations (scopes, fresh-auth, evidence handling) highlighted.
|
||||
- [x] Observability/telemetry pointers surfaced to support Ops follow-up.
|
||||
- [x] Media hygiene guidance documented (assets, compression, versioning).
|
||||
- [x] Document timestamp reflects Sprint 23 delivery.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 23).*
|
||||
|
||||
Reference in New Issue
Block a user