Skip to main content
rule CX Codex

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

Install into GitHub Copilot · Manually: put the files in place All methods and platforms ↓
.github/instructions/vex-generation.instructions.md
Open on GitHub

What 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_affected for 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.md

The applyTo field sets which files it applies to

Step 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

Similar IDE rules

All IDE rules for Security →

From the same set148

The whole set →
rust-tests This rule sets conventions for Rust tests, from module placement and naming to fixtures and HTTP mocks. Use it when you want tests in a project to follow the same structure. CX Codex +1 ★ 1,627repo stars CVE Analyzer CVE Analyzer — a subagent for deep CVE analysis: checks if vulnerable code is reachable in the project and returns evidence-backed VEX status. CX Codex +1 ★ 1,627repo stars python-script python-script defines Python 3.11+ script standards for Claude Code, enforcing package workflows with uv, modern type syntax, and clean CLI structures. CX Codex +1 ★ 1,627repo stars hve-artifact-authoring The hve-artifact-authoring skill guides the creation and validation of HVE Core agents, prompts, instructions, and skills. Use it when preparing an artifact in the repository and checking it against project conventions. CX Codex +1 ★ 1,627repo stars dataops Microsoft DataOps and DS/MLOps testing reference: where to validate data, how to write pipeline tests, and how to tell validation errors from drift. CX Codex +1 ★ 1,627repo stars session-log-canvas-update session-log-canvas-update diffs Copilot session event schemas against the canvas baseline. Keeps the Session Log canvas in sync across Copilot runtime updates. CX Codex +1 ★ 1,627repo stars Backlog Grooming Backlog Grooming reviews selected open GitHub issues against repository evidence and returns a maintainer report without changing those issues. CX Codex +1 ★ 1,627repo stars git-commit git-commit walks through confirming which paths to stage, then makes one local Conventional Commit, or just drafts a commit message for changes already staged. CX Codex +1 ★ 1,627repo stars

Project sponsors

Companies that keep this analytics open