new advisories work and features gaps work
This commit is contained in:
master
@@ -219,6 +219,100 @@ stellaops scan image:tag --output-format sarif --tier executed,tainted_sink
|
||||
stellaops smart-diff --output-format sarif --min-priority 0.7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## StellaOps Property Keys
|
||||
|
||||
> **Sprint:** SPRINT_20260112_008_DOCS_path_witness_contracts (PW-DOC-003)
|
||||
|
||||
SARIF `properties` bag extensions for StellaOps-specific metadata.
|
||||
|
||||
### Result-Level Properties
|
||||
|
||||
| Property Key | Type | Description |
|
||||
|--------------|------|-------------|
|
||||
| `stellaops/nodeHash` | string | Canonical node hash (`sha256:<hex>`) for static/runtime joining |
|
||||
| `stellaops/pathHash` | string | Canonical path hash for full reachability path |
|
||||
| `stellaops/topKNodeHashes` | array | Top-K node hashes for efficient lookup |
|
||||
| `stellaops/evidenceUri` | string | `cas://<hash>` URI to evidence bundle |
|
||||
| `stellaops/attestationUri` | string | `cas://<hash>` URI to DSSE envelope |
|
||||
| `stellaops/rekorUri` | string | Rekor transparency log entry URL |
|
||||
| `stellaops/witnessId` | string | Path witness identifier |
|
||||
| `stellaops/witnessHash` | string | BLAKE3 hash of witness payload |
|
||||
|
||||
### Run-Level Properties
|
||||
|
||||
| Property Key | Type | Description |
|
||||
|--------------|------|-------------|
|
||||
| `stellaops/scanId` | string | UUID of the scan |
|
||||
| `stellaops/graphHash` | string | BLAKE3 hash of the rich graph |
|
||||
| `stellaops/sbomDigest` | string | SHA256 digest of source SBOM |
|
||||
| `stellaops/feedSnapshot` | string | ISO8601 timestamp of feed data |
|
||||
|
||||
### Example with StellaOps Properties
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"ruleId": "SDIFF001",
|
||||
"level": "warning",
|
||||
"message": {
|
||||
"text": "CVE-2024-1234 became reachable via 3-hop path"
|
||||
},
|
||||
"locations": [
|
||||
{
|
||||
"logicalLocations": [
|
||||
{
|
||||
"name": "pkg:npm/lodash@4.17.20",
|
||||
"kind": "package"
|
||||
},
|
||||
{
|
||||
"name": "lodash.merge(object, object)",
|
||||
"kind": "function"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"properties": {
|
||||
"vulnerability": "CVE-2024-1234",
|
||||
"tier": "executed",
|
||||
"direction": "increased",
|
||||
"stellaops/nodeHash": "sha256:a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
|
||||
"stellaops/pathHash": "sha256:fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
|
||||
"stellaops/topKNodeHashes": [
|
||||
"sha256:entry1111111111111111111111111111111111111111111111111111111111",
|
||||
"sha256:sink22222222222222222222222222222222222222222222222222222222222"
|
||||
],
|
||||
"stellaops/evidenceUri": "cas://sha256:evidence123...",
|
||||
"stellaops/attestationUri": "cas://sha256:dsse456...",
|
||||
"stellaops/rekorUri": "https://rekor.sigstore.dev/api/v1/log/entries/abc123",
|
||||
"stellaops/witnessId": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Joining Static and Runtime Evidence
|
||||
|
||||
Use `stellaops/nodeHash` to correlate:
|
||||
|
||||
1. **Static analysis** findings (SARIF from Scanner)
|
||||
2. **Runtime telemetry** (execution traces from agents)
|
||||
3. **Policy decisions** (gating results)
|
||||
|
||||
```bash
|
||||
# Query findings by node hash
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://scanner.example.com/api/v1/findings?nodeHash=sha256:a1b2c3..."
|
||||
|
||||
# Verify path witness by hash
|
||||
stellaops witness verify --path-hash sha256:fedcba...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### SARIF Validation Errors
|
||||
|
||||
143
docs/technical/reviews/cli-command-name-sweep-2026-01-14.md
Normal file
143
docs/technical/reviews/cli-command-name-sweep-2026-01-14.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# CLI Command Name Sweep Report
|
||||
|
||||
**Date:** 2026-01-14
|
||||
**Sprint:** SPRINT_20260112_010_DOCS_cli_command_name_sweep
|
||||
**Owner:** Docs Guild
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This report inventories all CLI command references in documentation to confirm the canonical command name (`stella`) and identify legacy references (`stellaops`) for cleanup or alias documentation.
|
||||
|
||||
| Command Pattern | Count | Status |
|
||||
|-----------------|-------|--------|
|
||||
| `stella <command>` | 984 | Canonical - no action |
|
||||
| `stellaops <command>` | 140 | Legacy - review needed |
|
||||
|
||||
---
|
||||
|
||||
## Classification Summary
|
||||
|
||||
### Category 1: Replace (CLI Commands)
|
||||
|
||||
These are direct CLI command invocations using `stellaops` that should be updated to `stella`:
|
||||
|
||||
| File Path | Line | Context | Recommendation |
|
||||
|-----------|------|---------|----------------|
|
||||
| docs/benchmarks/performance-baselines.md | 191-239 | Benchmark commands | Replace with `stella` |
|
||||
| docs/benchmarks/smart-diff-wii.md | 141 | Verify attestation example | Replace with `stella` |
|
||||
| docs/benchmarks/submission-guide.md | 144-147 | Submission examples | Replace with `stella` |
|
||||
|
||||
**Estimated count:** ~25 references in benchmark docs.
|
||||
|
||||
### Category 2: Keep (Namespaces/Headers)
|
||||
|
||||
These are valid namespace, assembly, or header references that should remain as-is:
|
||||
|
||||
| Pattern | Context | Recommendation |
|
||||
|---------|---------|----------------|
|
||||
| `StellaOps.*` namespace | Code namespaces in docs | Keep - matches source code |
|
||||
| `X-StellaOps-*` headers | API authentication headers | Keep - canonical header prefix |
|
||||
| `stellaops:tenant` claim | JWT claim names | Keep - canonical claim name |
|
||||
| `stellaops.console.*` | Payload/event types | Keep - canonical type prefixes |
|
||||
|
||||
**Estimated count:** ~100+ references.
|
||||
|
||||
### Category 3: Ambiguous (Requires CLI Guild Input)
|
||||
|
||||
| Pattern | Context | Question |
|
||||
|---------|---------|----------|
|
||||
| URLs with `stellaops` | gateway.stellaops.local | Is this the canonical domain? |
|
||||
| Product name references | "StellaOps Scanner" | Product name vs CLI command |
|
||||
|
||||
---
|
||||
|
||||
## File-by-File Inventory (CLI Commands Only)
|
||||
|
||||
### docs/benchmarks/performance-baselines.md
|
||||
|
||||
```
|
||||
Line 191: time stellaops scan --image example:latest
|
||||
Line 195: time stellaops scan --image example:latest --format json
|
||||
Line 199: /usr/bin/time -v stellaops scan ...
|
||||
Line 203: perf stat stellaops scan ...
|
||||
Line 223: time stellaops sbom --image ...
|
||||
Line 226: stellaops sbom --image ...
|
||||
Line 234: time stellaops scan --image ...
|
||||
Line 239: stellaops scan --image ...
|
||||
```
|
||||
|
||||
**Action:** Replace `stellaops` with `stella` in all commands.
|
||||
|
||||
### docs/benchmarks/smart-diff-wii.md
|
||||
|
||||
```
|
||||
Line 141: stellaops verify-attestation ...
|
||||
```
|
||||
|
||||
**Action:** Replace with `stella verify-attestation`.
|
||||
|
||||
### docs/benchmarks/submission-guide.md
|
||||
|
||||
```
|
||||
Line 144: 'stellaops scan --image ...'
|
||||
Line 147: /usr/bin/time -v stellaops ...
|
||||
```
|
||||
|
||||
**Action:** Replace with `stella`.
|
||||
|
||||
---
|
||||
|
||||
## Legacy Alias Policy Recommendation
|
||||
|
||||
If `stellaops` is supported as a shell alias for `stella`:
|
||||
|
||||
1. Document the alias in CLI reference: `docs/modules/cli/guides/commands/aliases.md`
|
||||
2. Add a note in examples that `stellaops` is a legacy alias
|
||||
3. Prefer `stella` in all new documentation
|
||||
|
||||
If `stellaops` is NOT supported:
|
||||
|
||||
1. Replace all CLI command references with `stella`
|
||||
2. Update CI examples and scripts
|
||||
|
||||
---
|
||||
|
||||
## Follow-Up Tasks
|
||||
|
||||
| Task ID | Description | Owner | Priority |
|
||||
|---------|-------------|-------|----------|
|
||||
| CLISWEEP-REPLACE-001 | Replace `stellaops` CLI commands in benchmark docs | Docs Guild | P2 |
|
||||
| CLISWEEP-ALIAS-002 | Confirm alias policy with CLI Guild | CLI Guild | P1 |
|
||||
| CLISWEEP-DOC-003 | Document alias behavior if supported | Docs Guild | P2 |
|
||||
| CLISWEEP-VERIFY-004 | Verify no broken examples after replacement | QA Guild | P3 |
|
||||
|
||||
---
|
||||
|
||||
## Methodology
|
||||
|
||||
1. Searched `docs/**/*.md` for pattern `stellaops\s+<command>` where command is a known CLI verb
|
||||
2. Excluded namespace/header/claim references (matched by `StellaOps.*`, `X-StellaOps-*`, `stellaops:*`)
|
||||
3. Counted canonical `stella <command>` references for comparison
|
||||
4. Classified each reference by context and owner
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Search Commands Used
|
||||
|
||||
```powershell
|
||||
# Count stellaops CLI commands
|
||||
Get-ChildItem -Recurse -Path docs -Include *.md |
|
||||
Select-String -Pattern "stellaops\s+(scan|export|verify|...)"
|
||||
|
||||
# Count stella CLI commands (canonical)
|
||||
Get-ChildItem -Recurse -Path docs -Include *.md |
|
||||
Select-String -Pattern "stella\s+(scan|export|verify|...)" |
|
||||
Where-Object { $_.Line -notmatch "stellaops" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Report Status:** Complete
|
||||
**Next Review:** After CLI Guild alias policy confirmation
|
||||
Reference in New Issue
Block a user