Merge pull request #15 from bx33661/feat/threat-map-producer

feat(cli): add omv threat-map init producer for ThreatMap.v1

Author: bx33661

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- Added `omv threat-map init <id>` — the producer side of the ThreatMap.v1 pipeline. Scaffolds `.omv/threatmaps/<id>.yaml` (finding_id + package filled from the finding, `paths: []` ready to fill) so `omv-audit` records source → transform → sink dataflow instead of hand-authoring YAML. The read pipeline (`omv findings show` rendering, archive sidecar handling) was already in place; this connects it.
+
 ## v0.9.0 - CLI command split and local findings dedup
 
 - Split the `omv` CLI dispatcher (`omv.ts`, 1434 lines) into one module per command under `commands/`, plus a `commands/shared.ts` arg-helper module and a `commands/index.ts` registry replacing the dispatch `switch`. The 12 duplicated command error handlers collapse into one. `omv.ts` is now a 7-line entry.

scripts/sync_skill_assets.py

@@ -38,6 +38,7 @@
     ("shared/references/patterns/java.md", "skills/omv-audit/references/patterns/java.md"),
     ("shared/references/patterns/ruby.md", "skills/omv-audit/references/patterns/ruby.md"),
     ("contracts/evidence.v1.yaml", "skills/omv-audit/contracts/evidence.v1.yaml"),
+    ("contracts/threat-map.v1.yaml", "skills/omv-audit/contracts/threat-map.v1.yaml"),
     ("contracts/evidence.v1.yaml", "skills/omv-repro/contracts/evidence.v1.yaml"),
     ("shared/references/cvss-builder.md", "skills/omv-report/references/shared/cvss-builder.md"),
     ("contracts/evidence.v1.yaml", "skills/omv-report/contracts/evidence.v1.yaml"),

skills/omv-audit/SKILL.md

@@ -47,13 +47,13 @@ Stay in passive research mode: read public source code only. Do not send request
 
 如果 finding 属于 npm、Python、Go、Rust、Java 或 Ruby，按需加载 `references/patterns/` 下对应生态文件，用其中的 source pattern、sink signature、expected guard、evidence criteria、false-positive checks 和 CWE 映射辅助判断。Pattern registry 是方法论，不是真实漏洞案例库；不要加载无关生态 registry。
 
-当证据链足够清楚时，额外生成可选 ThreatMap.v1 sidecar：
+当证据链足够清楚时，生成可选 ThreatMap.v1 sidecar，记录 source → transform → sink 的 dataflow 路径：
 
-```text
-.omv/threatmaps/<id>.yaml
+```bash
+omv threat-map init <id>
 ```
 
-ThreatMap 是 Evidence.v1 的补充，不替代 `evidence.source` / `evidence.sink` / `evidence.guard` 摘要字段。
+这会在 `.omv/threatmaps/<id>.yaml` 生成骨架（`finding_id` 和 `package` 块已从 finding 填好，`paths: []` 留待填写）。然后在每个已确认的 source → sink 路径下补一条 `paths[]` 条目：`source`（type/location/description）、`transforms[]`（中间每一步：parse/decode/normalize/validate/authorize）、`sink`、`guard`（present/bypassable）、`confidence`。Schema 见 `contracts/threat-map.v1.yaml`。ThreatMap 是 Evidence.v1 的补充，不替代 `evidence.source` / `evidence.sink` / `evidence.guard` 摘要字段；sidecar 不修改父 Evidence.v1 文件。
 
 解释审计结论时使用方法论语言：说明输入如何到达 sink、guard 为什么缺失或可绕过、哪些证据仍不充分。除非用户提供真实 finding 作为上下文，否则不要把真实包或真实 CVE 当作教程示例。
 
@@ -111,6 +111,7 @@ Use the CLI result for lifecycle handoff:
 
 - `omv findings validate <id>` — 校验字段完整性，输出 evidence/submission 分数
 - `omv findings promote <id> --status confirmed|blocked` — 更新 status 字段
+- `omv threat-map init <id>` — 生成 `.omv/threatmaps/<id>.yaml` ThreatMap.v1 dataflow 骨架
 - `omv findings workflow` — 显示 active findings 的下一步动作
 - `python3 shared/scripts/resolve_source_path.py --ecosystem npm --pkg <name>` — 获取源文件 raw URL
 - `python3 shared/scripts/collect_metadata.py --repo <github-url>` — 获取仓库元数据

skills/omv-audit/contracts/threat-map.v1.yaml

@@ -0,0 +1,60 @@
+# ThreatMap.v1 — optional dataflow threat map sidecar
+# Produced by: omv-audit
+# Consumed by: omv findings show, omv-critic, omv-report
+#
+# The full threat map for a single finding lives in a sidecar file:
+#   .omv/threatmaps/<id>.yaml
+# The parent `.omv/findings/<id>.yaml` Evidence.v1 file remains valid without
+# this sidecar. Evidence.v1 source/sink/guard fields stay as compatibility
+# summaries; this graph is used when a richer source -> transform -> sink path
+# is useful for audit review or report criticism.
+
+schema_version: "1"
+
+# ── Identity ──────────────────────────────────────────────────────────────────
+finding_id: ""           # id matching `.omv/findings/<id>.yaml`
+package:
+  ecosystem: ""
+  registry_name: ""
+  repository_url: ""
+  version_analyzed: ""
+
+# ── Dataflow Paths ────────────────────────────────────────────────────────────
+# One entry per discovered source-to-sink path.
+paths: []
+# Each path entry:
+#   - id: 1
+#     source:
+#       type: user_input | file | network | env | config
+#       location: "src/routes/upload.js:42"
+#       description: "req.body.filename passed directly"
+#     transforms:
+#       - type: parse | decode | normalize | validate | authorize | other
+#         location: "src/routes/upload.js:45"
+#         description: "filename is joined without canonical path check"
+#     sink:
+#       type: fs_write | exec | eval | html_render | sql | network_req
+#       location: "src/utils/file.js:88"
+#       description: "path.join(baseDir, filename) without normalization"
+#     guard:
+#       present: false
+#       description: "no path traversal check before join"
+#       bypassable: true
+#     confidence: high   # high | medium | low
+#     notes: ""
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+# Digest fields written into the parent Evidence.v1 object.
+summary:
+  path_count: 0
+  confirmed_paths: 0
+  highest_confidence: unknown    # high | medium | low | unknown
+  vuln_classes: []               # list of vulnerability class names identified
+  notes: ""
+
+# ── Provenance ────────────────────────────────────────────────────────────────
+provenance:
+  analysis_date: ""
+  tool: manual             # manual | semgrep | codeql | other
+  tool_version: unknown
+  analyst: ""

skills/omv-audit/evals/evals.json

@@ -84,6 +84,24 @@
           "text": "scope-changed SSTI must have CVSS >= 9.0 and S:C in vector"
         }
       ]
+    },
+    {
+      "id": 6,
+      "prompt": "/omv-audit demo-threatmap-path-traversal",
+      "expected_output": "Confirmed audit that also scaffolds a ThreatMap.v1 sidecar at .omv/threatmaps/<id>.yaml via `omv threat-map init`, then fills one paths[] entry with source, transforms, sink, and a missing/bypassable guard for a path-traversal finding.",
+      "files": [
+        "evals/golden/threatmap-path-traversal.md"
+      ],
+      "assertions": [
+        {
+          "type": "confirmed_complete_evidence",
+          "text": "must still produce a complete confirmed Evidence.v1 block"
+        },
+        {
+          "type": "threatmap_sidecar_present",
+          "text": "must scaffold .omv/threatmaps/<id>.yaml and fill a paths[] source->sink->guard entry"
+        }
+      ]
     }
   ]
 }

skills/omv-audit/evals/golden/threatmap-path-traversal.md

@@ -0,0 +1,61 @@
+## Audit Result
+
+status: confirmed
+
+evidence:
+  source: lib/extract.js:42 zip entry name from archive
+  sink: lib/extract.js:88 fs.createWriteStream path joined without normalization
+  guard: missing path traversal check before join
+  reproducer: run `node repro.js` in a local checkout with version 0.4.1
+  observed_result: local run writes a file outside the configured base directory
+
+cvss:
+  vector: CVSS:3.1/AV:L/AC:L/PR:N/UI:R/S:U/C:H/I:N/A:N
+  score: 5.5
+  severity: Medium
+
+dedup:
+  nvd_searched: true
+  ghsa_searched: true
+  ecosystem_db_searched: true
+  existing_cve: none
+
+## ThreatMap.v1 sidecar
+
+Ran `omv threat-map init demo-threatmap-path-traversal` to scaffold `.omv/threatmaps/demo-threatmap-path-traversal.yaml`, then filled one `paths[]` entry for the confirmed route:
+
+```yaml
+schema_version: "1"
+finding_id: "demo-threatmap-path-traversal"
+package:
+  ecosystem: "npm"
+  registry_name: "demo-archive-extractor"
+  repository_url: "https://github.com/example/demo-archive-extractor"
+  version_analyzed: "0.4.1"
+paths:
+  - id: 1
+    source:
+      type: file
+      location: "lib/extract.js:42"
+      description: "zip entry name read from archive"
+    transforms:
+      - type: normalize
+        location: "lib/extract.js:60"
+        description: "entry.name joined to base dir with path.join, no canonicalization"
+    sink:
+      type: fs_write
+      location: "lib/extract.js:88"
+      description: "fs.createWriteStream resolves outside base dir via ../"
+    guard:
+      present: false
+      description: "no path traversal check before join"
+      bypassable: true
+    confidence: high
+summary:
+  path_count: 1
+  confirmed_paths: 1
+  highest_confidence: high
+  vuln_classes: ["Path Traversal"]
+```
+
+The sidecar is optional and does not modify the parent Evidence.v1 file; `evidence.source`/`sink`/`guard` remain the compatibility summaries.

skills/omv-audit/scripts/check_output.py

@@ -76,6 +76,13 @@ def check(assertion_type: str, text: str) -> bool:
             and "S:C" in text
             and any(float(m) >= 9.0 for m in re.findall(r"score:\s*([\d.]+)", text))
         )
+    if assertion_type == "threatmap_sidecar_present":
+        return (
+            "threat-map init" in text
+            and ".omv/threatmaps/" in text
+            and "paths:" in text
+            and contains_all(text, ["source:", "sink:", "guard:"])
+        )
     raise SystemExit(f"unknown assertion type: {assertion_type}")
 
 

src/cli/__tests__/findings.test.ts

@@ -19,6 +19,7 @@ import {
   showFinding,
   validateFinding,
   validateFindings,
+  writeThreatMap,
 } from "../findings.js";
 import { archiveMetadataPath, archivedFindingsDir, findingReportsDir, findingReproDir, findingsDir, threatMapPath, workspaceIndexPath } from "../paths.js";
 import { recordSubmission } from "../submissions.js";
@@ -361,6 +362,44 @@ summary:
   }
 });
 
+test("writeThreatMap scaffolds an idempotent ThreatMap.v1 sidecar", async () => {
+  const projectRoot = await mkdtemp(join(tmpdir(), "omv-findings-"));
+
+  try {
+    const dir = await ensureFindingsDir(projectRoot);
+    await writeFile(join(dir, "demo.yaml"), BASE_FINDING, "utf-8");
+
+    const path = threatMapPath("demo", projectRoot);
+
+    const first = await writeThreatMap("demo", projectRoot);
+    assert.equal(first.written, true);
+    assert.equal(first.skipped, false);
+    assert.equal(first.path, path);
+    assert.ok(existsSync(path));
+
+    const body = await readFile(path, "utf-8");
+    assert.match(body, /schema_version: "1"/);
+    assert.match(body, /finding_id: "demo"/);
+    assert.match(body, /paths: \[\]/);
+
+    // showFinding picks up the scaffolded sidecar
+    const detail = await showFinding("demo", projectRoot);
+    assert.equal(detail.threatMap?.path, path);
+
+    // non-empty sidecar is skipped without --force
+    const second = await writeThreatMap("demo", projectRoot);
+    assert.equal(second.written, false);
+    assert.equal(second.skipped, true);
+
+    // --force overwrites
+    const third = await writeThreatMap("demo", projectRoot, { force: true });
+    assert.equal(third.written, true);
+    assert.equal(third.skipped, false);
+  } finally {
+    await rm(projectRoot, { recursive: true, force: true });
+  }
+});
+
 test("submission score is confidence weighted", async () => {
   const projectRoot = await mkdtemp(join(tmpdir(), "omv-findings-"));
 

src/cli/args.ts

@@ -62,6 +62,8 @@ export function validateArgs(args: string[]): ArgsValidation {
       return validateReproArgs(args.slice(1));
     case "report":
       return validateReportArgs(args.slice(1));
+    case "threat-map":
+      return validateThreatMapArgs(args.slice(1));
     case "workspace":
       return validateWorkspaceArgs(args.slice(1));
     case "findings":
@@ -84,7 +86,7 @@ export function validateArgs(args: string[]): ArgsValidation {
     case "submissions":
       return validateSubmissionsArgs(args.slice(1));
     default:
-      return fail(`Unknown command: ${command}. Valid commands: version, setup, uninstall, config, doctor, dashboard, workspace, findings, radar, request, dedup, disclose, submissions, repro, report, help`);
+      return fail(`Unknown command: ${command}. Valid commands: version, setup, uninstall, config, doctor, dashboard, workspace, findings, radar, request, dedup, disclose, submissions, repro, report, threat-map, help`);
   }
 }
 
@@ -189,6 +191,27 @@ function validateReportArgs(args: string[]): ArgsValidation {
   }
 }
 
+function validateThreatMapArgs(args: string[]): ArgsValidation {
+  const subcommand = args[0];
+  const rest = args.slice(1);
+  switch (subcommand) {
+    case "init":
+      return validateOptions(rest, {
+        command: "threat-map init",
+        flags: new Set(["--force", "--json", ...HELP_FLAGS]),
+        options: new Map(),
+        minPositionals: 1,
+        maxPositionals: 1,
+      });
+    case "help":
+    case "--help":
+    case "-h":
+      return rest.length === 0 ? ok() : fail(`threat-map ${subcommand} accepts no arguments`);
+    default:
+      return fail(`Unknown threat-map command: ${subcommand ?? ""}. Valid commands: init, help`);
+  }
+}
+
 function validateDiscloseArgs(args: string[]): ArgsValidation {
   const subcommand = args[0] ?? "timeline";
   const rest = args[0] ? args.slice(1) : args;

src/cli/commands/index.ts

@@ -16,6 +16,7 @@ import * as submissions from "./submissions.js";
 import * as config from "./config.js";
 import * as repro from "./repro.js";
 import * as report from "./report.js";
+import * as threatMap from "./threat-map.js";
 
 const REGISTRY: Record<string, (args: string[]) => Promise<void>> = {
   version: version.run,
@@ -33,6 +34,7 @@ const REGISTRY: Record<string, (args: string[]) => Promise<void>> = {
   config: config.run,
   repro: repro.run,
   report: report.run,
+  "threat-map": threatMap.run,
 };
 
 export async function run(): Promise<void> {