stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

consolidation of some of the modules, localization fixes, product advisories work, qa work

Browse Source
This commit is contained in:
master
2026-03-05 03:54:22 +02:00
parent 7bafcc3eef
commit 8e1cb9448d
3878 changed files with 72600 additions and 46861 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs-archived/modules/vuln-explorer/guides/explorer-overview.md Normal file
View File

@@ -0,0 +1,25 @@
# Vulnerability Explorer Overview (Detailed)
The Vulnerability Explorer is the evidence-linked triage surface that brings together SBOM facts, advisory/VEX evidence, reachability signals, policy explainability, and operator decisions into a single auditable workflow.
This document complements the high-level guide `docs/VULNERABILITY_EXPLORER_GUIDE.md` with additional detail and cross-links.
## Core Objects
- **Finding record:** the current enriched view of a vulnerability for a specific artifact/context (tenant, artifact/image digest, policy version).
- **History:** append-only state transitions suitable for audit and replay.
- **Triage actions:** operator actions (assignment, comment, mitigation note, exception request) with provenance.
- **Evidence references:** stable pointers to evidence objects (SBOM slices, VEX observations/linksets, reachability proofs, explain traces, attestations).
## Key Properties
- **Narrative-first:** default view answers “Can I ship? If not, why? What’s the smallest safe change?”
- **Proof-linked:** every important fact links to evidence (no “trust the UI”).
- **Quiet by default, never silent:** suppression/muting is reversible and auditable.
- **Offline-ready:** evidence bundles are verifiable without online lookups.
## References
- High-level guide: `docs/VULNERABILITY_EXPLORER_GUIDE.md`
- Console operator guide: `docs/UI_GUIDE.md`
- Module dossier: `docs/modules/vuln-explorer/architecture.md`

32
docs-archived/modules/vuln-explorer/guides/explorer-using-console.md Normal file
View File

@@ -0,0 +1,32 @@
# Vulnerability Explorer Using the Console
This document describes the operator workflow for triaging findings in the Console. It is intentionally evidence-first and audit-oriented.
## Workflow (Typical)
1. Start from the findings list filtered to the tenant/environment you care about.
2. Open a finding to review:
- Verdict and “why” summary
- Effective VEX status and issuer provenance
- Reachability/impact signals (when available)
- Policy gate and explain trace
3. Record a triage action (assign/comment/mitigation/exception) with justification.
4. Export an evidence bundle when review, escalation, or offline verification is required.
## What to Expect in a Finding View
- Clear tenant context and artifact identifiers
- Evidence rail (SBOM, VEX, advisories, reachability, attestations)
- History/timeline of state changes and actions (append-only)
- Copyable identifiers (finding ID, digests, correlation IDs)
## Offline / Air-Gap Notes
- When operating from Offline Kit snapshots, the Console should surface snapshot identity and staleness budgets.
- Evidence bundle export is the primary bridge between online and offline review.
## References
- Console operator guide: `docs/UI_GUIDE.md`
- Vulnerability Explorer guide: `docs/VULNERABILITY_EXPLORER_GUIDE.md`
- Offline Kit: `docs/OFFLINE_KIT.md`

22
docs-archived/modules/vuln-explorer/guides/findings-ledger.md Normal file
View File

@@ -0,0 +1,22 @@
# Findings Ledger and Replay (Vulnerability Explorer)
The Findings Ledger is the append-only backbone for auditable triage. It records current finding state, history transitions, and operator actions in a way that supports deterministic replay and offline verification.
This document provides a conceptual overview; the authoritative schema and hashing rules are in the Findings Ledger module docs.
## What the Ledger Stores
- **Finding records:** enriched, policy-derived findings (with references to advisories/VEX/SBOM/reachability and explain traces).
- **History:** append-only state transitions with actor identity, justification, and timestamps (UTC).
- **Triage actions:** discrete operator actions (comment, assignment, mitigation note, ticket link) with immutable provenance.
## Replay and Verification
- Replay reconstructs derived state from append-only history/actions and compares deterministic digests.
- Offline bundles include the ledger exports plus integrity metadata so auditors can verify without trusting a live service.
## References
- Findings Ledger schema: `docs/modules/findings-ledger/schema.md`
- Merkle anchoring policy: `docs/modules/findings-ledger/merkle-anchor-policy.md`
- Vulnerability Explorer dossier: `docs/modules/vuln-explorer/architecture.md`

247
docs-archived/modules/vuln-explorer/guides/signed-vex-override-workflow.md Normal file
View File

@@ -0,0 +1,247 @@
# Signed VEX Override Workflow
This guide describes how to create and manage signed VEX override decisions using DSSE attestations for audit-grade provenance.
## Overview
VEX (Vulnerability Exploitability eXchange) decisions allow operators to mark vulnerabilities as not-affected, mitigated, or accepted-risk. When attestation signing is enabled, each override produces a DSSE envelope that:
1. Cryptographically binds the decision to the operator's identity
2. Records the decision in an immutable attestation log
3. Optionally anchors the attestation to Sigstore Rekor for transparency
4. Enables downstream policy engines to require signed overrides
## API Endpoints
### Create Signed Override
```http
POST /v1/vex-decisions
Content-Type: application/json
Authorization: Bearer <token>
{
"findingId": "find-abc123",
"status": "NOT_AFFECTED",
"justification": "CODE_NOT_REACHABLE",
"justificationText": "Static analysis confirms code path is unreachable in production configuration",
"scope": {
"environments": ["production"],
"projects": ["myapp"]
},
"validity": {
"notBefore": "2026-01-15T00:00:00Z",
"notAfter": "2026-07-15T00:00:00Z"
},
"attestationOptions": {
"sign": true,
"keyRef": "default-signing-key",
"rekorUpload": true,
"predicateType": "https://stella.ops/predicates/vex-override/v1"
}
}
```
### Response with Attestation Reference
```json
{
"id": "vex-dec-xyz789",
"findingId": "find-abc123",
"status": "NOT_AFFECTED",
"justification": "CODE_NOT_REACHABLE",
"justificationText": "Static analysis confirms code path is unreachable in production configuration",
"createdAt": "2026-01-15T10:30:00Z",
"createdBy": "user@example.com",
"signedOverride": {
"envelopeDigest": "sha256:abc123def456...",
"signatureAlgorithm": "ECDSA_P256_SHA256",
"signedAt": "2026-01-15T10:30:01Z",
"keyId": "default-signing-key",
"rekorInfo": {
"logIndex": 123456789,
"entryId": "24296fb24b8ad77a...",
"integratedTime": "2026-01-15T10:30:02Z",
"logId": "c0d23d6ad406973f..."
},
"verificationStatus": "VERIFIED"
}
}
```
### Update Signed Override
Updates create superseding records while preserving history:
```http
PATCH /v1/vex-decisions/{id}
Content-Type: application/json
Authorization: Bearer <token>
{
"status": "AFFECTED_MITIGATED",
"justification": "COMPENSATING_CONTROLS",
"justificationText": "WAF rule deployed to block exploit vectors",
"attestationOptions": {
"sign": true,
"supersedes": "vex-dec-xyz789"
}
}
```
### List Decisions with Attestation Filter
```http
GET /v1/vex-decisions?signedOnly=true&rekorAnchored=true
```
### Verify Attestation
```http
POST /v1/vex-decisions/{id}/verify
```
Response:
```json
{
"verified": true,
"signatureValid": true,
"rekorEntryValid": true,
"certificateChain": ["CN=signing-key,..."],
"verifiedAt": "2026-01-15T10:35:00Z"
}
```
## CLI Usage
### Create Signed Override
```bash
stella vex create \
--finding find-abc123 \
--status NOT_AFFECTED \
--justification CODE_NOT_REACHABLE \
--reason "Static analysis confirms unreachable" \
--sign \
--key default-signing-key \
--rekor
```
### View Override with Attestation
```bash
stella vex show vex-dec-xyz789 --include-attestation
```
Output:
```
VEX Decision: vex-dec-xyz789
Finding: find-abc123
Status: NOT_AFFECTED
Justification: CODE_NOT_REACHABLE
Created: 2026-01-15T10:30:00Z
Created By: user@example.com
Attestation:
Envelope Digest: sha256:abc123def456...
Algorithm: ECDSA_P256_SHA256
Signed At: 2026-01-15T10:30:01Z
Verification: VERIFIED
Rekor Entry:
Log Index: 123456789
Entry ID: 24296fb24b8ad77a...
Integrated Time: 2026-01-15T10:30:02Z
```
### Verify Override Attestation
```bash
stella vex verify vex-dec-xyz789
```
### Export Override Evidence
```bash
stella vex export vex-dec-xyz789 \
--format bundle \
--output override-evidence.zip
```
## Policy Engine Integration
Signed overrides can be required by policy rules:
```yaml
# Policy requiring signed VEX overrides
rules:
- id: require-signed-vex
condition: |
vex.status in ["NOT_AFFECTED", "AFFECTED_MITIGATED"]
and (vex.signedOverride == null or vex.signedOverride.verificationStatus != "VERIFIED")
action: FAIL
message: "VEX overrides must be signed and verified"
```
## Attestation Predicate Schema
The VEX override predicate follows in-toto attestation format:
```json
{
"_type": "https://in-toto.io/Statement/v1",
"subject": [
{
"name": "finding:find-abc123",
"digest": { "sha256": "..." }
}
],
"predicateType": "https://stella.ops/predicates/vex-override/v1",
"predicate": {
"decision": {
"id": "vex-dec-xyz789",
"status": "NOT_AFFECTED",
"justification": "CODE_NOT_REACHABLE",
"justificationText": "...",
"scope": { "environments": ["production"] },
"validity": { "notBefore": "...", "notAfter": "..." }
},
"finding": {
"id": "find-abc123",
"cve": "CVE-2026-1234",
"package": "example-pkg",
"version": "1.2.3"
},
"operator": {
"identity": "user@example.com",
"authorizedAt": "2026-01-15T10:30:00Z"
},
"supersedes": null
}
}
```
## Security Considerations
1. **Key Management**: Signing keys should be managed through Authority with appropriate access controls
2. **Rekor Anchoring**: Enable Rekor upload for public transparency; disable for air-gapped deployments
3. **Expiry**: Set appropriate validity windows; expired overrides surface warnings
4. **Audit Trail**: All signed overrides are recorded in the findings ledger history
## Offline/Air-Gap Mode
For air-gapped deployments:
1. Rekor upload is disabled automatically
2. Attestations are stored locally with envelope digests
3. Verification uses local trust roots
4. Export bundles include all attestation evidence for manual verification
## Related Documentation
- [VEX Consensus Guide](../../../VEX_CONSENSUS_GUIDE.md)
- [Attestor Architecture](../../attestor/architecture.md)
- [Findings Ledger](./findings-ledger.md)
- [Policy Integration](../../policy/guides/vex-trust-model.md)