Merge pull request #5 from bx33661/codex/intelligence-lifecycle-stability

Add request broker, pattern-packs, and CLI hardening

Author: bx33661

.gitignore

@@ -31,3 +31,6 @@ __pycache__/
 .idea/
 *.swp
 *.swo
+.omv/repro/
+.omv/reports/
+.omv/archive/

CONTRIBUTING.md

@@ -45,6 +45,8 @@ python3 scripts/release_check.py
 - Do not add credential theft, exfiltration, or abuse payloads.
 - Keep proof-of-concept examples local and minimal.
 - Preserve uncertainty and unverified fields in reports.
+- Keep bundled skills, references, walkthroughs, and golden outputs methodology-first. Use sanitized `demo-*`, `example-*`, or `fixture-*` names for examples.
+- Concrete real package names, CVEs, and advisory URLs are acceptable only when they are user-provided finding data, schema/format validation examples, or explicit primary-source research outputs with appropriate context.
 
 ## Pull Requests
 

README.md

@@ -32,14 +32,18 @@
 | **Evidence ledger** | `.omv/findings/*.yaml` keeps structured Evidence.v1 research state. |
 | **Audit workflow** | `/omv-audit` proves or blocks candidate findings using source -> sink -> guard reasoning. |
 | **Local reproduction** | `/omv-repro` records user-observed local results and repro artifacts. |
+| **Passive intelligence** | `/omv-radar` and `/omv-dedup` track watchlist changes and duplicate advisory risk. |
 | **Report drafting** | `/omv-report` generates review-friendly advisory drafts from validated findings. |
+| **Disclosure lifecycle** | `/omv-disclose`, `/omv-critic`, and `omv submissions ...` cover pre-submit review and post-submit tracking. |
+| **Request reliability** | `omv request ...` classifies rate limits, request refusals, source health, and cached metadata fetches. |
 | **CLI management** | `omv dashboard`, `omv doctor`, and `omv findings ...` keep local state inspectable. |
 
 ## Quick Start
 
 ```sh
 npx oh-my-vul setup
 omv doctor
+omv request preflight
 ```
 
 If `omv` is not on your `PATH`, use npx:
@@ -61,6 +65,9 @@ omv findings validate demo-traversal
 omv findings doctor demo-traversal
 
 /omv-report demo-traversal
+/omv-critic demo-traversal
+/omv-disclose timeline demo-traversal
+omv submissions record demo-traversal --platform vuldb --submission-id 12345 --url https://example.test/submission/12345
 omv report artifacts demo-traversal
 ```
 
@@ -104,8 +111,10 @@ Project-level setup writes `.omv/setup-scope.json` so `omv doctor` can resolve t
   -> omv repro init <id>
   -> /omv-repro when observed_result still needs local confirmation
   -> omv findings validate <id>
-  -> omv findings doctor <id>
+  -> /omv-critic
   -> /omv-report
+  -> /omv-disclose and omv submissions ...
+  -> omv findings doctor <id>
   -> omv report artifacts <id>
   -> advisory draft for VulDB, CVE, GHSA, OSV, or Markdown
 ```
@@ -122,6 +131,10 @@ Project-level setup writes `.omv/setup-scope.json` so `omv doctor` can resolve t
 | `omv-audit` | `/omv-audit` | audit | Deep-audit a candidate finding — prove or disprove the vulnerability, fill Evidence.v1 fields for omv-report |
 | `omv-repro` | `/omv-repro` | audit | Guide local reproduction of a finding — walk through execution, record observed_result, confirm or block |
 | `omv-report` | `/omv-report` | reporting | Generate VulDB/CVE/GHSA/OSV advisory reports from confirmed findings |
+| `omv-radar` | `/omv-radar` | intelligence | Passive watchlist intelligence — refresh local advisory/release signals and summarize radar events |
+| `omv-dedup` | `/omv-dedup` | intelligence | Duplicate advisory analysis — generate deterministic NVD/GHSA/OSV/ecosystem queries and update Evidence.v1 dedup fields |
+| `omv-disclose` | `/omv-disclose` | disclosure | Responsible disclosure lifecycle helper — draft vendor emails, timelines, and local submission bookkeeping guidance |
+| `omv-critic` | `/omv-critic` | reporting | Adversarial pre-submission review — identify likely CNA rejection reasons before report generation |
 <!-- omv:skills:end -->
 
 ## Finding Targets
@@ -154,6 +167,23 @@ csrf xxe sql ssti sandbox redirect upload crypto infoleak
 
 `/omv-find` should return evidence-backed candidates: repository, registry identity, maintenance signal, code-size estimate, **source -> sink -> guard** notes, and local audit next steps.
 
+## Request Reliability
+
+`/omv-find` often needs public registry metadata, GitHub metadata, raw source files, and source archives. Those sources can be rate-limited, bot-blocked, missing, or temporarily unavailable. Use the TypeScript request broker before or during request-heavy research:
+
+```sh
+omv request preflight
+omv request preflight --json --refresh
+omv request fetch https://registry.npmjs.org/markdown-it --json
+omv request fetch https://api.github.com/repos/owner/repo --accept application/json --refresh
+```
+
+The broker writes cache entries under `.omv/cache/http/`, redacts sensitive response headers, and returns structured `failure.reason`, `rateLimit`, `expiresAt`, and `recommendation` fields. GitHub API requests automatically use `GITHUB_TOKEN` or `GH_TOKEN` when present.
+
+Common failure reasons are `rate_limited`, `auth_required`, `bot_blocked_or_forbidden`, `not_found`, `network_timeout`, `network_error`, `upstream_error`, and `invalid_url`. Treat these as research-state signals: keep affected fields unverified, prefer registry/source archive fallbacks, and avoid repeatedly retrying blocked URLs.
+
+See [docs/request-broker.md](docs/request-broker.md) for the full request broker behavior, JSON contract, cache policy, and Playwright evaluation.
+
 ## Evidence Ledger
 
 Project-local research state lives in `.omv/findings/`. These files are gitignored by default because they may contain private research notes.
@@ -175,6 +205,13 @@ Evidence files follow [contracts/evidence.v1.yaml](contracts/evidence.v1.yaml).
 - dedup status
 - unknown-field accounting
 
+Optional sidecars keep richer local state without bloating Evidence.v1:
+
+- `.omv/threatmaps/<id>.yaml` stores ThreatMap.v1 source -> sink -> guard graphs.
+- `.omv/radar/events.jsonl` stores passive watchlist intelligence events.
+- `.omv/submissions/<id>.yaml` stores report submission bookkeeping.
+- `.omv/notes/<id>.md` stores timestamped local research decisions.
+
 <details>
 <summary><strong>Status values</strong></summary>
 
@@ -205,6 +242,37 @@ Use `/omv-report` after you have a validated Evidence.v1 file or a complete hand
 - choose platform-specific wording for VulDB, GHSA, OSV, and Markdown advisories;
 - keep proof-of-concept language local and reviewer-safe.
 
+Before reporting, `/omv-critic <id>` reviews Evidence.v1 plus any ThreatMap.v1 sidecar and returns `reject_risk: low|medium|high`. It is intentionally different from `omv findings validate`: validation checks structure, critic checks argument quality.
+
+After reporting, track submissions locally:
+
+The identifiers in this snippet are sanitized placeholders for command shape.
+
+```sh
+omv submissions record demo-traversal --platform vuldb --submission-id 12345 --url https://example.test/submission/12345
+omv submissions track demo-traversal
+omv submissions close demo-traversal --cve CVE-2026-12345
+```
+
+## Passive Intelligence
+
+Create `.omv/radar/watchlist.yaml`, then run:
+
+The package names in bundled examples are sanitized fixture values. Use real package names only for user-provided research targets.
+
+```sh
+omv radar refresh --dry-run
+omv radar refresh
+omv radar brief
+```
+
+Radar uses passive advisory, registry, and repository metadata sources only. Dedup review starts with deterministic queries:
+
+```sh
+omv dedup demo-traversal
+omv dedup demo-traversal --confirm --existing-cve none --notes "searched NVD, GHSA, OSV, npm advisory DB"
+```
+
 ## Safety Boundary
 
 `oh-my-vul` supports **non-destructive vulnerability research only**:
@@ -225,6 +293,8 @@ Use `/omv-report` after you have a validated Evidence.v1 file or a complete hand
 | Document | Purpose |
 |---|---|
 | [README.zh-CN.md](README.zh-CN.md) | Chinese project guide. |
+| [docs/request-broker.md](docs/request-broker.md) | Request broker usage, failure classes, cache behavior, and Playwright evaluation. |
+| [docs/request-broker.zh-CN.md](docs/request-broker.zh-CN.md) | Chinese request broker guide. |
 | [docs/vulnerability-research-best-practices.zh-CN.md](docs/vulnerability-research-best-practices.zh-CN.md) | Chinese best-practices guide for vulnerability research with this project. |
 | [docs/examples/demo-finding-flow.md](docs/examples/demo-finding-flow.md) | Sanitized end-to-end finding workflow example. |
 | [docs/roadmap-0.8.md](docs/roadmap-0.8.md) | Planned `v0.8` CLI improvements. |

README.zh-CN.md

@@ -33,13 +33,15 @@
 | **深度审计** | `/omv-audit` 用 source -> sink -> guard 证明或否定候选漏洞。 |
 | **本地复现** | `/omv-repro` 记录用户真实本地观测和复现材料。 |
 | **报告生成** | `/omv-report` 从 validated finding 生成审稿友好的报告草稿。 |
+| **请求可靠性** | `omv request ...` 识别限流、拒绝、来源健康和缓存元数据请求。 |
 | **CLI 管理** | `omv dashboard`、`omv doctor`、`omv findings ...` 管理本地状态。 |
 
 ## 快速开始
 
 ```sh
 npx oh-my-vul setup
 omv doctor
+omv request preflight
 ```
 
 如果没有全局安装 `omv`，用 npx 临时运行：
@@ -121,6 +123,10 @@ omv version --json
 | `omv-audit` | `/omv-audit` | 深入审计候选 finding，补齐 Evidence.v1 证据字段 |
 | `omv-repro` | `/omv-repro` | 引导本地复现，记录真实 observed_result |
 | `omv-report` | `/omv-report` | 从 confirmed finding 生成 VulDB/CVE/GHSA/OSV 报告草稿 |
+| `omv-radar` | `/omv-radar` | 被动 watchlist 情报，刷新 advisory/release 信号 |
+| `omv-dedup` | `/omv-dedup` | 去重分析，生成 NVD/GHSA/OSV/生态查询并更新 Evidence.v1 |
+| `omv-disclose` | `/omv-disclose` | 负责任披露生命周期辅助，包括时间线和沟通草稿 |
+| `omv-critic` | `/omv-critic` | 提交前反向审稿，找出可能被 CNA 或平台拒绝的原因 |
 
 ## 发现审计目标
 
@@ -150,6 +156,23 @@ csrf xxe sql ssti sandbox redirect upload crypto infoleak
 
 `/omv-find` 应输出带证据的候选结果，包括仓库、注册表身份、维护活跃度、代码规模估计、**source -> sink -> guard** 笔记和下一步本地审计建议。
 
+## 请求可靠性
+
+`/omv-find` 经常要读取公开 registry 元数据、GitHub 元数据、raw 源码文件和源码归档。这些来源可能限流、拒绝、路径不存在或临时不可用。请求密集型研究前，先用 TypeScript request broker 检查来源健康：
+
+```sh
+omv request preflight
+omv request preflight --json --refresh
+omv request fetch https://registry.npmjs.org/markdown-it --json
+omv request fetch https://api.github.com/repos/owner/repo --accept application/json --refresh
+```
+
+broker 会把缓存写入 `.omv/cache/http/`，脱敏响应头，并输出结构化 `failure.reason`、`rateLimit`、`expiresAt` 和 `recommendation`。如果环境里有 `GITHUB_TOKEN` 或 `GH_TOKEN`，GitHub API 请求会自动使用 token。
+
+常见失败分类包括 `rate_limited`、`auth_required`、`bot_blocked_or_forbidden`、`not_found`、`network_timeout`、`network_error`、`upstream_error` 和 `invalid_url`。这些分类应作为研究状态信号：相关字段保持未确认，优先使用 registry/source archive fallback，不要反复重试已经被拒绝的 URL。
+
+完整行为、JSON 字段、缓存策略和 Playwright 评估见 [docs/request-broker.zh-CN.md](docs/request-broker.zh-CN.md)。
+
 ## Evidence 账本
 
 项目本地研究状态保存在 `.omv/findings/`。这些文件默认应视为私有研究记录，不应直接发布。
@@ -224,6 +247,9 @@ omv findings promote demo-traversal --status blocked
 
 | 文档 | 用途 |
 |---|---|
+| [README.md](README.md) | 英文项目指南 |
+| [docs/request-broker.zh-CN.md](docs/request-broker.zh-CN.md) | 请求代理、失败分类、缓存和 Playwright 评估 |
+| [docs/request-broker.md](docs/request-broker.md) | 英文 request broker 指南 |
 | [docs/vulnerability-research-best-practices.zh-CN.md](docs/vulnerability-research-best-practices.zh-CN.md) | 使用本项目做漏洞研究的最佳实践 |
 | [docs/examples/demo-finding-flow.md](docs/examples/demo-finding-flow.md) | 脱敏的端到端 finding 工作流示例 |
 | [docs/roadmap-0.8.md](docs/roadmap-0.8.md) | `v0.8` CLI 改进计划 |

assets/logo-candidates/oh-my-vul-logo-refined-a.png

@@ -10,7 +10,8 @@ Skills reference these files directly rather than duplicating schema content in
 |---|---|
 | `evidence.v1.yaml` | Finding object passed between `omv-find` and `omv-report`. Replaces the old `handoff-contract.md` in both skills. |
 | `candidate-list.v1.yaml` | Schema for the candidate list output produced by `omv-find`. |
-| `threat-map.v1.yaml` | Schema for the threat map sidecar produced by `omv-audit` (future). |
+| `threat-map.v1.yaml` | Optional dataflow threat map sidecar produced by `omv-audit`. |
+| `submission.v1.yaml` | Local submission tracking sidecar for post-report bookkeeping. |
 
 ## Versioning