安全扫描数据接口
全量插件安全审查数据的机器可读接口——全量快照、单插件 JSON、扫描状态等级、版本绑定规则。全部为静态、缓存、可免费引用的数据。
| URL | 说明 | 更新 |
|---|---|---|
/data/security-scan.json | 全量快照——所有插件的扫描结果（verdict、counts、类别、hash、版本） | 每日 01:10 北京时间（17:10 UTC） |
/data/security-scan.schema.json | 快照对应的 JSON Schema——供第三方校验数据契约 | 随字段新增更新 |
/artifact/<id>.json | 单插件 JSON——派生扫描状态 + 扫描记录 + 版本信息 | 每日 01:10 北京时间（17:10 UTC） |
JSON 接口支持跨域读取：Access-Control-Allow-Origin: *，无需 API Key 或注册。
由扫描 verdict 通过 deriveBadgeState（src/scripts/badge-state.ts）派生。判定顺序：outdated → critical → medium → warning → stale → passed。
| 等级 | 条件 | 含义 |
|---|---|---|
critical | verdict = fail | 阻断级严重发现（密钥 / 网络外传 / 破坏性 / 挖矿） |
medium | verdict = warn && critical > 0 | 非阻断严重发现（动态执行 / shell / 安装脚本 / 混淆）——展示为需注意 |
warning | verdict = warn && critical = 0 | 仅警告级发现 |
passed | verdict = pass | 无严重/警告发现（允许 info） |
outdated | scan.commitSha ≠ plugin.latestCommitSha && scannedAt 超过 7 天 | 仓库有新提交且扫描已超过 7 天，结果不再代表当前代码 |
stale | passed && scannedAt 超过 30 天 | 上次通过扫描已超过 30 天 |
unscanned | 无扫描记录 | 未扫描（新插件或扫描失败） |
/data/security-scan.json 是带快照外层结构的单个 JSON 对象，不是裸的插件 id 映射。消费者应忽略未知外层字段。
| 字段 | 类型 | 语义 |
|---|---|---|
generated | string (YYYY-MM-DD) | 由 generatedAt 派生的快照日期 |
generatedAt | string (ISO 8601) | 流水线生成快照时持久化写入的时间；不使用网页构建时间 |
source | string | 快照对应的人工插件注册表页面 |
schema | string | 校验每条扫描记录的 schema 绝对地址 |
update | string | 当前流水线更新频率与执行方 |
license | object | 数据来源与复用条款（需注明来源） |
count | integer | scans 中插件 id 数量 |
scans | object | 插件 id 到扫描记录的映射；键与 plugins.json 的 id 一致 |
| 字段 | 类型 | 语义 |
|---|---|---|
verdict | pass|warn|fail | 扫描结论（见等级表） |
counts | object | 各级发现数量：critical / warning / info |
criticalByCategory | object | 严重发现按类别分组（shell、code-exec、secrets、network、destructive、obfuscation、install、mining） |
filesScanned | integer | 扫描的源文件数（上限 15） |
scannedAt | string (ISO) | 扫描时间 |
commitSha | string | null | 扫描时的 HEAD commit SHA——结果仅对该版本有效 |
pkgVersion | string | null | 插件自身版本（从 package.json 提取） |
pkgDsh | boolean | 是否声明 dsh 清单（package.json 的 dsh 字段） |
latestCommitSha | string | null | 注册表记录的最新 HEAD（update-plugins 更新，用于 outdated 判定） |
latestReleaseTag | string | null | 最新 GitHub release tag（插件发布版本） |
latestCommitSha 和 latestReleaseTag 是 plugins.json 中的插件级元数据，为方便使用也在单插件 JSON 中暴露；流水线回填期间可能为 null。
扫描结果仅对扫描时的 commitSha 版本有效。扫描后 7 天内的新提交不会触发 outdated（评级仍然有效）；若仓库持续有新提交且扫描已超过 7 天，状态才降级为 outdated，直到每日流水线重新扫描——防止「认证后投毒」。
获取全量快照或单插件数据：
安全扫描数据由 dsh.so 流水线从公开 GitHub 仓库聚合：增量发现每 2 小时一次（北京时间偶数小时 02:00-22:00），手动投稿在北京时间奇数小时 03:00-23:00 处理，全量刷新每日北京时间 00:00，安全扫描每日北京时间 01:10。字段只增不删：既有字段不会移除或改名，新增字段会同步更新 schema。快照和 schema 可免费引用，需注明来源 dsh.so；新增字段见 更新日志。