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:

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.

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。