bx33661/oh-my-vul/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