stella policy — Command Guide

Overview

The stella policy command group manages the full Policy Studio lifecycle from the command line: scaffolding new policies, simulating changes against SBOMs, running the review and approval workflow, and publishing, promoting, signing, and verifying policy revisions.

Audience: policy authors, security engineers, and CI authors who gate releases on policy outcomes.

Outputs are deterministic and offline-friendly — see Determinism Rules and Offline/Air-Gap Notes.

Commands

Policy Creation & Scaffolding

# 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]

Templates: basic, sbom-gate, vex-precedence, reachability, secret-detection, license-compliance, supply-chain

Policy Simulation

# 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:

Policy Workflow

# 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

# Publish policy
stella policy publish <policy-id> [--version <ver>] [--sign] [--attestation-type <type>] [--dry-run]

# Promote policy to environment
stella policy promote <policy-id> --from <env> --to <env> [--dry-run] [--format json|table] [--output <path>]

# 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

# 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 Lattice Explain

# Explain policy lattice structure
stella policy lattice explain [--format json|mermaid] [--output <path>]

Policy Verdicts Export

# Export policy verdict history
stella policy verdicts export \
  [--from <timestamp>] \
  [--to <timestamp>] \
  [--policy <id>] \
  [--outcome pass|fail|warn] \
  [--format json|csv] \
  [--output <path>]

Policy Activation

# Activate an approved policy revision
stella policy activate <policy-id> --version <ver> [--environment <env>] [--force] [--dry-run]

Common Flags

Exit Codes

JSON Schemas

PolicySimulationResult

{
  "$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

{
  "$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

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

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

- 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

See also

• stella reachability— generate the reachability signals consumed by --reachability-state / --reachability-score.
• stella risk— risk profiles and scoring that complement policy gates.
• Output and exit codes — canonical CLI exit-code reference.