microsoft / microsoft/hve-core
feat: Add VEX (Vulnerability Exploitability eXchange) Workflow
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
### Issue Description
## Proposal: Add VEX (Vulnerability Exploitability eXchange) Workflow
### Overview
To complement our existing supply chain security practices (SBOM and build provenance attestations), introduce a VEX (Vulnerability Exploitability eXchange) document and process. VEX provides a machine-readable status for vulnerabilities in dependencies, dramatically improving signal-to-noise for downstream consumers and aligning HVE Core with modern supply chain standards.
### Motivation
- **Consumers and auditors currently receive only an SBOM**: All dependencies and transitive packages are listed, but every potential CVE is flagged whether or not it's exploitable in this project.
- **VEX augments SBOMs**: Maintainers/auditors can communicate actual risk (`Affected`, `Not Affected`, `Fixed`, `Under Investigation`) for CVEs, helping consumers prioritize real vulnerabilities, not theoretical ones.
- **Noise reduction**: With 123 forks and growing adoption, a VEX document prevents a flood of "are you affected by CVE-X?" issues every time a high-profile vulnerability is disclosed in a common dependency.
- **Best practices alignment**: Complements our existing Sigstore, SLSA, and OpenSSF posture for supply chain security maturity.
### Current State
The release pipeline already produces and attests the following artifacts per release:
| Suffix | Format | Purpose |
|---|---|---|
| `.spdx.json` | SPDX 2.3 JSON | Software Bill of Materials |
| `.sigstore.json` | Sigstore bundle (JSON) | Cryptographic attestation envelope |
| `.intoto.jsonl` | in-toto DSSE envelope | Provenance statement |
VEX would add a new row to this table as a natural extension.
### VEX Workflow
VEX is **not** auto-generated — it requires human triage. The workflow is:
1. A CVE is disclosed in a dependency (flagged by Dependabot, Grype, Trivy, etc.)
2. A maintainer investigates whether the vulnerable code path is reachable in HVE Core
3. The maintainer updates the VEX document in `security/vex/hve-core.openvex.json` with a status entry
4. The VEX file ships with the next release, attested and uploaded alongside existing artifacts
### Implementation Plan
#### Phase 1: Foundation
- [ ] Choose VEX format — recommend [OpenVEX](https://openvex.dev/) for simplicity and ecosystem compatibility
- [ ] Create initial VEX document at `security/vex/hve-core.openvex.json`
- [ ] Triage any currently known CVEs in production dependencies and populate initial statements
- [ ] Add `openvex` to `.cspell/general-technical.txt`
#### Phase 2: CI Integration
- [ ] Add VEX schema validation step to PR validation pipeline (lint/check well-formedness)
- [ ] Optional: Add a "VEX gap" CI job that cross-references SBOM scan results against VEX entries and warns on unaddressed CVEs
#### Phase 3: Release Pipeline
- [ ] Add a step in the `attest-and-upload` job (in both `release-stable.yml` and `release-prerelease.yml`) to:
- Copy VEX document into release artifacts
- Attest with Sigstore (same as SBOM)
- Upload alongside existing `.spdx.json`, `.sigstore.json`, and `.intoto.jsonl` files
- [ ] Update the Release Artifact Formats table in `SECURITY.md` to include the new `.openvex.json` suffix
- [ ] Update `append-verification-notes` job to reference VEX in release notes
#### Phase 4: Documentation
- [ ] Create `docs/security/vex-verification.md` (parallel to `sbom-verification.md`) covering:
- What VEX is and how it complements the SBOM
- How to download and verify the VEX document
- How to interpret status values (`not_affected`, `affected`, `fixed`, `under_investigation`)
- How to consume VEX alongside the SBOM in tooling (Grype, Trivy, etc.)
- [ ] Update `docs/security/security-model.md` control table with a new VEX control entry
- [ ] Update `docs/agents/sssc-planning/phase-reference.md` capability table
### Proposed Repo Structure
```
security/
vex/
hve-core.openvex.json ← VEX document, maintained manually, committed to git
docs/security/
vex-verification.md ← consumer-facing verification and interpretation guide
```
### Example VEX Statement
```json
{
"@context": "https://openvex.dev/ns/v0.2.0",
"@id": "https://github.com/microsoft/hve-core/security/vex/2026-03-27",
"author": "Microsoft HVE Core Maintainers",
"timestamp": "2026-03-27T00:00:00Z",
"statements": [
{
"vulnerability": { "@id": "https://nvd.nist.gov/vuln/detail/CVE-2026-XXXXX" },
"products": [
{ "@id": "pkg:npm/@microsoft/hve-core" }
],
"status": "not_affected",
"justification": "vulnerable_code_not_in_execute_path",
"impact_statement": "The affected parsing function is never invoked by HVE Core"
}
]
}
```
### References
- [OpenVEX Specification](https://openvex.dev/)
- [CycloneDX VEX](https://cyclonedx.org/capabilities/vex/)
- [CISA VEX Overview](https://www.cisa.gov/resources-tools/resources/minimum-requirements-vulnerability-exploitability-exchange-vex)
- [Current SBOM verification guide](https://github.com/microsoft/hve-core/tree/main/docs/security/sbom-verification.md)
- [Security model controls](https://github.com/microsoft/hve-core/tree/main/docs/security/security-model.md)
- [`attest-and-upload` job in release-stable.yml](https://github.com/microsoft/hve-core/tree/main/.github/workflows/release-stable.yml)
- [`attest-and-upload` job in release-prerelease.yml](https://github.com/microsoft/hve-core/tree/main/.github/workflows/release-prerelease.yml)
### Additional Context
_No response_
Contributor guide
Research direction
Start by reading the existing SBOM verification guide, SECURITY.md artifact table, and the attest-and-upload jobs in .github/workflows/release-stable.yml and release-prerelease.yml. Then review the proposed security/vex/hve-core.openvex.json and related documentation and CI locations. Done means the VEX document is validated, included and attested in release artifacts, and the referenced security and verification documentation is updated.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, json
- Domain
- devops, documentation, release, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100