vex-generation — Claude Code rule for VEX reports
The vex-generation rule guides AI-assisted VEX triage with evidence requirements, confidence bands, and status constraints. Use it when an agent drafts vulnerability findings for human review.
MIT ★ 1,627 updated 2026-10-25
.github/instructions/vex-generation.instructions.mdWhat vex-generation does
The rule requires evidence for each VEX status and a confidence-band assignment before the agent drafts a statement. If reachability or exploitability is uncertain, the status must be under_investigation. The agent cannot assign not_affected in the Low band, and Medium- and Low-confidence findings need structured questions for a human reviewer.
A triage report has an executive summary, per-CVE technical findings, and an OpenVEX JSON document. The technical section covers package versions, reachability, evidence citations, confidence, and the recommended status. The JSON must validate against the OpenVEX v0.2.0 schema. A human approver is the author of record; the agent must not claim that role. The rule also covers identifier lookups and licensing when using advisory data. For schema guidance, it points to the vex skill and its SKILL.md file.
What it helps with
- draft a VEX triage report for CVE findings
- support a vulnerability status with evidence
- flag uncertain findings for human review
- resolve CVEs through advisory aliases
- prepare OpenVEX JSON under the stated rules
Example prompts for the agent
- Analyze these CVE findings and draft a VEX report with evidence for each status.
- Review whether the evidence supports
not_affectedfor each finding. - Create the OpenVEX JSON and add reviewer questions for low-confidence findings.
How to install vex-generation
Manually: put the files in place
.github/instructions/vex-generation.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.claude/rules/vex-generation.mdThe paths frontmatter field limits the files: move applyTo from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/vex-generation.mdcFrontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own
Manually: put the files in place
.devin/rules/vex-generation.mdManually: put the files in place
.clinerules/vex-generation.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about vex-generation
How do I install vex-generation in Claude Code?
Add the rule file at .claude/rules/vex-generation.md.
What does the vex-generation rule do?
It sets requirements for evidence, confidence routing, VEX statuses, report sections, and human approval when an agent drafts vulnerability findings.
What status applies when reachability is uncertain?
The rule requires under_investigation. It also bars not_affected in the Low confidence band.
Source text
vex-generation.instructions.md · MIT
--- description: "VEX generation rules: evidence requirements, confidence routing, forbidden transitions, report templates, and licensing posture for AI-assisted vulnerability triage - Brought to you by microsoft/hve-core" applyTo: '**/.github/agents/security/sssc-reviewer.agent.md, **/.github/agents/security/subagents/cve-*.agent.md' --- # VEX Generation Instructions Rules governing AI-assisted VEX document generation. Agents producing or editing OpenVEX documents must follow these instructions. For OpenVEX schema details, see the `vex` skill (read its `SKILL.md`). ## Evidence requirements, confidence routing, and forbidden transitions The canonical definitions for justification codes, evidence requirements per status, confidence-routing bands, and forbidden transitions live in the `vex` skill reference `references/vex-status-logic.md`. Agents must follow the decision tree, evidence thresholds, and band routing defined in that reference. The behavioral rules below supplement that reference with agent-specific constraints. ### Agent behavioral rules * Every VEX status determination must be supported by evidence proportional to its assertion strength. Stronger assertions (especially `not_affected`) require stronger evidence. * The agent must classify each finding into exactly one confidence band before drafting a VEX statement. * When reachability or exploitability is uncertain, the only valid status is `under_investigation`. * The agent is **forbidden** from drafting `not_affected` in the Low confidence band. * In the Medium and Low bands, the agent must include structured questions for the human reviewer. ## Author-of-record contract VEX documents require an accountable author for trust purposes. | Role | Description | |------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | Drafter | the AI agent. No trust requirement; the agent performs analysis and drafts the document. | | Reviewer | CODEOWNERS-required human approver who validates evidence and status determinations. | | Author of record | the merge commit author (the human approver). This is the accountable identity. | | Trust anchor | Sigstore identity of the reusable VEX attestation workflow, microsoft/hve-core/.github/workflows/vex-attest.yml, that attests the VEX document. | The agent must never represent itself as the author of record. The `author` field in OpenVEX documents must identify the maintainer team or organization, not the agent. ## Licensing posture When drafting VEX content, follow these rules for external data: | Source | License | Permitted use | |--------------------|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | OSV.dev | Mixed (varies by upstream source) | Check record provenance before paraphrasing. Only paraphrase CC0 or public domain records. Write original prose for CC-BY-4.0 sourced records. | | NVD API 2.0 | US Gov public domain | Use for CVSS vectors and CWE classification. | | GitHub Advisory DB | CC-BY-4.0 | Identifiers, aliases, CVSS, severity, and affected ranges (factual metadata) plus reference URLs. Do not quote or closely paraphrase prose. | OSV.dev aggregates records from multiple databases. Check the record `id` prefix (`GHSA-` = CC-BY-4.0, `RUSTSEC-` = CC0, `CVE-` from NVD = public domain) to determine the upstream license. When the upstream license is unclear, write original prose and cite the record URL as a reference. Write original remediation and impact prose. Do not copy from any external source. ## Identifier resolution and alias fallback Each data source is keyed by a different identifier, so a single-id lookup misses records that exist under an alias. OSV.dev and the GitHub Advisory Database are keyed by the native advisory id (`GHSA-`, `PYSEC-`, and similar) and return `404` for a `CVE-` query; NVD is keyed by the `CVE-` id. For each finding: 1. Collect every identifier: the scanner's primary id plus all `aliases`. 2. Query each source by the id it is keyed on (GitHub Advisory DB and OSV.dev by `GHSA-`/`PYSEC-`/native id; NVD by `CVE-`), and walk the aliases until a source resolves. The OSV package query resolves by package and version regardless of id. 3. Keep the first authoritative value per field (NVD for CVSS and CWE; OSV for affected ranges). 4. Treat advisory data as unavailable only after every identifier has been tried against every reachable source. The GitHub Advisory Database (`api.github.com`) is reachable in the gh-aw sandbox by default, while `api.osv.dev` and `services.nvd.nist.gov` require entries in the workflow `network:` allowlist. When OSV.dev and NVD are unreachable, fall back to the GitHub Advisory Database for the CVE alias, CVSS vector, severity, and affected packages. ## Report templates Agent-generated VEX triage output consists of three sections. ### Executive summary Brief overview for human reviewers. Include: * Total CVEs analyzed. * Counts by status (`not_affected`, `affected`, `fixed`, `under_investigation`). * Counts by confidence band. * Highlight any `affected` findings requiring immediate action. ### Technical report Per-CVE detailed findings. For each CVE include: * CVE identifier, severity (CVSS score and vector), and CWE classification. * Affected package and version range. * Confidence band assignment with rationale. * Reachability analysis: call path trace or explanation of why code is unreachable. * Evidence citations (file paths, line ranges, dependency tree output). * Recommended VEX status and justification code. * Structured questions for human reviewer (Medium and Low confidence only). ### OpenVEX JSON The generated `hve-core.openvex.json` document containing all VEX statements. Must: * Validate against the OpenVEX v0.2.0 schema (see `openvex-schema.md` reference). * Increment the document `version` field. * Set `timestamp` and `last_updated` to the current UTC issuance time for every content-changing revision. Before advancing the document timestamp, preserve the prior effective timestamp on every unchanged statement that inherited it from the document. * Set the `tooling` field to record document provenance: the drafting agent, the human-reviewed merge, and the reusable VEX attestation workflow's Sigstore identity. * Preserve existing statements that were not re-analyzed. * Use PURL format for all product identifiers. ## SBOM input precedence When multiple scan sources are available, prefer them in this order: 1. Trivy JSON output (richest vulnerability metadata). 2. OSV-Scanner JSON output. 3. SPDX-JSON SBOM (dependency list only, requires separate vulnerability lookup). ## Maturity All VEX generation artifacts ship at `experimental` maturity. Promote to `stable` after validation across three or more codebases with a false-positive rate of 5% or less on `not_affected` determinations.
© microsoft · MIT · microsoft/hve-core