feat(agents): VEX Generation Agent — AI-Assisted Vulnerability Triage for Any Codebase

### Custom Agent Name

/vex-generator

### Type

Custom Agent

### Purpose

## Proposal: VEX Generation Agent — AI-Assisted Vulnerability Triage for Any Codebase

### Overview

Add a new Copilot agent to the `security` collection that enables **any hve-core consumer** to scan their own codebase for dependency vulnerabilities, perform AI-assisted exploitability analysis, and produce OpenVEX-compliant documents — all using local CLI tools and plain HTTP fetches, with no MCP server dependencies.

This agent is a **general-purpose security tool shipped as part of hve-core's security plugin**. Once it exists, it also enables the [VEX Workflow proposal](https://github.com/microsoft/hve-core/issues/1220) for hve-core's own releases — but that's a secondary benefit, not the primary goal.

### Motivation

**For hve-core consumers (primary):**

- Teams adopting hve-core already get security planning (`security-planner`), OWASP code review (`security-reviewer`), and supply chain posture assessment (`sssc-planner`). But there's a gap between *knowing your dependencies have CVEs* (Dependabot, Trivy) and *communicating whether those CVEs are actually exploitable in your context* (VEX).
- This agent closes that gap. A developer runs `/vex-scan`, points it at their codebase, and gets a draft VEX document with evidence-backed exploitability determinations — the same kind of analysis that currently requires a dedicated security engineer.
- The output is an OpenVEX JSON file that can be shared with consumers, auditors, and compliance tools (Grype, Trivy) to suppress false-positive CVE alerts downstream.

**For hve-core itself (secondary):**

- Once this agent ships in the security collection, the [manual VEX workflow proposal](https://github.com/microsoft/hve-core/issues/1220) becomes implementable: maintainers use `/vex-scan` against hve-core's own dependencies, review the draft, and commit the final document to `security/vex/hve-core.openvex.json` as part of the release pipeline.

**Inspiration:** [dasiths/ai_generated_vex](https://github.com/dasiths/ai_generated_vex) demonstrates this pattern using MCP servers (`trivy-mcp`, `vexdoc-mcp`, `osv-mcp`). This proposal adapts the concept for hve-core's agent architecture with a **no-MCP-dependency** constraint, preferring local CLI tools and direct REST API calls.

### How It Fits in hve-core

#### Within the Security Collection

The agent ships as part of the existing `security` plugin/collection, alongside the other security agents:

| Existing agent | What it covers | Gap this fills |
|---|---|---|
| `security-reviewer` | OWASP Top 10 assessment of application code | Does NOT scan dependencies for CVEs or produce VEX |
| `security-planner` | STRIDE threat modeling, security plan generation | Strategic planning — no vulnerability scanning |
| `sssc-planner` | Supply chain *posture* assessment (OpenSSF, SLSA) | Assesses process maturity — doesn't produce VEX artifacts |
| **`vex-generator`** (new) | **Dependency CVE scanning → exploitability analysis → OpenVEX output** | **Tactical: scans actual dependencies, determines real exploitability, produces machine-readable VEX** |

#### How consumers invoke it

```text
# Mode 1: Full scan of your codebase
/vex-scan

# Mode 2: Triage an existing scan report or SBOM
/vex-triage
```

The agent asks for product name, scope (directories), and optionally an existing Trivy JSON or SBOM file, then runs autonomously through scan → enrich → analyze → generate.

### Agent Architecture

#### MCP-Free Tool Strategy

The key constraint is **no MCP server dependencies**. Every tool from the `ai_generated_vex` reference project is replaced with a local CLI or HTTP alternative:

| `ai_generated_vex` approach | hve-core replacement | Implementation |
|---|---|---|
| `trivy-mcp` (MCP server) | Trivy CLI via `runCommands` | `trivy fs --format json --scanners vuln,misconfig,secret {scope}` |
| `osv-mcp` (Docker MCP server) | OSV.dev REST API via `fetch` | `POST https://api.osv.dev/v1/vulns/{CVE-ID}` |
| `vexdoc-mcp` (MCP server) | Agent writes OpenVEX JSON directly via `editFiles` | Uses embedded OpenVEX spec from skill — no `vexctl` or Node.js needed |

#### Supplementary CVE Data Sources (all via `fetch`, no dependencies)

| Source | URL Pattern | Data Provided |
|---|---|---|
| OSV.dev | `https://api.osv.dev/v1/vulns/{id}` | Affected versions, references, severity |
| NVD API 2.0 | `https://services.nvd.nist.gov/rest/json/cves/2.0?cveId={id}` | CVSS scores, CWE classification |
| GitHub Advisory DB | `https://api.github.com/advisories/{GHSA-ID}` | GitHub-specific severity, patched versions |

### Workflow

```text
User provides: scope, product name
│
▼
Phase 1: Vulnerability Scan
└─ runCommands: trivy fs --format json --scanners vuln,misconfig,secret {scope}
└─ Parse JSON → CVE inventory with package PURLs
│
▼
Phase 2: CVE Enrichment
└─ For each CVE-ID:
└─ fetch: OSV.dev → vulnerability mechanism, affected ranges
└─ fetch: NVD API → CVSS vector, CWE, description
└─ Build enriched CVE profiles
│
▼
Phase 3: Exploitability Analysis (per-CVE, via cve-analyzer subagent)
└─ Code reachability: codebase + search to trace import → usage → entry point
└─ Attack vector assessment: network exposure, auth requirements, input validation
└─ Environmental context: deployment protections, runtime mitigations
└─ Evidence collection: code snippets, configs, execution paths
└─ Status determination: not_affected | affected | fixed | under_investigation
│
▼
Phase 4: Report Generation
└─ editFiles: OpenVEX JSON document
└─ editFiles: Security assessment report (markdown)
└─ editFiles: Executive summary
└─ Output to: docs/security/reports/{report-name}/
```

### Artifact Placement

```text
.github/
├── agents/security/
│ └── vex-generator.agent.md ← orchestrator
│ └── subagents/
│ └── cve-analyzer.agent.md ← per-CVE deep analysis
├── prompts/security/
│ └── vex-scan.prompt.md ← /vex-scan command
│ └── vex-triage.prompt.md ← /vex-triage command
├── instructions/security/
│ └── vex-generation.instructions.md ← status logic, evidence requirements
├── skills/security/
│ └── openvex-spec.skill.md ← OpenVEX schema reference
```

### Agent Design

#### `vex-generator.agent.md` — Orchestrator

```yaml
---
name: vex-generator
description: "Scans dependencies for vulnerabilities, analyzes CVE exploitability against the codebase, and generates OpenVEX documents using local CLI tools - Brought to you by microsoft/hve-core"
tools: ['codebase', 'search', 'editFiles', 'fetch', 'runCommands', 'think', 'agent']
agents:
- cve-analyzer
---
```

- Runs Trivy CLI scans via `runCommands`
- Fetches CVE details from OSV.dev and NVD via `fetch`
- Delegates per-CVE deep analysis to `cve-analyzer` subagent
- Assembles final OpenVEX JSON directly (no `vexctl` or MCP needed)
- Writes all output to `docs/security/reports/{report-name}/`

#### `cve-analyzer.agent.md` — Per-CVE Subagent

```yaml
---
name: cve-analyzer
description: "Deep exploitability analysis for a single CVE against the current codebase - Brought to you by microsoft/hve-core"
tools: ['codebase', 'search', 'fetch', 'think']
agents: []
disable-model-invocation: true
---
```

- Receives enriched CVE profile from orchestrator
- Traces code reachability using `codebase` and `search`
- Determines VEX status with evidence-backed justification
- Returns structured finding for inclusion in final VEX document

### Consumer Value

The agent produces three deliverables for any codebase it's pointed at:

| Deliverable | File | Audience |
|---|---|---|
| Executive summary | `summary.md` | Management, security leads |
| Technical report | `yyyy-mm-dd-report.md` | Security engineers, developers |
| OpenVEX document | `vex.json` | Automated tooling (Grype, Trivy), auditors, downstream consumers |

The OpenVEX document is the key differentiator: it's machine-readable, spec-compliant, and can be fed back into Trivy/Grype to suppress false-positive CVE alerts:

```bash
# Consumer uses the VEX to filter scan results
trivy fs --vex vex.json --format table .
```

### Enabling the hve-core VEX Workflow

Once this agent ships, the [VEX Workflow proposal](https://github.com/microsoft/hve-core/issues/1220) becomes straightforward:

1. hve-core maintainers run `/vex-scan` against the repository before a release
2. Review the draft VEX document for accuracy
3. Commit the reviewed document to `security/vex/hve-core.openvex.json`
4. The release pipeline attests and uploads it alongside existing SBOM artifacts

The agent produces the **draft**; humans provide the **sign-off**. The VEX workflow issue handles the release integration (attestation, upload, documentation).

### Implementation Plan

#### Phase 1: Core Agent + Skill

- [ ] Create `openvex-spec.skill.md` — OpenVEX schema reference, status definitions, justification codes
- [ ] Create `vex-generation.instructions.md` — evidence requirements, status logic, report templates
- [ ] Create `cve-analyzer.agent.md` subagent
- [ ] Create `vex-generator.agent.md` orchestrator

#### Phase 2: Prompts + Collection Integration

- [ ] Create `/vex-scan` prompt (Mode 1: full pipeline)
- [ ] Create `/vex-triage` prompt (Mode 2: from existing report)
- [ ] Add all artifacts to security collection with `maturity: experimental`
- [ ] Add `openvex` to `.cspell/general-technical.txt`

#### Phase 3: Testing

- [ ] Test against a known-vulnerable project (e.g., intentionally outdated dependencies)
- [ ] Validate OpenVEX output against spec
- [ ] Test `/vex-triage` with existing Trivy JSON and SPDX SBOM inputs
- [ ] Tune exploitability analysis prompting for accuracy

#### Phase 4: Documentation

- [ ] Agent documentation in `docs/agents/security/`
- [ ] Update `plugins/security/README.md` with new agent, commands, and skill
- [ ] Add usage examples to `docs/hve-guide/roles/security-architect.md`
- [ ] Create `docs/security/vex-verification.md` for consumers

### Prerequisites for Consumers

| Tool | Purpose | Install |
|---|---|---|
| Trivy (v0.63.0+) | Vulnerability scanning | `brew install trivy` / `apt install trivy` |

That's it. No Docker, Go, Node.js, or MCP servers required.

### Open Questions

1. **Output location**: `docs/security/reports/` (persistent, git-friendly) vs. `.copilot-tracking/security/vex/` (ephemeral tracking)?
2. **Confidence thresholds**: Should the agent flag CVEs where exploitability confidence is below a threshold for mandatory human review?
3. **SBOM input support**: Should Mode 2 (`/vex-triage`) accept SPDX JSON SBOMs in addition to Trivy JSON reports?
4. **OWASP integration**: Should the agent optionally invoke `security-reviewer` for application-level vulnerability discovery alongside dependency CVE scanning?

### References

- [dasiths/ai_generated_vex](https://github.com/dasiths/ai_generated_vex) — Inspiration (MCP-based approach)
- [OpenVEX Specification](https://openvex.dev/)
- [OSV.dev API](https://osv.dev/docs/)
- [NVD API 2.0](https://nvd.nist.gov/developers/vulnerabilities)
- [Trivy CLI Documentation](https://aquasecurity.github.io/trivy/)
- [VEX Workflow Proposal](https://github.com/microsoft/hve-core/issues/1220) — manual VEX maintenance for hve-core releases (enabled by this agent)
- [SBOM Verification Guide](https://github.com/microsoft/hve-core/tree/main/docs/security/sbom-verification.md) — existing SBOM consumer documentation pattern

### Requirements

_No response_

Start by reviewing the existing security collection and its artifacts under .github/agents/security/, prompts/security/, instructions/security/, and skills/security/, then compare the proposal with issue 1220. Check the Trivy and OpenVEX references before defining the four planned phases. Done means the listed agent, subagent, prompts, skill, instructions, collection integration, validation, and documentation work are addressed.

Written by the indexing model from the issue text.