synergy moats product advisory implementations
This commit is contained in:
master
313
docs/modules/cli/guides/commands/explain.md
Normal file
313
docs/modules/cli/guides/commands/explain.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# 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:**
|
||||
```bash
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```markdown
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Get complete explanation with all details
|
||||
stella explain block sha256:abc123... \
|
||||
--show-evidence \
|
||||
--show-trace \
|
||||
--replay-token \
|
||||
--format table
|
||||
```
|
||||
|
||||
### Markdown for PR Comment
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
|
||||
1. **Same inputs produce identical outputs** - Given the same artifact digest and policy version, the output is byte-for-byte identical
|
||||
2. **Evidence is sorted** - Evidence artifacts are sorted by timestamp (ascending)
|
||||
3. **Trace is sorted** - Evaluation trace steps are sorted by step number
|
||||
4. **Timestamps use ISO 8601** - All timestamps use ISO 8601 format with UTC offset
|
||||
5. **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:**
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
```bash
|
||||
# Check connectivity
|
||||
stella doctor --check check.policy.connectivity
|
||||
|
||||
# Use offline mode if available
|
||||
stella explain block sha256:abc123... --offline
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Policy Commands](policy.md) - Policy management and testing
|
||||
- [VEX Commands](vex.md) - VEX document management
|
||||
- [Evidence Commands](evidence.md) - Evidence retrieval and verification
|
||||
- [Verify Commands](verify.md) - Verdict verification and replay
|
||||
- [Command Reference](reference.md) - Complete command reference
|
||||
Reference in New Issue
Block a user