stella-ops.org/git.stella-ops.org

Fork 0

Files

master 702a27ac83 synergy moats product advisory implementations

2026-01-17 01:32:20 +02:00

8.4 KiB

Raw Permalink Blame History

stella explain - Block Explanation Commands

Sprint: SPRINT_20260117_026_CLI_why_blocked_command

Overview

The stella explain command group provides commands for understanding why artifacts are blocked by policy gates. This addresses the M2 moat requirement: "Explainability with proof, not narrative."

When an artifact is blocked, stella explain produces a deterministic trace with referenced evidence artifacts, enabling:

Clear understanding of which gate blocked the artifact
Actionable suggestions for remediation
Verifiable evidence chain
Deterministic replay for verification

Commands

stella explain block

Explain why an artifact was blocked by policy gates.

Usage:

stella explain block <digest> [options]

Arguments:

<digest> - Artifact digest in any of these formats:
- sha256:abc123... - Full digest with algorithm prefix
- abc123... - Raw 64-character hex digest (assumed sha256)
- registry.example.com/image@sha256:abc123... - OCI reference (digest extracted)

Options:

Option	Alias	Description	Default
`--format <format>`	`-f`	Output format: `table`, `json`, `markdown`	`table`
`--show-evidence`	`-e`	Include full evidence artifact details	false
`--show-trace`	`-t`	Include policy evaluation trace	false
`--replay-token`	`-r`	Include replay token in output	false
`--output <path>`	`-o`	Write to file instead of stdout	stdout
`--offline`		Query local verdict cache only	false

Output Formats

Table Format (Default)

Human-readable format optimized for terminal display:

Artifact: sha256:abc123def456789012345678901234567890123456789012345678901234
Status: BLOCKED

Gate: VexTrust
Reason: Trust score below threshold (0.45 < 0.70)
Suggestion: Obtain VEX statement from trusted issuer or add issuer to trust registry

Evidence:
  [VEX   ] vex:sha256:de...23  vendor-x      2026-01-15T10:00:00Z
  [REACH ] reach:sha256...56   static        2026-01-15T09:55:00Z

Replay: stella verify verdict --verdict urn:stella:verdict:sha256:abc123:v2.3.0:1737108000

JSON Format

Machine-readable format for CI/CD integration:

{
  "artifact": "sha256:abc123def456789012345678901234567890123456789012345678901234",
  "status": "BLOCKED",
  "gate": "VexTrust",
  "reason": "Trust score below threshold (0.45 < 0.70)",
  "suggestion": "Obtain VEX statement from trusted issuer or add issuer to trust registry",
  "evaluationTime": "2026-01-15T10:30:00+00:00",
  "policyVersion": "v2.3.0",
  "evidence": [
    {
      "type": "VEX",
      "id": "vex:sha256:def456789abc123",
      "source": "vendor-x",
      "timestamp": "2026-01-15T10:00:00+00:00",
      "retrieveCommand": "stella evidence get vex:sha256:def456789abc123"
    },
    {
      "type": "REACH",
      "id": "reach:sha256:789abc123def456",
      "source": "static-analysis",
      "timestamp": "2026-01-15T09:55:00+00:00",
      "retrieveCommand": "stella evidence get reach:sha256:789abc123def456"
    }
  ],
  "replayCommand": "stella verify verdict --verdict urn:stella:verdict:sha256:abc123:v2.3.0:1737108000"
}

Markdown Format

Suitable for embedding in GitHub issues, PR comments, or documentation:

## Block Explanation

**Artifact:** `sha256:abc123def456789012345678901234567890123456789012345678901234`
**Status:** BLOCKED

### Gate Decision

| Property | Value |
|----------|-------|
| Gate | VexTrust |
| Reason | Trust score below threshold (0.45 < 0.70) |
| Suggestion | Obtain VEX statement from trusted issuer or add issuer to trust registry |
| Policy Version | v2.3.0 |

### Evidence

| Type | ID | Source | Timestamp |
|------|-----|--------|-----------|
| VEX | `vex:sha256:de...23` | vendor-x | 2026-01-15 10:00 |
| REACH | `reach:sha256...56` | static-analysis | 2026-01-15 09:55 |

### Verification

```bash
stella verify verdict --verdict urn:stella:verdict:sha256:abc123:v2.3.0:1737108000


---

## Examples

### Basic Block Explanation

```bash
# Get basic explanation of why an artifact is blocked
stella explain block sha256:abc123def456789012345678901234567890123456789012345678901234

JSON Output for CI/CD

# Get JSON output for parsing in CI/CD pipeline
stella explain block sha256:abc123... --format json --output block-reason.json

# Parse in CI/CD
GATE=$(jq -r '.gate' block-reason.json)
REASON=$(jq -r '.reason' block-reason.json)
echo "Blocked by $GATE: $REASON"

Full Explanation with Evidence and Trace

# Get complete explanation with all details
stella explain block sha256:abc123... \
  --show-evidence \
  --show-trace \
  --replay-token \
  --format table

Markdown for PR Comment

# Generate markdown for GitHub PR comment
stella explain block sha256:abc123... --format markdown --output comment.md

# Use with gh CLI
gh pr comment 123 --body-file comment.md

Retrieve Evidence Artifacts

# Get explanation
stella explain block sha256:abc123... --show-evidence

# Retrieve specific evidence artifacts
stella evidence get vex:sha256:def456789abc123
stella evidence get reach:sha256:789abc123def456

Verify Deterministic Replay

# Get replay token
REPLAY=$(stella explain block sha256:abc123... --format json | jq -r '.replayCommand')

# Execute replay verification
eval $REPLAY

Exit Codes

Code	Meaning
`0`	Artifact is NOT blocked (all gates passed)
`1`	Artifact IS blocked (one or more gates failed)
`2`	Error (artifact not found, API error, etc.)

CI/CD Integration:

# Fail pipeline if artifact is blocked
if ! stella explain block sha256:abc123... --format json > /dev/null 2>&1; then
  EXIT_CODE=$?
  if [ $EXIT_CODE -eq 1 ]; then
    echo "ERROR: Artifact is blocked by policy"
    stella explain block sha256:abc123... --format markdown
    exit 1
  else
    echo "ERROR: Could not retrieve block status"
    exit 2
  fi
fi

Evidence Types

The explain block command returns evidence artifacts that contributed to the gate decision:

Type	Description	Source
`VEX`	VEX (Vulnerability Exploitability eXchange) statement	VEX issuers, vendor security teams
`REACH`	Reachability analysis result	Static analysis, call graph analysis
`SBOM`	Software Bill of Materials	SBOM generators, build systems
`SCAN`	Vulnerability scan result	Scanner service
`ATTEST`	Attestation document	Attestor service, SLSA provenance
`POLICY`	Policy evaluation result	Policy engine

Determinism Guarantee

All output from stella explain block is deterministic:

Same inputs produce identical outputs - Given the same artifact digest and policy version, the output is byte-for-byte identical
Evidence is sorted - Evidence artifacts are sorted by timestamp (ascending)
Trace is sorted - Evaluation trace steps are sorted by step number
Timestamps use ISO 8601 - All timestamps use ISO 8601 format with UTC offset
JSON uses canonical ordering - JSON properties are ordered consistently

This enables:

Replay verification - Use the replay token to verify the decision can be reproduced
Audit trails - Compare explanations across time
Cache validation - Verify cached decisions match current evaluation

Troubleshooting

Artifact Not Found

Error: Artifact sha256:abc123... not found in registry or evidence store.

Causes:

Artifact was never scanned
Artifact digest is incorrect
Artifact was deleted from registry

Solutions:

# Verify artifact exists
stella image inspect sha256:abc123...

# Scan the artifact
stella scan docker://myregistry/myimage@sha256:abc123...

Not Blocked

Artifact sha256:abc123... is NOT blocked. All policy gates passed.

This means the artifact passed all policy evaluations. Exit code will be 0.

API Error

Error: Policy service unavailable