# 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)