new advisories work and features gaps work

2026-01-14 18:39:19 +02:00
parent 95d5898650
commit 15aeac8e8b
148 changed files with 16731 additions and 554 deletions
--- a/docs/modules/attestor/vex-override-predicate.md
+++ b/docs/modules/attestor/vex-override-predicate.md
@@ -0,0 +1,151 @@
+# VEX Override Predicate Specification
+
+## Overview
+
+The VEX Override predicate provides a cryptographically signed record of operator decisions to override or annotate vulnerability assessments. This enables auditable, tamper-evident records of security triage decisions within the StellaOps vulnerability management workflow.
+
+## Predicate Type URI
+
+```
+https://stellaops.dev/attestations/vex-override/v1
+```
+
+## Use Cases
+
+1. **not_affected**: Document that a vulnerability does not affect the artifact in its deployed configuration
+2. **mitigated**: Record compensating controls that address the vulnerability
+3. **accepted**: Acknowledge an accepted risk with proper authorization
+4. **under_investigation**: Mark a vulnerability as being actively assessed
+
+## Schema
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `artifactDigest` | string | Artifact digest this override applies to (e.g., `sha256:abc123...`) |
+| `vulnerabilityId` | string | CVE or vulnerability identifier being overridden |
+| `decision` | string/enum | One of: `not_affected`, `mitigated`, `accepted`, `under_investigation` |
+| `justification` | string | Human-readable explanation for the decision |
+| `decisionTime` | ISO 8601 | UTC timestamp when the decision was made |
+| `operatorId` | string | Identifier of the operator who made the decision |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `expiresAt` | ISO 8601 | When this override should be re-evaluated |
+| `evidenceRefs` | array | References to supporting documentation |
+| `tool` | object | Information about the tool creating the predicate |
+| `ruleDigest` | string | Digest of the policy rule that triggered evaluation |
+| `traceHash` | string | Hash of reachability analysis at decision time |
+| `metadata` | object | Additional key-value metadata |
+
+### Evidence Reference Schema
+
+```json
+{
+  "type": "document|ticket|scan_report|attestation",
+  "uri": "https://...",
+  "digest": "sha256:...",
+  "description": "Optional description"
+}
+```
+
+### Tool Schema
+
+```json
+{
+  "name": "StellaOps",
+  "version": "1.0.0",
+  "vendor": "StellaOps Inc"
+}
+```
+
+## Sample Payload
+
+```json
+{
+  "artifactDigest": "sha256:a1b2c3d4e5f6...",
+  "decision": "not_affected",
+  "decisionTime": "2026-01-14T10:00:00Z",
+  "evidenceRefs": [
+    {
+      "description": "Security review document",
+      "digest": "sha256:def456...",
+      "type": "document",
+      "uri": "https://docs.example.com/security-review/123"
+    }
+  ],
+  "justification": "Component is compiled without the vulnerable code path due to build configuration",
+  "operatorId": "security-team@example.com",
+  "predicateType": "https://stellaops.dev/attestations/vex-override/v1",
+  "ruleDigest": "sha256:rule789...",
+  "tool": {
+    "name": "StellaOps",
+    "vendor": "StellaOps Inc",
+    "version": "1.0.0"
+  },
+  "traceHash": "sha256:trace012...",
+  "vulnerabilityId": "CVE-2024-12345"
+}
+```
+
+## Canonicalization Rules
+
+VEX override predicates MUST be serialized using RFC 8785 JSON Canonicalization Scheme (JCS) before signing:
+
+1. **Key ordering**: All object keys are sorted lexicographically (Unicode code point order)
+2. **Number format**: No exponent notation, no leading zeros, no trailing zeros after decimal
+3. **String encoding**: Default JSON escaping (no relaxed escaping)
+4. **Whitespace**: Minified JSON (no whitespace between tokens)
+5. **Property naming**: Original snake_case field names preserved (no camelCase conversion)
+
+### Serializer Configuration
+
+```csharp
+// DO NOT use CamelCase naming policy
+// DO NOT use UnsafeRelaxedJsonEscaping
+// Use JsonCanonicalizer.Canonicalize() before signing
+
+var canonicalJson = JsonCanonicalizer.Canonicalize(payloadJson);
+```
+
+## DSSE Envelope Structure
+
+```json
+{
+  "payloadType": "https://stellaops.dev/attestations/vex-override/v1",
+  "payload": "<base64-encoded-canonical-predicate>",
+  "signatures": [
+    {
+      "keyid": "key-identifier",
+      "sig": "<base64-signature>"
+    }
+  ]
+}
+```
+
+## Verification
+
+1. Decode the base64 payload
+2. Verify the signature using DSSE PAE (Pre-Authentication Encoding)
+3. Parse and validate the predicate schema
+4. Check expiration if `expiresAt` is present
+5. Optionally verify transparency log inclusion (Rekor anchoring)
+
+## Offline Verification
+
+The predicate supports offline verification when:
+- The signing certificate chain is bundled
+- Transparency log proofs are embedded
+- No network access is required for validation
+
+See [Rekor Verification Design](./rekor-verification-design.md) for transparency log integration details.
+
+## Related Documents
+
+- [Attestor Architecture](./architecture.md)
+- [DSSE Roundtrip Verification](./dsse-roundtrip-verification.md)
+- [Transparency Logging](./transparency.md)
+- [VEX Consensus Guide](../../VEX_CONSENSUS_GUIDE.md)