Omv report

VulDB Report Generator

References

Load these when needed — do not load all at once:

• references/ecosystems.md — vendor naming rules, version verification commands, duplicate CVE search databases, CWE→Class mapping. Read when ecosystem-specific details are needed.
• references/shared/cvss-builder.md — metric-by-metric CVSS v3.1 decision table with common vector combinations. Read when computing the CVSS score.
• contracts/evidence.v1.yaml — structured input contract from omv-find; read when the user provides a handoff packet or asks to continue from finder results.
• contracts/verification.v1.yaml — adversarial review sidecar. Read when .omv/verifications/<id>.yaml exists or the user asks for a high-confidence report.
• contracts/source-ref.v1.yaml — optional local source identity sidecar. Read when .omv/sources/<id>.yaml exists; a locator is recorded input, not proof of remote authenticity.
• contracts/report-provenance.v1.yaml — generated report input manifest shape used by omv report provenance.
• references/report-templates.md — reusable VulDB, GHSA, OSV, and standalone Markdown advisory templates. Read when the user requests a specific report format.
• references/examples/xss-npm.md — complete filled report for a click-triggered XSS in an npm package.
• references/examples/path-traversal-go.md — complete filled report for an unauthenticated path traversal in a Go module.
• references/examples/prototype-pollution-npm.md — filled report for prototype pollution in an npm package.
• references/examples/redos-python.md — filled report for ReDoS in a Python package.

---

HARD-GATE: verification before submission-ready claims

NO submission-ready VulDB / CVE / GHSA / OSV prose WITHOUT fresh gate evidence:
  1. omv findings validate <id> OK (when CLI available)
  2. status: confirmed
  3. submissionScore ≥ 75
  4. omv review <id> --strict → ready   (or user explicitly asks for triage draft only)

If the gate fails: explain gaps, suggest /omv-audit, /omv-repro, /omv-critic, or omv review.
Label any incomplete output triage draft — not for submission.
Do not rationalize “almost ready” into submission-ready wording.

Validity Check

Flag these patterns before writing — each one is a common rejection reason:

Pattern	Why VulDB rejects it
Attacker must supply the app's own code/config to trigger	Classified as developer misuse, not a library vuln
Sink found (eval, innerHTML, window.open) but no attacker-controlled input path proven	Sink ≠ vulnerability — prove the full data flow
No concrete tested version number	Submissions without a version boundary get rejected
Theoretical risk, no PoC	Requires a reproducible demonstration
Likely duplicate CVE exists	Search NVD, GHSA, and the ecosystem DB first

If a flag appears, tell the user what is missing and how to address it before continuing.

If the input is an omv-find handoff packet (Evidence.v1), apply contracts/evidence.v1.yaml before drafting:

• status: blocked means explain blockers instead of writing a submission-ready report.
• status: candidate means produce a triage draft only.
• status: confirmed can become a submission-ready report if required fields are present.
• Preserve unverified fields as unverified; do not silently upgrade them to confirmed facts.

Evidence Preflight

Before writing any submission-ready report from finder output, consume the local validation result:

1. If the user gives a finding id such as demo, read .omv/findings/demo.yaml.
2. If the user gives a path, read that Evidence.v1 file.
3. Run or ask for omv findings validate <id|path> --json when CLI tools are available.
4. If .omv/threatmaps/<id>.yaml exists, run or ask for omv threat-map validate <id> --json.
5. If .omv/verifications/<id>.yaml exists or the user wants a strict pre-submission gate, run or ask for omv verification validate <id> --json and omv review <id> --strict --json.
6. If .omv/sources/<id>.yaml exists, run or ask for omv sources validate <id> --json; treat a stale hash as a traceability warning, not as proof or disproof of the vulnerability.
7. If CLI tools are unavailable, validate manually against contracts/evidence.v1.yaml, contracts/verification.v1.yaml, and contracts/source-ref.v1.yaml when relevant, and say that deterministic validation was not run.

Use the validation result to choose output mode:

• Validation errors: lead with the errors and blockers; do not produce a submission-ready VulDB/CVE/GHSA/OSV report.
• ThreatMap errors: do not use graph claims as report proof until omv threat-map validate <id> passes.
• Verification failure, stale hash, or non-pass decision under strict verification: do not produce a submission-ready report; list the verifier disagreements or required changes first.
• status: blocked: explain blockers and minimum evidence needed.
• status: candidate: produce only triage notes or a draft outline clearly marked not ready for submission.
• status: confirmed: proceed only if required evidence is present and submission score is at least 75/100 (submissionScore = submission_score in contract — the gating score after deducting blockers/unverified fields/confidence penalties); include validation warnings in the pre-submission checklist.
• submissionScore below 75 or verdict.exploitability not proven: do not produce a submission-ready report; explain what evidence or reproduction artifact is missing.
• evidence.repro_artifacts present: reference the artifacts as local reviewer evidence. If absent, warn that the report depends only on inline reproducer text.

Deterministic Skeleton Renderer

For confirmed findings with submission score ≥ 75, run the deterministic renderer first to get a pre-filled skeleton. Resolve scripts/render_template.py relative to this installed SKILL.md; do not assume one global install directory.

The renderer requires the pinned Python dependency in scripts/requirements.txt. Install it once with python3 -m pip install -r <installed-skill-dir>/scripts/requirements.txt on macOS/Linux or py -3 -m pip install -r <installed-skill-dir>\scripts\requirements.txt on Windows.

macOS/Linux:

python3 <installed-skill-dir>/scripts/render_template.py \
  --finding .omv/findings/<id>.yaml --format vuldb|ghsa|osv|md

Windows PowerShell (the Python launcher is preferred):

py -3 <installed-skill-dir>\scripts\render_template.py `
  --finding .omv\findings\<id>.yaml --format vuldb

<installed-skill-dir> is the omv-report directory discovered by the active Agent. User-level defaults are ~/.agents/skills/omv-report for Codex and ~/.claude/skills/omv-report for Claude Code; project installs use .agents/skills/omv-report or .claude/skills/omv-report.

The renderer fills all structural fields (package, versions, CVSS, CWE, source→sink→guard, reproducer, dedup checklist) and leaves [DRAFT: ...] markers for prose sections. Fill in every [DRAFT: ...] before submitting. Do not submit placeholders.

After producing a submission-ready report for a confirmed finding, record and check its local inputs when the report was written under .omv/reports/<id>/:

omv sources init <id>              # optional; derives only known Evidence source facts
omv report provenance <id>        # run after report files are written
omv report artifacts <id>

SourceRef and report provenance are local hash records. Do not claim they verify remote repository authenticity. A legacy report without provenance.json remains usable but receives a warning until a manifest is created.

Then suggest removing it from the active local queue:

omv findings archive <id> --reason reported

If the report was written under .omv/reports/<id>/, the archive command records those artifact paths in archive metadata. For a stricter local gate, use:

omv findings archive <id> --reason reported --strict

Do not archive automatically unless the user asks; archiving is project-management state, not part of Evidence.v1 validation.

---

Severity

Pick one level and briefly explain the reasoning — overstating severity causes reviewers to distrust the whole report.

Severity	Conditions
Critical	RCE or auth bypass, no interaction, no auth, triggered by default config
High	High impact but requires auth or one user action; or severe data loss without interaction
Medium	Requires user interaction (e.g. click); or limited blast radius
Low	Info disclosure; DoS with heavy prerequisites

XSS that requires a click = Medium, always — even if session tokens are theoretically at risk.

Generate a CVSS v3.1 vector. Read references/shared/cvss-builder.md for the full metric decision table.

---

Output Formats

Four formats are supported. Read references/report-templates.md for the exact field layout and formatting rules of the one the user asks for — load it only for that format, not all at once.

• VulDB — form fields for a VulDB submission and CVE request. Default when the user says "submit to VulDB" or "request a CVE". The form's CVE checkbox needs all three: vendor contacted beforehand, no CVE assigned yet, not submitted to another CNA.
• GHSA — GitHub Security Advisory. Filing a GHSA auto-triggers a CVE request once published; do not also file the same issue to VulDB (duplicate CVE risk).
• OSV — machine-readable osv.dev JSON. Must be valid JSON; never invent an advisory ID. If no fix is known, omit the fixed event and say so in details.
• Markdown advisory — standalone blog post, maintainer report, or email disclosure.

Decision-level rules that apply to every format:

• Vendor is the project name, not the registry. Class uses a plain English name, not a CWE number (references/ecosystems.md has the CWE→Class table).
• Version uses up to and including or before — never ≤, latest, or all versions.
• PoC uses a verification payload only (e.g. alert(document.domain)) — no cookie-exfiltration or outbound-request payloads. A self-contained file plus a screenshot/GIF meaningfully improves acceptance.
• Describe the full exploit path: attacker control point → vulnerable code → impact. State required user interaction explicitly so reviewers don't assume the severity is exaggerated.
• Keep facts identical across formats; do not force one platform's field syntax into another.

For confirmed findings scoring ≥ 75, run the deterministic skeleton renderer (Evidence Preflight above) before hand-writing prose, then fill every [DRAFT: ...] marker.

---

Deterministic Helpers

Use bundled scripts when they fit the task:

• scripts/check_output.py: runs heuristic eval assertions against a saved omv-report output. It checks platform fields, blocked handoff behavior, OSV JSON structure, duplicate CNA warnings, severity sanity, and safe PoC wording.

---

CVE Request Checklist

• Affects a real product, not test or example code
• Clear vendor / product / version
• Real security impact — not just a bug
• Searched for existing CVEs in the right databases (see references/ecosystems.md)
• No GHSA number already assigned
• No other CNA currently processing this issue
• Vendor has been contacted, or there is a documented reason why not

---

Pre-Submit Checklist

• Severity matches actual attack conditions — not overstated
• Class field uses plain English name, not a CWE number
• Version uses up to and including or before — not ≤ or latest
• Vendor is the project name — not the registry name
• CVSS v3.1 vector included
• PoC uses a verification payload only (alert(document.domain))
• Full exploit path described: attacker control point → vulnerable code → impact
• Advisory URL is publicly accessible
• Duplicate CVE search completed
• Vendor contact status stated honestly
• Screenshot or GIF attached (optional but meaningfully improves acceptance rate)

Subagent Team Orchestration

这个 skill 在关键环节可以委托给专门 subagent：

• cvss-analyst — 从 Evidence.v1 impact 字段计算 CVSS v3.1 vector、score、severity。当 impact 字段已填且需要严格评分时委托：

  Use the cvss-analyst subagent to compute CVSS from: <vuln_class>, <impact_fields>
  

• dedup-analyst — 在递交前检索 NVD/GHSA/OSV 是否已有相同 advisories。submission 前强制推荐：

  Use the dedup-analyst subagent to check duplicates for: <ecosystem>, <package>, <vuln_class>
  

• report-writer — 从 confirmed Evidence.v1 推导具体平台格式（VulDB / GHSA / OSV / Markdown）。当用户指定特定格式时委托：

  Use the report-writer subagent to render: <finding_id>, <formats[]>
  

• verifier — submission 前对 evidence 结论做对抗复核（默认反驳 bias），并把结果写入 Verification.v1。提升 submission 信心时推荐：

  Use the verifier subagent with the cvss-deflate lens to refute the CVSS scoring for <finding_id>, then record the result in .omv/verifications/<id>.yaml
  

Subagent 是可选优化，不是强制。Codex 使用当前会话的原生 delegation，Claude Code 可使用 .claude/agents/*.md 中的角色定义。不要只把 verifier 结论保存在聊天记录里；如果它影响报告可信度，必须记录到 Verification.v1。