git.stella-ops.org/docs/modules/cli/guides/commands/policy.md

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

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 (CLI-POLICY-27-003)

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

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

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

# 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

# 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

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

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