upstream-radar 0.35.0 → 0.36.0

package/docs/README.zh-CN.md

@@ -96,7 +96,7 @@ FIRST EPSS estimated exploitation probability: 97.2% (percentile 100.0%)
 想立即检查一个真实发布的 DSH 插件，可以在空目录直接运行：
 
 ```bash
-npx --yes upstream-radar@0.35.0 inspect dsh-feishu-bot@0.15.8 --deep
+npx --yes upstream-radar@0.36.0 inspect dsh-feishu-bot@0.15.8 --deep
 ```
 
 它会直接输出简短的准入结论、覆盖情况、依赖数量、漏洞数量和下一步，不需要先
@@ -109,7 +109,7 @@ npx --yes upstream-radar@0.35.0 inspect dsh-feishu-bot@0.15.8 --deep
 npm 解析环境中目前无法建立完整依赖图：
 
 ```bash
-npx --yes upstream-radar@0.35.0 inspect \
+npx --yes upstream-radar@0.36.0 inspect \
   @sanqi-normal/dsh-webui-market-plugin@0.5.4 \
   --deep --fail-on never
 ```
@@ -309,6 +309,25 @@ npm：     dsh-feishu-bot@0.15.8
 因为一个持续存在的 mismatch 每天重复唤醒 Agent。机器可读定义见
 [`upstream-downstream-ir.schema.json`](../schemas/upstream-downstream-ir.schema.json)。
 
+### 把上游变化路由到受影响插件
+
+单独建立反向索引只能回答“谁使用了某个精确版本”。把它传给 observer 后，Radar
+会按包名对齐 old → new 变化：即使上游从 `parser@1.0.0` 变成 `parser@2.0.0`，而
+下游插件还停留在 `parser@1.0.0`，也会把这个插件和完整依赖路径列出来。覆盖不完整
+会继续显示为 `incomplete`，不会被当成已经确认的故障。
+
+```bash
+npx --yes upstream-radar@0.36.0 graph reverse ./plugin-reports \
+  --output ./reverse-dependency-index.json
+npx --yes upstream-radar@0.36.0 observe ./targets.yml \
+  --reverse-index ./reverse-dependency-index.json \
+  --state ./observations.json --report ./upstream-radar-observer.md
+```
+
+这一步不安装插件、不执行代码，也不调用模型；它只是把确定性的依赖图证据接到
+always-on 的上游变化任务上。索引结构见
+[`reverse-dependency-index.schema.json`](../schemas/reverse-dependency-index.schema.json)。
+
 可以从[可复制的真实 targets 示例](../examples/upstream-observer/targets.yml)开始。它默认观察公开的 DSH/飞书插件 `PlutoKeating/dsh-lark-bot`，不是模拟项目：
 
 ```yaml
@@ -332,7 +351,7 @@ Radar 会在三层目录内自动找到它；npm 名称和源码 manifest 不一
 想明确选择锁文件时再加 `--lockfile`：
 
 ```bash
-npx --yes upstream-radar@0.35.0 observe \
+npx --yes upstream-radar@0.36.0 observe \
   https://github.com/PlutoKeating/dsh-lark-bot \
   --state ./observations.json --report ./upstream-radar-observer.md
 ```
@@ -355,7 +374,7 @@ workspace 边保留为未解析证据；不会安装或启动 DSH。
 会额外指定 `--package`：
 
 ```bash
-npx --yes upstream-radar@0.35.0 observe \
+npx --yes upstream-radar@0.36.0 observe \
   https://github.com/PlutoKeating/dsh-lark-bot \
   --package dsh-feishu-bot \
   --lockfile pnpm-lock.yaml --lockfile-type pnpm \
@@ -633,7 +652,7 @@ cd my-dsh-plugin
 pnpm install --ignore-scripts
 
 # 把插件放进 DSH profile 前，先读取精确依赖图。
-pnpm dlx --package=upstream-radar@0.35.0 upstream-radar graph pnpm-lock pnpm-lock.yaml --json
+pnpm dlx --package=upstream-radar@0.36.0 upstream-radar graph pnpm-lock pnpm-lock.yaml --json
 ```
 
 这棵图会保留精确的 DSH 包版本，也会把未解析的可选 peer 明确显示出来；它不会加载生成的插件，也不会运行 lifecycle script。审查后，把下面这个完整 workflow 复制到 `.github/workflows/upstream-radar.yml`：
@@ -655,7 +674,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: MicroMilo/upstream-radar@v0.35.0
+      - uses: MicroMilo/upstream-radar@v0.36.0
         with:
           fail-on: high
           fail-on-compatibility: breaking
@@ -666,7 +685,7 @@ Action 会自动识别唯一的 `pnpm-lock.yaml`，检查同一棵精确依赖
 也可以直接检查一个真实发布的 DSH 包：
 
 ```bash
-npx --yes upstream-radar@0.35.0 inspect dsh-feishu-bot@0.15.8 --deep
+npx --yes upstream-radar@0.36.0 inspect dsh-feishu-bot@0.15.8 --deep
 ```
 
 这次检查的结论是 `REVIEW`：registry 完整性、签名、provenance 和 89 个已解析包都
@@ -679,7 +698,7 @@ npx --yes upstream-radar@0.35.0 inspect dsh-feishu-bot@0.15.8 --deep
 如果不想分别执行 `inspect`、打包和 `probe`，可以用一个命令完成一次 DSH 插件审查：
 
 ```bash
-pnpm dlx --package=upstream-radar@0.35.0 upstream-radar review dsh-plugin \
+pnpm dlx --package=upstream-radar@0.36.0 upstream-radar review dsh-plugin \
   dsh-cloudflare-browser-run@0.1.1 \
   --dsh-version 0.1.0-rc.6,0.1.0-rc.7
 ```
@@ -845,7 +864,7 @@ pnpm run try:dsh
 在把项目接入兼容性门禁前，可以先运行离线规则 benchmark：
 
 ```bash
-pnpm dlx --package=upstream-radar@0.35.0 upstream-radar benchmark compatibility
+pnpm dlx --package=upstream-radar@0.36.0 upstream-radar benchmark compatibility
 ```
 
 它覆盖六类契约：安全补丁、只需要项目分析的变化、不兼容的 DSH peer、发布者明确声明 breaking、候选传递依赖漏洞，以及候选依赖图不完整。这个命令不会联网、安装包、加载插件或启动 DSH；它验证的是 Radar 的确定性规则以及 `breaking`/`any` 门禁行为，不是运行时兼容性证明。
@@ -858,7 +877,7 @@ pnpm dlx --package=upstream-radar@0.35.0 upstream-radar benchmark compatibility
 # 打包精确版本，并明确不运行它的 lifecycle script。
 npm pack --ignore-scripts dsh-plugin@1.2.3
 
-pnpm dlx --package=upstream-radar@0.35.0 upstream-radar probe dsh-load \
+pnpm dlx --package=upstream-radar@0.36.0 upstream-radar probe dsh-load \
   ./dsh-plugin-1.2.3.tgz \
   --dsh-version 0.1.0-rc.6
 ```
@@ -884,7 +903,7 @@ pnpm run showcase:dsh-probe
 如果要比较多个 DSH 版本，可以使用矩阵入口：
 
 ```bash
-pnpm dlx --package=upstream-radar@0.35.0 upstream-radar probe dsh-matrix \
+pnpm dlx --package=upstream-radar@0.36.0 upstream-radar probe dsh-matrix \
   ./dsh-plugin-1.2.3.tgz \
   --dsh-version 0.1.0-rc.3 \
   --dsh-version 0.1.0-rc.6 \
@@ -902,7 +921,7 @@ JSON 结果结构见[矩阵结果 schema](../schemas/dsh-load-matrix.schema.json
 ```yaml
 steps:
   - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-  - uses: MicroMilo/upstream-radar@v0.35.0
+  - uses: MicroMilo/upstream-radar@v0.36.0
     with:
       fail-on: high
       # 可选：把确定性的 DSH/插件兼容性破坏也作为 CI 失败条件
@@ -911,12 +930,12 @@ steps:
       threat-intel: true
 ```
 
-这个 Action 只是 `radar check --frozen --state :memory: --fail-on high --fail-on-compatibility breaking --json` 的薄封装。`--frozen` 是有意的：它只使用配置文件里的依赖图，不会尝试读取 runner 上不存在的本地 DSH profile。`threat-intel` 默认是 `false`，这样普通 CI 门禁不会因为额外查询变重；设置为 `true` 后，Job Summary 和原始 JSON 会包含 CISA KEV 与 FIRST EPSS 的优先级证据。每次运行彼此独立；发现达到阈值的漏洞或选择的兼容性变化时返回 `2`，运行或漏洞源出错时返回 `1`。`breaking` 只拦截有 confirmed/strong 信号的兼容性事件，`any` 会拦截所有活动兼容性事件，默认值是 `never`。除了原始 JSON 日志，Action 还会把经过转义的简短摘要写入 GitHub Job Summary，定时任务失败时可以直接看到受影响的包、准确依赖路径、已经发布的修复版本（如果有）、一行优先级证据和建议的下一步。这个入口不会投递 DSH Agent 任务，也不会修改分支；需要持续监控和项目级分析时，仍使用原生 DSH bundle。建议把 Action 固定到类似 `v0.35.0` 的发布标签，并根据团队策略固定 checkout Action。
+这个 Action 只是 `radar check --frozen --state :memory: --fail-on high --fail-on-compatibility breaking --json` 的薄封装。`--frozen` 是有意的：它只使用配置文件里的依赖图，不会尝试读取 runner 上不存在的本地 DSH profile。`threat-intel` 默认是 `false`，这样普通 CI 门禁不会因为额外查询变重；设置为 `true` 后，Job Summary 和原始 JSON 会包含 CISA KEV 与 FIRST EPSS 的优先级证据。每次运行彼此独立；发现达到阈值的漏洞或选择的兼容性变化时返回 `2`，运行或漏洞源出错时返回 `1`。`breaking` 只拦截有 confirmed/strong 信号的兼容性事件，`any` 会拦截所有活动兼容性事件，默认值是 `never`。除了原始 JSON 日志，Action 还会把经过转义的简短摘要写入 GitHub Job Summary，定时任务失败时可以直接看到受影响的包、准确依赖路径、已经发布的修复版本（如果有）、一行优先级证据和建议的下一步。这个入口不会投递 DSH Agent 任务，也不会修改分支；需要持续监控和项目级分析时，仍使用原生 DSH bundle。建议把 Action 固定到类似 `v0.36.0` 的发布标签，并根据团队策略固定 checkout Action。
 
 如果仓库还没有提交 Radar 配置，最短接入方式是省略 `config`、`pnpm-lock` 和 `npm-lock`。checkout 之后，Action 会自动使用唯一存在的 `pnpm-lock.yaml` 或 `package-lock.json`，生成临时的审查清单，再执行同一个 frozen 检查：
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.35.0
+- uses: MicroMilo/upstream-radar@v0.36.0
   with:
     fail-on: high
 ```
@@ -926,7 +945,7 @@ steps:
 如果要在插件进入 DSH 前审查精确发布物，可以增加 `inspect-package`：
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.35.0
+- uses: MicroMilo/upstream-radar@v0.36.0
   with:
     inspect-package: dsh-cloudflare-browser-run@0.1.1
     # review 是安全默认值；只有允许覆盖不完整时才使用 block
@@ -938,7 +957,7 @@ steps:
 如果仓库只有 pnpm 锁文件，还没有提交 Radar 配置，可以让 Action 在同一个 job 中生成配置；可直接复制[pnpm workflow 示例](../examples/github-actions/upstream-radar-pnpm.yml)：
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.35.0
+- uses: MicroMilo/upstream-radar@v0.36.0
   with:
     pnpm-lock: pnpm-lock.yaml
     fail-on: high
@@ -952,7 +971,7 @@ npm 项目可以改用 `npm-lock: package-lock.json`；`pnpm-lock` 和 `npm-lock
 调用方需要先 checkout 仓库。这个 Action 不会安装项目依赖，也不会执行项目的 lifecycle script；它只读取提交到仓库的依赖图并查询配置中的上游漏洞源。如果需要完全显式的底层命令，等价写法是：
 
 ```bash
-pnpm dlx --package=upstream-radar@0.35.0 upstream-radar radar check \
+pnpm dlx --package=upstream-radar@0.36.0 upstream-radar radar check \
   ./upstream-radar.config.json --frozen --state :memory: --fail-on high \
   --fail-on-compatibility breaking --json
 ```
@@ -960,7 +979,7 @@ pnpm dlx --package=upstream-radar@0.35.0 upstream-radar radar check \
 如果还要检查一个已发布插件能否跨多个 DSH 版本加载，可以增加三个 input：
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.35.0
+- uses: MicroMilo/upstream-radar@v0.36.0
   id: radar
   with:
     config: upstream-radar.config.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "upstream-radar",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Always-on dependency security monitoring for DeepSeek Harness (DSH) plugins: find exact installed or candidate transitive vulnerable paths and breaking updates, then route evidence to a DSH Agent.",
   "type": "module",
   "license": "Apache-2.0",

package/schemas/reverse-dependency-index.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/MicroMilo/upstream-radar/blob/main/schemas/reverse-dependency-index.schema.json",
+  "title": "Upstream Radar reverse dependency index",
+  "description": "A deterministic index from exact npm dependency coordinates to downstream plugin graphs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "generatedAt", "observations", "inputs", "coverage", "plugins", "dependencies"],
+  "properties": {
+    "schema": { "const": "upstream-radar.reverse-dependency-index/v1alpha1" },
+    "generatedAt": { "type": "string", "minLength": 1, "maxLength": 128, "format": "date-time" },
+    "observations": { "type": "integer", "minimum": 0 },
+    "inputs": { "$ref": "#/$defs/inputs" },
+    "coverage": { "$ref": "#/$defs/coverage" },
+    "plugins": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/plugin" }
+    },
+    "dependencies": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/dependency" }
+    }
+  },
+  "$defs": {
+    "coordinate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ecosystem", "name", "version"],
+      "properties": {
+        "ecosystem": { "const": "npm" },
+        "name": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "version": { "type": "string", "minLength": 1, "maxLength": 512 }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "name": { "type": "string", "minLength": 1, "maxLength": 512 }
+      }
+    },
+    "path": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodes", "kinds"],
+      "properties": {
+        "nodes": { "type": "array", "minItems": 2, "items": { "type": "string", "minLength": 1, "maxLength": 1024 } },
+        "kinds": {
+          "type": "array",
+          "items": { "enum": ["runtime", "development", "optional", "peer", "host-runtime"] }
+        }
+      }
+    },
+    "use": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pluginId", "plugin", "sources", "coverage", "paths"],
+      "properties": {
+        "pluginId": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "plugin": { "$ref": "#/$defs/coordinate" },
+        "project": { "$ref": "#/$defs/project" },
+        "sources": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 } },
+        "coverage": { "enum": ["complete", "incomplete"] },
+        "paths": { "type": "array", "items": { "$ref": "#/$defs/path" } }
+      }
+    },
+    "dependency": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dependency", "dependents"],
+      "properties": {
+        "dependency": { "$ref": "#/$defs/coordinate" },
+        "dependents": { "type": "array", "items": { "$ref": "#/$defs/use" } }
+      }
+    },
+    "pluginObservation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "coverage", "unresolved"],
+      "properties": {
+        "source": { "type": "string", "minLength": 1, "maxLength": 4096 },
+        "graphDigest": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "coverage": { "enum": ["complete", "incomplete"] },
+        "unresolved": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "plugin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "plugin", "observations"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "plugin": { "$ref": "#/$defs/coordinate" },
+        "project": { "$ref": "#/$defs/project" },
+        "observations": { "type": "array", "items": { "$ref": "#/$defs/pluginObservation" } }
+      }
+    },
+    "inputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["files", "loadedFiles", "skipped"],
+      "properties": {
+        "files": { "type": "integer", "minimum": 0 },
+        "loadedFiles": { "type": "integer", "minimum": 0 },
+        "skipped": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["source", "reason"],
+            "properties": {
+              "source": { "type": "string", "minLength": 1, "maxLength": 4096 },
+              "reason": { "type": "string", "minLength": 1, "maxLength": 2048 }
+            }
+          }
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["completeObservations", "incompleteObservations", "unresolvedEdges"],
+      "properties": {
+        "completeObservations": { "type": "integer", "minimum": 0 },
+        "incompleteObservations": { "type": "integer", "minimum": 0 },
+        "unresolvedEdges": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}