DSH Security Assurance
DeepSeek Harness 的策略驱动仓库安全评估插件 · 中文默认，English below
安全评估主视觉
中文
这是什么
dsh-security-assurance 为 DeepSeek Harness 提供证据驱动的仓库安全评估。它通过公开的 Harness/Cordis 接口接入，不修改 Harness Core，并把评估过程封装为可查询、可恢复、可审计的版本化结果。
这是一个安全保障插件，不是通用漏洞扫描器。当前内建能力包括 Node 项目的 package.json 安装生命周期检查、npm 发布面、pnpm 锁文件完整性、GitHub Actions 权限与不可变依赖检查，以及对冻结 npm-audit.json 和 Gitleaks v8 JSON 报告的纯归一化与独立验证。
一次扫描发现不等于可审计的安全结论：输入可能被篡改、截断，或与冻结仓库不一致。Security Assurance 只接收冻结 Subject 上的已验证 slice，并在独立验证和 sealed submission 后给出 verdict。
评估如何形成可信结论
Security Assurance 从授权 Catalog 选择、Subject Freeze、PURE 分析和独立验证到 Verdict 与 sealed submission 的证据流
Service 先解析授权 Catalog 选择并冻结完整 Subject，再把已验证 slice 交给合格的 PURE Analyzer 或报告归一化器。Candidate 和 Coverage 必须经过独立复核，Kernel 才能计算 SATISFIED、FAILED 或 INDETERMINATE，并为终态 Assessment 生成摘要绑定的 Submission。
当前版本
- 版本：
0.1.0-rc.14
- 状态：Release Candidate（预发布版）
- 适配：DeepSeek Harness
0.1.2-alpha.1（主目标）；0.1.2-alpha.2 至 0.1.2-rc.1、0.1.3-alpha.1、0.1.3-alpha.2、0.1.5-alpha.1、0.1.5-alpha.2、0.1.5-rc.1 与 0.1.5-rc.2 经兼容矩阵验证
- GitHub：v0.1.0-rc.14 Release
支持范围
| 项目 | 当前状态 |
|---|
| 评估模式 | REPOSITORY、精确提交或 Mission 产出工作区的 CHANGE，以及默认策略的 TARGETED |
| 支持 Subject | git_revision、workspace_snapshot、change（精确 base/head）；Control Plane 可使用 Host 专用 workspace_change |
CHANGE 模式 | 支持精确已提交的 base→head，以及 Control Plane 冻结的 baseline→produced workspace；均扫描完整结果树 |
TARGETED 模式 | 内建 Node 生命周期与 GitHub Actions 策略支持 git_revision、workspace_snapshot 的明确相对文件/目录；只读取目标内的相关清单或 workflow |
| 默认策略 | security/node-package-lifecycle |
| 可选 npm audit 策略 | security/npm-dependency-audit |
| 可选 Gitleaks 策略 | security/secret-leak-audit |
| 可选 GitHub Actions 策略 | security/github-actions-supply-chain |
| 可选 npm 发布面策略 | security/npm-publish-surface |
| 可选 pnpm 锁文件策略 | security/pnpm-lockfile-integrity |
| 默认档案 | security/standard |
| Harness 版本 | 0.1.2-alpha.1（主）、0.1.2-alpha.2、0.1.2-alpha.3、0.1.2-alpha.4、0.1.2-alpha.5、0.1.2-rc.1、0.1.3-alpha.1、0.1.3-alpha.2、0.1.5-alpha.1、0.1.5-alpha.2、0.1.5-rc.1、0.1.5-rc.2 |
| Node.js | ^22.19.0 || >=24.0.0（CI 覆盖 22 与 24） |
| 支持平台 | Windows、Linux、macOS |
评估会先读取当前 Host 注册的 Repository 和 Catalog；只有 Service 返回的精确 ID、模式、Subject、Target、Profile 和强化控制才能用于启动，不允许模型猜测路径或标识符。
TARGETED 仍会冻结并摘要绑定完整 Subject，但只把明确目标内、经过验证的相关 slice 交给内建分析器：Node 生命周期策略读取 package.json，GitHub Actions 策略读取 .github/workflows/*.yml|yaml。每个目标必须对应一个现有条目或目录前缀；不存在的目标会在创建 Assessment 前被拒绝。npm 发布面、npm audit、Gitleaks 与 pnpm 锁文件策略暂不声明 TARGETED 支持，因为它们的根部或外部输入目前不能独立证明与目标完全一致。
Harness 支持窗口是一个显式的已验证集合：每日 Harness Compatibility 工作流自动发现官方仓库标签，对主目标在 Ubuntu、macOS、Windows 上、对其余版本在 Ubuntu 上执行双插件联合 E2E（Mission → Developer 工作区变更 → CHANGE Assessment → sealed submission → Quality Gate）和打包 fresh Profile 安装加 Web 探针。新标签会自动进入验证，但未通过矩阵验证前不会被声明支持（ADR 0310）。
独立工具与 Workbench 的 Catalog 契约保持不变，只向模型提供精确提交 change。当 Control Plane 完成 Developer 与 Implementation Evidence 后，Provider 会从不可伪造的执行上下文接收 Host 专用 workspace_change，同时核对分支、baseline HEAD、Git 状态指纹、逐字节产出变更指纹与完整结果树；任何漂移都会在创建 Assessment 前 fail closed。
3 分钟最短安装（Harness Web）
兼容 DeepSeek Harness 0.1.2-alpha.1 至 0.1.2-rc.1、0.1.3-alpha.1、0.1.3-alpha.2、0.1.5-alpha.1、0.1.5-alpha.2、0.1.5-rc.1 与 0.1.5-rc.2（显式已验证集合，见上方支持范围），要求 Node.js ^22.19.0 || >=24.0.0 和 Harness CLI。将终端当前目录设为要评估的 Git 仓库，然后直接安装 GitHub Release 中已经构建的包：
- 下载对应 Release 的 tarball。
- 在目标仓库目录安装插件并检查最终组合。
- 启动 Harness Web，然后运行一个明确的
/security 评估。
dsh plugin --profile web add https://github.com/bailong-Hakuryu/dsh-security-assurance/releases/download/v0.1.0-rc.14/dsh-security-assurance-0.1.0-rc.14.tgz
dsh --profile web --dump-config
dsh web
也可以先在 Release 页面下载 dsh-security-assurance-0.1.0-rc.14.tgz，再把上面 URL 换成本地文件的绝对路径。
如果还要使用工程 Mission 门禁，请先安装 Engineering Control Plane，再安装本插件：
dsh plugin --profile web add D:\Downloads\dsh-engineering-control-plane-0.1.13.tgz
dsh plugin --profile web add https://github.com/bailong-Hakuryu/dsh-security-assurance/releases/download/v0.1.0-rc.14/dsh-security-assurance-0.1.0-rc.14.tgz
dsh --profile web --dump-config
dsh web
插件会把启动时的工作目录注册为 current-workspace。启动后建议先用 dsh --profile web --dump-config 检查组合；如果端口已被占用，请在 Harness Profile 中选择其他空闲端口。
用户如何调用
插件同时支持被动路由和主动指令：
被动调用（推荐）：直接描述目标，模型会先获取可用仓库和评估目录，再按服务返回的选择启动评估。
请对当前仓库进行安全评估，并报告最终 Verdict 和 Findings。
检查当前项目的 package.json 安装生命周期配置。
主动调用：在 Harness Web 或 CLI 输入：
/security 评估当前仓库
/security 检查当前仓库的包安装生命周期
/security 只检查 packages/api 和 packages/web 的包安装生命周期
npm audit 报告适配
npm audit 由 Host、CI 或操作者在评估外部执行；插件不会在 PURE 分析边界内启动 npm、访问 Registry 或读取实时网络状态。先生成 UTF-8 报告，并确保它在评估启动前包含于所选 Subject：
npm audit --json | Set-Content -Encoding utf8 npm-audit.json
将 Repository 的策略绑定设为 security/npm-dependency-audit。适配器会按冻结字节和摘要读取 npm-audit.json：干净且完整的报告得到 SATISFIED；经独立契约复核的漏洞得到阻塞 Finding 和 FAILED；报告缺失、格式不受支持、Coverage 不完整或 Evidence 被篡改时得到 INDETERMINATE。报告新鲜度仍由生成报告的 Host/CI 负责。
Gitleaks 报告适配
Gitleaks 同样由 Host、CI 或操作者在评估外部执行。推荐启用完全脱敏，并把 UTF-8 JSON 报告纳入评估 Subject：
gitleaks dir . --redact=100 --report-format=json --report-path=gitleaks-report.json
将 Repository 的策略绑定设为 security/secret-leak-audit。PURE 适配器只保留规则 ID、受影响相对路径和位置；Secret、Match、源代码行、秘密哈希、作者邮箱与提交消息不会进入 Candidate、Finding、Evidence、Seal 或导出。完整空报告得到 SATISFIED；独立复核的任意报告项得到 HIGH、阻塞 Finding 和 FAILED；缺失、无效、被篡改或不完整的报告得到 INDETERMINATE。扫描配置、报告新鲜度、Git 历史范围和 allowlist 正确性仍由 Host/CI 负责。
GitHub Actions 供应链策略
将 Repository 绑定到 security/github-actions-supply-chain 后，插件只读取冻结 Subject 中、当前 Target 选中的 .github/workflows/.yml 与 .yaml。PURE 分析器不会执行 workflow 或访问 GitHub；它要求顶层 permissions 显式为只读或空权限，拒绝 job 级写权限，并要求外部 Action/可复用 workflow 使用完整 40 位提交 SHA、container Action 使用 sha256 镜像摘要。本地 ./ Action 不会被误报。
完整解析会在独立验证契约中重新执行。安全或空的目标 workflow 集得到 SATISFIED；已验证违规得到阻塞 Finding 和 FAILED；重复键、alias、无效/不支持的 YAML 或被篡改的 Contribution 得到 INDETERMINATE。该严格策略不判断写权限是否“业务上合理”；确需写权限的发布 workflow 应使用另一份经过评审的 Policy，而不是在本策略里静默放行。
npm 发布面策略
将 Repository 绑定到 security/npm-publish-surface，即可离线验证冻结根部 package.json 的发布声明：公开包身份、公开访问、显式 files allowlist，以及 exports、main、types、bin 目标都必须被该 allowlist 包含。它不会运行 npm pack、枚举文件系统、访问 Registry，也不声称文件真实存在、包来源可信或依赖安全。
一致清单得到 SATISFIED；私有包、受限发布、缺少显式 allowlist、过宽模式或未被 allowlist 包含的入口得到经独立重导验证的阻塞 Finding 和 FAILED；格式错误、重复 JSON 键、非法入口或被篡改的 Contribution 得到 INDETERMINATE。v1 只支持 REPOSITORY 与 CHANGE，并且只证明清单自洽，不替代真实打包工件证明。
pnpm 锁文件完整性策略
将 Repository 绑定到 security/pnpm-lockfile-integrity，即可离线比较冻结 Subject 根部的 package.json 与 pnpm-lock.yaml。PURE Analyzer 要求 packageManager 精确固定到一个 pnpm 语义版本、pnpm v9 根 importer 与三类依赖声明逐项一致，并要求每个外部 package resolution 带有效 SRI。它不会运行 pnpm、安装依赖、访问 Registry 或声称依赖无漏洞。
一致输入得到 SATISFIED；缺失锁文件、清单漂移、未固定包管理器或缺失 SRI 得到经独立重导验证的阻塞 Finding 和 FAILED；重复 JSON 键、YAML 别名、格式错误、未知 lockfile 版本、非 pnpm 包管理器或被篡改的 Contribution 得到 INDETERMINATE。v1 只覆盖根 importer，并且只支持 REPOSITORY 与 CHANGE，不会把 workspace 子包冒充成已检查范围。
工具工作流
| 顺序 | 工具 | 作用 |
|---|
| 1 | security_repositories | 列出当前会话可见的已授权仓库 |
| 2 | security_catalog | 获取指定仓库支持的模式、Subject、Profile 和控制 |
| 3 | security_assessment_start | 用精确选择启动一次持久化评估 |
| 4 | security_assessment_status | 读取版本化状态、Coverage 和 Verdict |
| 5 | security_assessment_findings | 分页读取脱敏 Finding 摘要 |
| 6 | security_assessment_resume | 仅按服务公布的合法动作恢复阻塞评估 |
| 7 | security_assessment_cancel | 按精确 revision 取消并等待外部工作静默 |
| 8 | security_assessment_export | 请求固定格式、固定目标的官方导出 |
推荐顺序是 repositories → catalog → start → status → findings。变更操作使用服务返回的精确 revision 和新的 idempotency_key；旧请求不会被自动重放。
返回结果与安全边界
- 所有公共操作返回统一的
SecurityResult<T> envelope。
- 命令返回不可变、带版本的 Receipt；查询返回按身份和 revision 绑定的 Snapshot。
- Findings、Evidence 和导出内容遵循宿主授权、用途和脱敏规则。
- 模型参数不接受凭据、数据库句柄、绝对路径或可执行对象；身份和权限由 Host 当前会话解析。
- Registry、Assessment、Evidence 和导出状态保存在插件私有 SQLite 中，使用幂等键与 revision CAS 防止重复执行。
- 缺失授权、状态冲突、超时、取消或外部失败会 fail closed，不会伪造满足结论。
workspace_snapshot 只应对用户明确授权的仓库运行；祖先符号链接/联结会被拒绝，Subject 符号链接只登记不解引用，Git 通过 Harness 受管子进程边界执行。详见 SECURITY-REVIEW.md。
与 Engineering Control Plane 联用
两插件联用时，Control Plane 负责 Mission、工程 Evidence 和最终 Quality Gate；本插件只负责外部安全义务及其证据提交。安全评估失败或不确定会阻塞 Gate，但不会被转换成工程批准。
安装两者后，Control Plane 的可选 Provider 会按精确的 Provider ID、版本和 current-workspace 绑定本插件。两个插件不共享 SQLite、可写 Evidence 路径、事务或 Kernel 对象。
公开入口
| 入口 | 作用 |
|---|
dsh-security-assurance | 根 Security Assurance Service；同时导出内建 GitHub Actions、npm 发布面、pnpm 锁文件策略及 npm audit、Gitleaks 归一化契约 |
dsh-security-assurance/tools | 八个严格模型工具 |
dsh-security-assurance/contracts | 版本化公共契约 |
dsh-security-assurance/analyzer | 内建分析器接口 |
dsh-security-assurance/evaluation | 纯函数 Metrics Engine |
dsh-security-assurance/release-file-bindings | 发布文件绑定的版本化纯契约 |
dsh-security-assurance/release-proof | 精确候选证明记录与确定性索引纯契约 |
dsh-security-assurance/release-qualification | 资格草案、组装输入与最终输入的严格纯契约 |
dsh-security-assurance/release-promotion | RC → stable 行为等价交接收据纯契约（不授予发布权限） |
dsh-security-assurance/host-repository-provider | Host Repository 注册适配器 |
dsh-security-assurance/control-plane-provider | 可选 Control Plane 适配器 |
dsh-security-assurance/invariant | 启动就绪诊断 |
dsh-security-assurance/workbench-remote | 需要部署方认证解析器，默认禁用 |
常见排查
仓库列表为空：从目标 Git 仓库目录启动 Harness，并确认 Host Repository Provider 已加载；不要手工编造 Repository ID。
Catalog 显示 UNSUPPORTED：确认使用的是已授权仓库、security/standard Profile，以及 Catalog 为当前策略返回的模式。独立启动的 CHANGE 接受精确已提交的 base/head；未提交工作区只由 Control Plane 的 Host 专用 Subject 接入。TARGETED 支持 security/node-package-lifecycle 与 security/github-actions-supply-chain；npm 发布面、npm audit、Gitleaks 与 pnpm 锁文件策略仍显示 UNSUPPORTED。
端口冲突：关闭占用端口的旧 Harness 进程，或在 Web Profile 中改用空闲端口后重新启动。
评估为 BLOCKED：先读取 security_assessment_status 的 legalNextActions，只执行服务允许的 resume 或 cancel。
开发与验证
pnpm install
pnpm lint
pnpm build
pnpm typecheck
pnpm test
pnpm pack:dry-run
pnpm pack:profile-smoke
pnpm pack:browser-e2e
pnpm release:check
稳定版候选还必须先从真实 tarball、干净源码修订和锁文件生成确定性绑定，再用该绑定核验完整发布证据：
pnpm release:bind -- --input .\release-files.json --output .\release-file-bindings.json
pnpm release:collect -- --input .\release-proof-input.json --output .\release-proof-index.json
pnpm release:assemble -- --input .\release-qualification-draft.json --output .\release-qualification-input.json
pnpm release:qualify -- --input .\release-qualification-input.json --output .\release-qualification
pnpm release:handoff -- --input .\release-handoff-input.json --output .\release-promotion-handoff.json
第一条命令只记录已复核的文件事实，不制造测试或安全证明；packed smoke 可用 DSH_RELEASE_PROOF_OUTPUT 输出绑定同一 tarball 的严格证明记录，第二条命令验证并按规范顺序收集这些记录，逐字节摘要后生成 proof index；第三条命令重新读取 index、binding 与每份 proof record，把状态原样合并到 release:qualify 的严格输入；第四条命令再次读取绑定的真实文件，并且只在 Release Constitution 为 PROMOTE 且最终 Manifest 为 VERIFIED 时返回 0，原子生成 Manifest、公开 Scorecard 和资格结论三件套；第五条命令绑定这三件套与原 RC tarball，逐项比较拟发布 stable tarball，只允许同基线版本替换及 README/CHANGELOG 发布元数据变化，并输出明确写有 authorization: NOT_GRANTED 的交接收据。当前候选依照 ADR 0307 不发布旧 Workbench client，因此真实浏览器记录会诚实标记 WORKBENCH 为 INCONCLUSIVE，不会把通用 Web 外壳冒充成 Workbench。有效但阻断/不完整的证据返回 2 并保留可审计产物；字节摘要、Git HEAD、已跟踪源码、资格组合或包行为不一致时返回 1 且不生成对应产物。所有 CLI 都不会自动打 tag、签名、上传或发布包。完整输入契约见 v0.1 发布清单。
手动 Release Candidate Evidence workflow 会要求一个完整的 40 位 Control Plane commit SHA，只打包并绑定一次候选，然后让 Linux、macOS、Windows 下载同一组 tarball 生成三份平台证明；最终收集任务从候选包安装公开 CLI，生成可下载的 release-evidence-index。该 workflow 不执行资格提升、打 tag、创建 Release 或发布 npm。
当前开发树包含 88 个测试文件、470 个测试，并由发布门禁统一执行静态检查、类型检查、构建、打包和 Harness Profile smoke。公开 CI 在 Ubuntu、macOS 和 Windows 上从两个 tarball 重建 fresh Profile 并执行 Web 探针；每日兼容矩阵另对全部已声明 Harness 版本执行双插件联合 E2E 与打包安装探针。
完整领域模型见 CONTEXT.md，安全政策见 SECURITY.md，候选版审查见 SECURITY-REVIEW.md。
English
What it is
dsh-security-assurance is an evidence-backed repository security assessment plugin for DeepSeek Harness. It integrates through public Harness and Cordis seams without modifying Harness Core, and exposes versioned, queryable, recoverable assessment results.
This is an assurance plugin, not a general vulnerability scanner. Built-in capabilities include the Node package.json install-lifecycle check, npm publish surface, pnpm lockfile integrity, GitHub Actions permission and immutable-dependency checks, and pure normalization plus independent validation of frozen npm-audit.json and Gitleaks v8 JSON reports.
A scan finding is not automatically an auditable security conclusion: input may be tampered with, truncated, or detached from the frozen repository. Security Assurance accepts only verified slices from a frozen Subject, then emits a verdict after independent validation and sealed submission.
Assessment at a glance
Security Assurance evidence flow from an authorized Catalog choice and immutable Subject through PURE analysis, independent validation, Coverage, Verdict, and sealed submission
The Service resolves an authorized Catalog selection and freezes the complete Subject before exposing verified slices to qualified PURE Analyzers or report normalizers. Candidates and Coverage are independently re-derived before the Kernel can compute SATISFIED, FAILED, or INDETERMINATE and emit a digest-bound Submission for a sealed Assessment.
Current release
- Version:
0.1.0-rc.14
- Status: release candidate
- Target Harness:
0.1.2-alpha.1 (primary); 0.1.2-alpha.2 through 0.1.2-rc.1, 0.1.3-alpha.1, 0.1.3-alpha.2, 0.1.5-alpha.1, 0.1.5-alpha.2, 0.1.5-rc.1, and 0.1.5-rc.2 verified by the compatibility matrix
- Release: v0.1.0-rc.14
Support matrix
License
MIT
