old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions
This commit is contained in:
master
@@ -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)
|
||||
Reference in New Issue
Block a user