up
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
This commit is contained in:
master
@@ -1,25 +1,332 @@
|
||||
# stella policy — Command Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The `stella policy` command group provides comprehensive policy management capabilities for Policy Studio, including creation, simulation, workflow management, and lifecycle operations.
|
||||
|
||||
## Commands
|
||||
- `stella policy eval --input <bundle> --subject <sbom|vex|vuln> [--offline] [--output json|ndjson|table]`
|
||||
- `stella policy simulate --from <bundleA> --to <bundleB> [--budget <ms>] [--offline]`
|
||||
- `stella policy publish --input <bundle> --sign --attest`
|
||||
|
||||
## Flags (common)
|
||||
- `--offline` / `STELLA_OFFLINE=1`: forbid network calls; use cached bundles only.
|
||||
- `--tenant <id>`: scope evaluation to tenant; RLS enforcement required on the server.
|
||||
- `--rationale`: include rationale IDs in responses.
|
||||
- `--output`: `json` (default), `ndjson`, or `table`.
|
||||
### Policy Creation & Scaffolding
|
||||
|
||||
## Inputs/outputs
|
||||
- Inputs: policy bundles (signed), subject artifacts (SBOM/VEX/Vuln snapshots).
|
||||
- Outputs: deterministic JSON/NDJSON or tables; includes `correlationId`, `policyVersion`, `rationaleIds` when requested.
|
||||
- Exit codes follow `output-and-exit-codes.md`.
|
||||
```bash
|
||||
# Create a new policy from a template
|
||||
stella policy new <name> [--template <template>] [--output <path>] [--description <desc>] [--tags <tag1,tag2>] [--shadow-mode] [--create-fixtures] [--git-init]
|
||||
```
|
||||
|
||||
## Determinism rules
|
||||
- Sort evaluation results by subject key; timestamps UTC ISO-8601.
|
||||
- No inferred verdicts beyond Policy Engine response.
|
||||
**Templates:** `basic`, `sbom-gate`, `vex-precedence`, `reachability`, `secret-detection`, `license-compliance`, `supply-chain`
|
||||
|
||||
## Offline/air-gap notes
|
||||
- When `--offline`, evaluation must use locally cached bundles and subject artifacts; fail with exit code 5 if network would be needed.
|
||||
- Trust roots loaded from `STELLA_TRUST_ROOTS` when verifying signed bundles.
|
||||
### Policy Simulation (CLI-POLICY-27-003)
|
||||
|
||||
```bash
|
||||
# Simulate policy changes with enhanced options
|
||||
stella policy simulate <policy-id> \
|
||||
[--base <version>] \
|
||||
[--candidate <version>] \
|
||||
[--sbom <id1,id2,...>] \
|
||||
[--env key=value] \
|
||||
[--mode quick|batch] \
|
||||
[--sbom-selector <pattern>] \
|
||||
[--heatmap] \
|
||||
[--manifest-download] \
|
||||
[--reachability-state <id:state>] \
|
||||
[--reachability-score <id:score>] \
|
||||
[--with-exception <exc-id>] \
|
||||
[--without-exception <exc-id>] \
|
||||
[--explain] \
|
||||
[--fail-on-diff] \
|
||||
[--format json|table|markdown] \
|
||||
[--output <path>]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--mode quick\|batch` | Simulation mode: `quick` samples SBOMs, `batch` evaluates all matching |
|
||||
| `--sbom-selector` | SBOM selector pattern (e.g., `registry:docker.io/*`, `tag:production`). Repeatable |
|
||||
| `--heatmap` | Include severity heatmap summary in output |
|
||||
| `--manifest-download` | Request manifest download URI for offline analysis |
|
||||
| `--reachability-state` | Override reachability state (format: `CVE-XXXX:reachable`). Repeatable |
|
||||
| `--reachability-score` | Override reachability score (format: `CVE-XXXX:0.85`). Repeatable |
|
||||
| `--format markdown` | Generate CI-friendly markdown report |
|
||||
|
||||
### Policy Workflow (CLI-POLICY-27-002)
|
||||
|
||||
```bash
|
||||
# Bump policy version
|
||||
stella policy version bump <policy-id> [--changelog <message>] [--major|--minor|--patch]
|
||||
|
||||
# Submit policy for review
|
||||
stella policy submit <policy-id> [--version <ver>] [--reviewers <user1,user2>] [--changelog <message>]
|
||||
|
||||
# Add review comment
|
||||
stella policy review comment <policy-id> [--version <ver>] --comment <text> [--line <num>] [--file <path>]
|
||||
|
||||
# Approve policy review
|
||||
stella policy approve <policy-id> [--version <ver>] [--comment <text>]
|
||||
|
||||
# Reject policy review
|
||||
stella policy reject <policy-id> [--version <ver>] --reason <text>
|
||||
|
||||
# Get review status
|
||||
stella policy review status <policy-id> [--version <ver>]
|
||||
```
|
||||
|
||||
### Policy Lifecycle (CLI-POLICY-27-004)
|
||||
|
||||
```bash
|
||||
# Publish policy
|
||||
stella policy publish <policy-id> [--version <ver>] [--sign] [--attestation-type <type>] [--dry-run]
|
||||
|
||||
# Promote policy to environment
|
||||
stella policy promote <policy-id> [--version <ver>] --env <environment> [--canary <percentage>] [--dry-run]
|
||||
|
||||
# Rollback policy
|
||||
stella policy rollback <policy-id> [--to-version <ver>] [--reason <text>] [--force]
|
||||
|
||||
# Sign policy
|
||||
stella policy sign <policy-id> [--version <ver>] [--key-id <key>] [--attestation-type <type>]
|
||||
|
||||
# Verify policy signature
|
||||
stella policy verify-signature <policy-id> [--version <ver>] [--check-rekor]
|
||||
```
|
||||
|
||||
### Policy History & Explain (CLI-POLICY-23-006)
|
||||
|
||||
```bash
|
||||
# Get policy history
|
||||
stella policy history <policy-id> [--limit <num>] [--since <date>] [--until <date>]
|
||||
|
||||
# Explain policy decision
|
||||
stella policy explain <policy-id> [--version <ver>] [--finding-id <id>] [--verbose]
|
||||
```
|
||||
|
||||
### Policy Activation
|
||||
|
||||
```bash
|
||||
# Activate an approved policy revision
|
||||
stella policy activate <policy-id> --version <ver> [--environment <env>] [--force] [--dry-run]
|
||||
```
|
||||
|
||||
## Common Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--tenant` / `-t` | Tenant context for the operation |
|
||||
| `--json` | Output as JSON |
|
||||
| `--verbose` / `-v` | Enable verbose logging |
|
||||
| `--offline` | Forbid network calls; use cached bundles only |
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Success |
|
||||
| 1 | General error |
|
||||
| 4 | Input validation error |
|
||||
| 5 | Network required but offline mode enabled |
|
||||
| 20 | Differences detected with `--fail-on-diff` |
|
||||
| 130 | Operation cancelled by user |
|
||||
|
||||
## JSON Schemas
|
||||
|
||||
### PolicySimulationResult
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"diff": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"schemaVersion": { "type": "string" },
|
||||
"added": { "type": "integer" },
|
||||
"removed": { "type": "integer" },
|
||||
"unchanged": { "type": "integer" },
|
||||
"bySeverity": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"up": { "type": "integer" },
|
||||
"down": { "type": "integer" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"ruleHits": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"ruleId": { "type": "string" },
|
||||
"ruleName": { "type": "string" },
|
||||
"up": { "type": "integer" },
|
||||
"down": { "type": "integer" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"explainUri": { "type": "string" },
|
||||
"heatmap": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"buckets": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"severity": { "type": "string" },
|
||||
"count": { "type": "integer" },
|
||||
"percentage": { "type": "number" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"total": { "type": "integer" }
|
||||
}
|
||||
},
|
||||
"manifestDownloadUri": { "type": "string" },
|
||||
"manifestDigest": { "type": "string" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PolicyReviewSummary
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"policyId": { "type": "string" },
|
||||
"version": { "type": "integer" },
|
||||
"status": { "type": "string", "enum": ["pending", "approved", "rejected", "changes_requested"] },
|
||||
"submittedBy": { "type": "string" },
|
||||
"submittedAt": { "type": "string", "format": "date-time" },
|
||||
"reviewers": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"userId": { "type": "string" },
|
||||
"status": { "type": "string" },
|
||||
"reviewedAt": { "type": "string", "format": "date-time" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"comments": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"commentId": { "type": "string" },
|
||||
"author": { "type": "string" },
|
||||
"text": { "type": "string" },
|
||||
"createdAt": { "type": "string", "format": "date-time" },
|
||||
"line": { "type": "integer" },
|
||||
"file": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CI/CD Integration Examples
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Policy Simulation
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'policies/**'
|
||||
|
||||
jobs:
|
||||
simulate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Stella CLI
|
||||
run: |
|
||||
curl -sSL https://get.stellaops.io | bash
|
||||
|
||||
- name: Simulate Policy Changes
|
||||
run: |
|
||||
stella policy simulate P-7 \
|
||||
--base $(git merge-base HEAD origin/main) \
|
||||
--candidate HEAD \
|
||||
--mode batch \
|
||||
--heatmap \
|
||||
--format markdown \
|
||||
--output simulation-report.md \
|
||||
--fail-on-diff
|
||||
|
||||
- name: Upload Report
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: policy-simulation-report
|
||||
path: simulation-report.md
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
policy-simulate:
|
||||
stage: test
|
||||
script:
|
||||
- stella policy simulate P-7 --mode quick --heatmap --json > simulation.json
|
||||
- |
|
||||
if [ $(jq '.diff.added + .diff.removed' simulation.json) -gt 0 ]; then
|
||||
echo "Policy changes detected"
|
||||
stella policy simulate P-7 --format markdown --output report.md
|
||||
exit 20
|
||||
fi
|
||||
artifacts:
|
||||
paths:
|
||||
- simulation.json
|
||||
- report.md
|
||||
when: always
|
||||
```
|
||||
|
||||
### Azure DevOps
|
||||
|
||||
```yaml
|
||||
- task: Bash@3
|
||||
displayName: 'Policy Simulation'
|
||||
inputs:
|
||||
targetType: 'inline'
|
||||
script: |
|
||||
stella policy simulate P-7 \
|
||||
--mode batch \
|
||||
--sbom-selector "registry:$(ACR_REGISTRY)/*" \
|
||||
--heatmap \
|
||||
--json \
|
||||
--output $(Build.ArtifactStagingDirectory)/simulation.json
|
||||
```
|
||||
|
||||
## Determinism Rules
|
||||
|
||||
- Sort evaluation results by subject key
|
||||
- Timestamps use UTC ISO-8601 format
|
||||
- No inferred verdicts beyond Policy Engine response
|
||||
- Hashes computed with SHA-256
|
||||
|
||||
## Offline/Air-Gap Notes
|
||||
|
||||
- When `--offline` is set, evaluation uses locally cached bundles and subject artifacts
|
||||
- Fails with exit code 5 if network would be needed
|
||||
- Trust roots loaded from `STELLA_TRUST_ROOTS` environment variable when verifying signed bundles
|
||||
- Signature verification can use local Rekor mirror via `STELLA_REKOR_MIRROR`
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `STELLAOPS_BACKEND_URL` | Backend API URL |
|
||||
| `STELLA_OFFLINE` | Set to `1` to enable offline mode |
|
||||
| `STELLA_TRUST_ROOTS` | Path to trust roots for signature verification |
|
||||
| `STELLA_REKOR_MIRROR` | Local Rekor transparency log mirror URL |
|
||||
| `STELLAOPS_TENANT` | Default tenant context |
|
||||
|
||||
Reference in New Issue
Block a user