dsh-code-security 0.3.8 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.4.1 (2026-10-15)
+
+- 修复同一行同时命中高熵密钥和其他安全规则时，其他规则的证据仍带出原始字符串的问题；所有证据统一使用同一套高熵脱敏判断，也覆盖截断的字符串。
+- 回归检查模型返回值、历史、已接受基线、SARIF 与 Markdown，保留原始证据指纹用于跟踪。
+
+## 0.4.0 (2026-10-15)
+
+- 增加 DSH 中英文设置工作台：项目选择、扫描/增量/复查、覆盖情况、问题筛选、脱敏证据、复制位置与报告下载。
+- 可选接入 Betterleaks 1.9.0、Semgrep CE 1.181.0 和 OSV-Scanner 2.7.0。扫描使用隔离快照，不执行项目安装/构建脚本；密钥在线验证关闭，OSV 联网查询需要明确选择。
+- 增加自有 MIT 数据流规则和可靠的 DOMPurify 绑定判断，区分模式提示与数据流证据。增强差异扫描读取暂存区/工作树实际内容，仅报告涉及新增行的问题。
+- 统一脱敏输出、历史、基线和导出，迁移旧记录时保留稳定指纹。修复 PEP 621 等 Python 依赖解析，错误/动态声明不再被当成空的安全清单。
+- 可按项目开启每轮结束后的安静增量检查，包含未跟踪文件、取消过期任务，仅为后续对话提供新增高风险提示；手动结果独立保存。
+- 复查保留上次范围与引擎，检查不完整时不判定关闭；成功复查更新当前报告。增加 Windows/Linux、Node 22/24 与固定原生引擎的 CI 检查。
+
 ## 0.3.8 (2026-10-12)
 
 - 修复增量扫描遗漏中文/转义文件名、私钥、`.env` 敏感项和禁用依赖审计配置的问题，报告真实证据行号。

package/README.en.md

@@ -13,8 +13,9 @@ Feedback and contributions are welcome: report [issues](https://github.com/STARD
 ## What it does
 
 - Scan files, directories or Git diffs with locations and code evidence.
-- Recheck fixes and manage baselines or scan policy.
-- Export Markdown or SARIF reports and inspect dependency manifests.
+- Inspect new findings, coverage and redacted evidence in DSH Settings, then recheck fixes.
+- Optionally use Betterleaks for secrets, Semgrep CE for data flow and OSV for dependency advisories.
+- Export Markdown/SARIF, maintain baselines, and opt into quiet per-project change checks.
 
 ## Install
 
@@ -28,11 +29,11 @@ For the web version, replace `desktop` with `web`. Restart DSH after installatio
 
 ## Start using it
 
-Ask: “Review the current Git diff for security findings, show evidence and recheck the fixes.”
+Ask: “Review the current Git diff for security findings, show evidence and recheck the fixes.” Then open **Settings → Code security** to view the project and results.
 
 ## Requirements and configuration
 
-Deterministic rules run locally. See the usage guide for rule coverage, baselines and policy configuration.
+Built-in rules run locally by default. Optional programs are installed by the user; basic checks work without them. Online dependency audits require an explicit mode choice, and automatic checks are off by default. Complete detected credentials are redacted before return, persistence and export.
 
 Detailed configuration, tool arguments and troubleshooting are in the [usage guide](docs/USAGE.en.md). For standalone development, follow the Node requirement in [package.json](package.json).
 

package/README.md

@@ -13,8 +13,9 @@
 ## 功能
 
 - 扫描文件、目录或 Git diff，报告规则、位置与代码证据。
-- 复扫修复结果，维护问题基线和检查策略。
-- 导出 Markdown / SARIF 报告，检查依赖清单。
+- 在 DSH 设置中查看新增问题、检查覆盖、脱敏证据，并复查修复结果。
+- 可选 Betterleaks 密钥检测、Semgrep CE 数据流规则、OSV 依赖漏洞审计。
+- 导出 Markdown / SARIF，维护基线；可按项目开启安静的自动改动检查。
 
 ## 安装
 
@@ -28,11 +29,11 @@ dsh plugin --profile desktop add dsh-code-security
 
 ## 开始使用
 
-安装后可说：“审查当前 Git 改动的安全问题，给出位置和证据，再复查修复结果。”
+安装后可说：“审查当前 Git 改动的安全问题，给出位置和证据，再复查修复结果。”之后可在「设置 → 代码安全」查看项目与检查结果。
 
 ## 依赖与配置
 
-默认在本机执行确定性规则检查。规则覆盖与基线、策略配置见使用说明。
+默认仅运行本地内置规则。增强程序由用户自行安装，未安装也可使用基础检查。联网依赖审计需明确选择；自动检查默认关闭。完整检测到的密钥会在返回、保存和导出前脱敏。
 
 详细配置、工具参数与排错见[使用说明](docs/USAGE.md)。从源码独立开发时，Node 要求以 [package.json](package.json) 为准。
 

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Third-party components
+
+The plugin and the original rules in rules/semgrep.yml are MIT licensed.
+
+Runtime dependencies are installed as separate npm packages and retain their own notices:
+
+| Component | Purpose | License |
+| :-- | :-- | :-- |
+| @babel/parser, @babel/traverse, @babel/types 7.29.x | Parse JavaScript/TypeScript and verify sanitizer bindings | MIT |
+| smol-toml 1.9.1 | Parse Python/Rust TOML manifests | BSD-3-Clause |
+| proper-lockfile 4.1.2 | Serialize state and workspace-index updates | MIT |
+
+Optional scanner executables are not bundled, copied, downloaded or installed by the plugin. The operator installs them separately:
+
+| Program tested | Upstream license |
+| :-- | :-- |
+| [Betterleaks 1.9.0](https://github.com/betterleaks/betterleaks/tree/v1.9.0) | MIT |
+| [OSV-Scanner 2.7.0](https://github.com/google/osv-scanner/tree/v2.7.0) | Apache-2.0 |
+| [Semgrep CE 1.181.0](https://github.com/semgrep/semgrep) | LGPL-2.1 for the CE engine; other components may have separate notices |
+
+Semgrep-maintained registry rules have separate terms. This plugin does not bundle or automatically load those rules. Its four original taint rules are supplied under the plugin's MIT license. See [Semgrep licensing](https://docs.semgrep.dev/licensing).
+
+The CI-only installer downloads checksum-pinned public scanner releases and installs Semgrep in an ephemeral virtual environment. These test programs are not included in the npm artifact. fflate (MIT) is a development dependency used only to create a synthetic offline advisory fixture.

package/docs/USAGE.en.md

@@ -1,37 +1,94 @@
-# dsh-code-security usage guide
+# Code security guide
 
 [Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
 
-## Current improvements
+## Start with a change
 
-Relative stateDir defaults to .code-security in the session workspace. Concurrent scans retain both histories. Damaged records must be inspected after backup rather than silently recreated. Scans skip symlinks and junctions; static rules do not replace a full security audit.
+Ask in a project chat: “Check the current changes for security issues, show evidence, and recheck the repairs.” Or open **Settings → Code security**, select the project and choose **Scan code** or **Check changes**.
 
-0.3.8 (2026-10-12): incremental reviews decode Git's quoted paths and check added private keys, `.env` secrets and disabled audit settings. Three context lines on each side support existing next-line suppressions and multiline settings; only evidence intersecting added lines is reported. Multiline locations point to the match's first line. Staged reviews use index content rather than later working-tree edits.
+Projects come from host sessions or completed security tools; the browser cannot submit arbitrary filesystem roots. If a project is missing, run a check in its chat and refresh the list. Jobs continue when the panel is closed. Cancellation waits for the scanner and preserves the previous report.
 
-Full, directly selected file and incremental scans share default and policy exclusions. Paths and Git scope are relative to the session workspace, including nested workspaces. `filesScanned` counts reviewed files and `filesSkipped` includes exclusions; incremental results also provide `filesChanged` and reviewed `addedLines`. Git output uses fixed colors/prefixes and disables external diff/textconv helpers. Invalid `base`/`staged` arguments and malformed or incomplete hunks fail without replacing scan state.
+Findings show severity, confidence, rule, location, source engines and redacted evidence. Filter new/high-risk findings, copy locations, download SARIF/Markdown, or open a file while its corresponding project chat is active.
 
-Saved evidence with a legacy `./` path prefix still matches baselines. File-level findings now use actual matching snippets; older baselines that saved the beginning of an entire file may require a fresh scan and human review before acceptance.
+## Optional engines
+
+| Engine | Coverage | Default |
+| :-- | :-- | :-- |
+| Built-in rules | 40+ injection, deserialization, crypto, secrets, configuration and path/network patterns | Enabled; local |
+| Betterleaks 1.9.0 | Platform-specific and generic secret patterns | Optional; live credential validation disabled |
+| Semgrep CE 1.181.0 | Original JS/TS command, HTML and SQL taint rules; Python command taint | Optional; local; metrics/version checks disabled |
+| OSV-Scanner 2.7.0 | Resolved dependency versions and known advisories | Chosen separately in dependency checks |
+
+Install optional programs yourself, then set their executable paths or add them to PATH. Save settings and click **Check tools**. Engine settings apply to the current DSH profile; automatic checks are enabled per project. The plugin never installs scanners automatically.
+
+A selected engine that is missing, fails, times out or returns incomplete output cannot produce a pass. No eligible files is explicitly shown as not run. Findings at the same location with the same CWE are merged while retaining source engines.
+
+Built-in HTML findings are low-confidence sink patterns. Only a verified lexical dompurify import and a default sanitize call suppress them. Shadowed parameters, changed methods, custom configuration or parse failure are not silently treated as safe. Semgrep CE provides single-file data-flow evidence, not cross-file analysis or proof of exploitability.
+
+## Dependency modes
+
+- **Inventory (offline)** parses npm, PEP 621, Poetry, Python dependency groups, Cargo, Go and other declarations. Parse errors and dynamic declarations are explicit. Version-risk flags are not a CVE audit.
+- **Local database** uses OSV's fully offline mode. Missing databases and malformed lockfiles are incomplete checks.
+- **Online** explicitly permits querying OSV with package names, resolved versions and dependency metadata. Source code is not uploaded. No package manager, install script or project build is run.
+
+Use package-lock.json, pnpm-lock.yaml, uv.lock or another supported resolved lockfile. A declared version range cannot stand in for an installed version. Local-source packages are not counted as checked against public advisories. Advisory IDs and upstream fixed versions are returned; compatibility still needs testing.
+
+The current OSV 2.7.0 implementation uses `cache/osv-scalibr/npm/all.zip` (PyPI for Python). Enter **cache** in the panel. Download the ecosystem archive from OSV's official export bucket, or use OSV's own database download command beforehand. The 2.7.0 implementation/Windows test differs from its older documentation that still names osv-scanner. Custom cache paths are forwarded using both old and new environment-variable names; 2.7.0 is the version tested here.
+
+Health shows cache file modification times, not advisory freshness guarantees. See the [offline guide](https://google.github.io/osv-scanner/usage/offline-mode/) and [current cache implementation](https://github.com/google/osv-scalibr/blob/5be78a00e3c2/enricher/vulnmatch/osvlocal/matcher.go).
+
+## Quiet automatic checks
+
+Disabled by default. Enable **Check changes after each turn** in the project's enhanced settings:
+
+1. After a main-session turn, debounce for about 1.8 seconds; cancel when a new turn starts.
+2. Run only local built-in rules over Git changes and untracked files.
+3. Supply new, unaccepted high-risk patterns as untrusted evidence for a later conversation reminder. No popup, new model turn, automatic edit or baseline acceptance.
+4. Save automatic results separately, preserving manual enhanced scans and rechecks. Non-Git projects and failures are shown as incomplete.
+
+This is not scheduled monitoring and does not run after DSH exits.
 
 ## Tools
 
-| Tool | Purpose | Write |
+| Tool | Main arguments and purpose | Writes |
 | :-- | :-- | :-- |
-| `secure_scan` | Scan files with CWE/severity/line/snippet evidence | state |
-| `secure_diff` | Review only added lines of git diff | state |
-| `secure_fix_verify` | Compare with baseline: closed / remaining / fresh | state |
-| `secure_report` | Aggregate by rule/file with gate verdict | no |
-| `secure_export` | Export SARIF 2.1.0 / Markdown | file write approval |
-| `secure_baseline` | Accept current findings as baseline; gate on new issues only | approval |
-| `secure_deps` | SBOM-lite: parse dependency manifests and version-risk flags | no |
-| `secure_policy_show` | Show .code-security.json | no |
-| `secure_policy_set` | Replace policy JSON | approval |
-
-40+ deterministic rules: injection, deserialization, weak crypto (including shell TLS bypass flags), secrets, dangerous config, sensitive logging, path traversal, SSRF.
-
-```bash
-dsh plugin --profile web add dsh-code-security
+| secure_scan | Optional target and engines array | State |
+| secure_diff | base (HEAD), staged, target, includeUntracked (false), engines | State |
+| secure_fix_verify | Reuse the previous scope/engines; narrowing is rejected | State only after a complete recheck |
+| secure_report | Latest findings, baseline split and coverage | None |
+| secure_export | format: sarif/markdown; optional path | Approval when writing a path |
+| secure_baseline | Required reason; accept all current findings | Approval |
+| secure_deps | target; audit: none/offline/online | Temporary snapshot |
+| secure_policy_show | Show project policy | None |
+| secure_policy_set | Complete policy JSON | Approval |
+| secure_health | Engine versions, settings and cache metadata | None |
+
+Example secure_scan arguments:
+
+```json
+{"target":"src","engines":["builtin","betterleaks","semgrep"]}
 ```
 
-## License
+Rechecks retain the previous target, Git base, staging mode and engine selection. An incomplete check closes no previous findings. A rule ceasing to match is separate from application tests passing.
+
+Legacy diff records lack the full scope metadata. Rerun secure_diff once after upgrading before rechecking such a record.
+
+## Scope and state
+
+Defaults: 5,000 files, 2 MiB per file, at most 64 MiB per enhanced snapshot. Build directories, node_modules, .git and .code-security are excluded; symlinks/junctions are not followed. Unreadable/oversized files and parse/output limits are explicitly incomplete. Current scans cover a workspace or Git diff, not every historical commit.
+
+Relative stateDir defaults to the session project's .code-security. Locks and atomic replacement protect concurrent history/baseline writes. Corrupt records are preserved and reported. Legacy findings, history and baselines are migrated to redacted evidence while retaining fingerprints computed from original evidence. Complete detected credentials are not returned to the model or reports.
+
+Policy file: `.code-security.json`.
+
+```json
+{"version":1,"exclude":["vendor/**","generated/**"],"ignore":[{"ruleId":"SEC-206","file":"test/**","reason":"Not security-sensitive"}],"failOn":"high"}
+```
+
+Git runs with external diff/textconv disabled. Paths are relative to the session workspace. Staged scans read the index and only added-line findings are reported. Invalid arguments, Git refs and incomplete hunks preserve previous state.
+
+## Development and licenses
+
+Run `pnpm test`. Without native executable paths, the three native integration tests are explicitly skipped. Separate CI jobs install pinned, checksum-verified engines on Windows/Linux and use a synthetic offline OSV database.
 
-MIT (see [LICENSE](../LICENSE))
+The plugin and its original rules are [MIT](../LICENSE). Optional programs are not redistributed. See [third-party notices](../THIRD_PARTY_NOTICES.md). Static checks provide reviewable evidence and do not replace application tests or a full security audit.

package/docs/USAGE.md

@@ -1,85 +1,97 @@
-# dsh-code-security 使用说明
+# 代码安全检查使用说明
 
-[返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
+[返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证范围](VALIDATION.md)
 
-## 本次改进
+## 从一次修改开始
 
-相对 stateDir 默认在会话工作区的 .code-security。并发扫描保留双方历史；记录损坏时先备份排查，不会默默重建。扫描不跟随符号链接或目录联接；静态规则不能代替完整安全审计。
+在项目聊天中说：“检查当前改动的安全问题，给出证据，修好后再复查。”也可以打开 DSH「设置 → 代码安全」，选择项目后点击「检查代码」或「检查改动」。
 
-0.3.8 改进（2026-10-12）：`secure_diff` 支持 Git 转义的中文/特殊文件名，并检查新增私钥、`.env` 敏感项与禁用审计配置。它读取前后各 3 行上下文以处理已有豁免和跨行配置，只报告证据涉及新增行的问题；跨行证据的行号指向匹配的起始行。暂存扫描以暂存区内容为准。
+工作台登记当前会话的项目目录，不接受浏览器传入任意磁盘路径。项目尚未出现时，先在该项目聊天中运行一次安全检查，再刷新项目。检查可以在关闭面板后继续；取消检查会等待进程退出，不覆盖之前的结果。
 
-全量、直接指定文件与增量扫描均遵守默认目录排除及策略 `exclude`。文件路径统一相对当前会话工作区；在仓库子目录作为工作区时，增量扫描不包含该目录外的改动。返回的 `filesScanned` 为实际审查的文件数，`filesSkipped` 包含排除项；增量结果另有 `filesChanged` 和实际审查的 `addedLines`。
+结果区区分新增和已接受的问题，并显示严重度、置信度、规则、位置、来源及脱敏证据。可筛选高风险问题、复制位置、导出 SARIF/Markdown。打开文件需要先打开对应的项目聊天；否则复制位置即可。
 
-`base` 必须是非空 Git ref，不能以 `-` 开头；`staged` 必须是布尔值。差异块行数不完整或格式错误会报错，本次不会覆盖已有扫描记录。Git 的颜色/前缀偏好不会改变解析格式，外部 diff 和 textconv 转换器被禁用。
+## 选择检查深度
 
-旧记录的 `./` 路径前缀可继续匹配基线。私钥、`.env` 和禁用审计配置现在使用实际匹配片段；旧基线若保存的是文件开头的大段文本，可能被重新识别为新增，需复扫并人工复核后再接受。详见[本轮迭代记录](ITERATION-2026-10-12.md)。
+| 引擎 | 检查内容 | 默认行为 |
+| :-- | :-- | :-- |
+| 内置规则 | 40+ 条注入、反序列化、弱加密、凭据、危险配置、路径与网络模式 | 启用，本地运行 |
+| Betterleaks 1.9.0 | 平台格式与通用密钥规则 | 可选，关闭在线密钥有效性验证 |
+| Semgrep CE 1.181.0 | 本插件自有的 JS/TS 命令、HTML、SQL 与 Python 命令输入传播规则 | 可选，本地运行，关闭指标与版本查询 |
+| OSV-Scanner 2.7.0 | 锁文件中的实际依赖版本与已知漏洞 | 在依赖检查中单独选择 |
+
+增强程序由用户安装，不随插件自动下载。在「增强工具与自动检查」填写可执行文件路径，或将程序加入 PATH，保存后点击「检查工具」。设置对当前 DSH profile 生效；自动检查开关按项目保存。只选择需要的引擎，未安装时可继续使用内置规则。
+
+扫描状态包含覆盖情况：执行完成、部分完成、未安装、超时、失败、没有可检查文件。选中但失败的引擎不会被当成通过；没有符合该引擎的文件会明确标注未运行。同一位置、同类问题合并展示并保留来源。
+
+内置 HTML 规则是低置信度的写入点提示。只有可确认词法绑定来自 dompurify 的默认 sanitize 调用才可抑制提示；同名参数、重写方法、额外配置或语法解析失败不会被简单当作安全。Semgrep CE 提供单文件数据流证据，不承诺跨文件分析或漏洞可利用性。
+
+## 依赖清单与漏洞审计
+
+- **仅列出依赖**：默认离线；解析 npm、PEP 621、Poetry、Python 依赖组、Cargo、Go 等声明，显示固定/范围/浮动版本。清单不是漏洞审计，解析失败和动态依赖会说明。
+- **本地数据库**：通过 OSV 的完全离线模式扫描锁文件。数据库未找到或锁文件无效时显示未完成。
+- **联网审计**：明确选择后，向 OSV 查询包名、实际版本等依赖信息；不上传源代码，不执行包管理器、项目安装脚本或构建脚本。显示漏洞编号、受影响版本和上游列出的修复版本。
+
+推荐提供 package-lock.json、pnpm-lock.yaml、uv.lock 等锁文件；只有版本范围时不能冒充实际安装版本。本地路径包不能当作已查询公共漏洞库。修复版本来自公告，升级前仍需检查兼容性。
+
+OSV 2.7.0 当前实现使用 `缓存目录/osv-scalibr/npm/all.zip`（Python 使用 PyPI）。在工作台填写的是**缓存目录**。可从 OSV 官方漏洞导出桶下载相应生态的 all.zip，或者自行使用 OSV 的数据库下载命令。注意：2.7.0 的源码/Windows 实测路径与其仍写 osv-scanner 的旧离线文档存在差异。自定义目录会同时传给新旧环境变量；本轮实测的是 2.7.0。
+
+「检查工具」显示找到的缓存和文件修改时间。文件时间不是每条漏洞的更新时间；损坏、不完整、过旧数据库的风险不会由一个日期消除。参考 [OSV 离线说明](https://google.github.io/osv-scanner/usage/offline-mode/)和[当前缓存实现](https://github.com/google/osv-scalibr/blob/5be78a00e3c2/enricher/vulnmatch/osvlocal/matcher.go)。
 
-## 工具
+## 安静的自动检查
 
-| 工具 | 作用 | 写操作 |
+默认关闭。在项目的增强设置中启用「每轮完成后检查改动」并保存：
+
+1. 主会话一轮结束后，合并等待约 1.8 秒再检查；新一轮开始会取消旧检查。
+2. 只用内置规则检查本地 Git 改动和未跟踪的新文件，不运行模型或外部扫描程序。
+3. 只把未被手动基线接受的新增高风险模式，作为证据提供给后续对话提示。没有弹窗，也不会自动修改代码或接受基线。
+4. 结果放在独立的 automatic 目录，保留手动增强扫描和复查记录。非 Git 项目或检查失败会在设置中提示手动核对。
+
+它不是定时监控，也不会在 DSH 关闭后运行。提醒发生在后续对话中，不是主动发起一轮新对话。
+
+## 工具参数
+
+| 工具 | 主要参数与用途 | 写入 |
 | :-- | :-- | :-- |
-| `secure_scan` | 扫描文件/目录，输出 CWE/严重度/行号/代码片段证据 | 写状态 |
-| `secure_diff` | 只审查 git diff 新增行 | 写状态 |
-| `secure_fix_verify` | 修复后复扫：关闭 / 仍存在 / 新引入 | 写状态 |
-| `secure_report` | 按规则/文件聚合 + 门禁结论 | 否 |
-| `secure_export` | 导出 SARIF 2.1.0 / Markdown 报告 | 写文件审批 |
-| `secure_baseline` | 接受当前已知问题为基线，之后只按新增判定 | 审批门 |
-| `secure_deps` | SBOM-lite：解析依赖清单与版本约束风险 | 否 |
-| `secure_policy_show` | 查看 .code-security.json 策略 | 否 |
-| `secure_policy_set` | 写入策略（排除/忽略/阈值） | 审批门 |
-
-## 规则覆盖（40+）
-
-- 注入：eval / exec / shell=True / SQL 拼接 / innerHTML
-- 反序列化：pickle / yaml.load / ObjectInputStream / Marshal / unserialize
-- 加密：弱哈希、ECB、硬编码 IV/密钥、JWT none、TLS 校验关闭、Shell TLS 绕过（curl -k / wget --no-check-certificate / git sslVerify=false）
-- 凭据：硬编码密码、令牌、私钥、高熵密钥
-- 配置：chmod 777、Docker privileged / latest、npm audit=false、CORS *
-- 泄露：敏感日志、错误堆栈外发、路径穿越、SSRF
-
-发现只包含客观证据与 CWE 编号，不附修复建议——修复方案由 agent 基于证据生成。
-
-## 安装
-
-```bash
-dsh plugin --profile web add dsh-code-security
+| secure_scan | target 可选；engines 可选数组 | 本地状态 |
+| secure_diff | base 默认 HEAD；staged；target；includeUntracked 默认 false；engines | 本地状态 |
+| secure_fix_verify | 沿用上次范围与引擎，不能用缩小范围伪称修复 | 完整复查后更新状态 |
+| secure_report | 最近结果、新增/已接受、覆盖情况 | 无 |
+| secure_export | format 为 sarif/markdown；path 可选 | 提供 path 时需审批 |
+| secure_baseline | reason 必填，接受当前全部问题 | 需审批 |
+| secure_deps | target；audit 为 none/offline/online | 临时快照 |
+| secure_policy_show | 查看项目策略 | 无 |
+| secure_policy_set | policy 为完整 JSON | 需审批 |
+| secure_health | 工具版本、检查设置和缓存信息 | 无 |
+
+```json
+{"target":"src","engines":["builtin","betterleaks","semgrep"]}
 ```
 
-## 卸载
+以上是 secure_scan 的参数。secure_fix_verify 默认使用上次的 target、Git base、暂存模式和引擎；检查失败时不判定旧问题已修复。规则不再命中与实际功能测试通过是两项不同证据。
 
-```bash
-dsh plugin --profile web remove dsh-code-security
-```
+升级前的增量记录未保存完整范围，需先重新执行 secure_diff，之后才能按原范围复查。
 
-卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
+## 范围、策略和记录
 
-## 使用
+默认跳过 node_modules、.git、构建目录和 .code-security，也不跟随符号链接/目录联接。默认文件上限 5000、每文件 2 MiB；增强快照总量最多 64 MiB。超过限制、无法读取或格式无效时明确显示不完整。当前检查工作区或指定 Git 差异，不遍历所有 Git 历史提交。
 
-```text
-secure_scan { target: src }
-secure_diff { base: HEAD }
-secure_fix_verify { target: src }
-secure_baseline { reason: 历史遗留 }
-secure_deps { target: . }
-```
+相对 stateDir 默认位于当前会话项目的 .code-security。并发写入使用锁与原子替换；记录损坏时保留原文件并报错。旧记录、历史和基线读取时会迁移为脱敏证据，并保留基于原始证据计算的指纹。不会向模型或报告返回完整检测到的密钥。
 
-策略示例（`.code-security.json`）：
+策略文件 `.code-security.json`：
 
 ```json
 {
   "version": 1,
   "exclude": ["vendor/**", "generated/**"],
-  "ignore": [{ "ruleId": "SEC-206", "file": "test/**", "reason": "非安全敏感" }],
+  "ignore": [{"ruleId":"SEC-206","file":"test/**","reason":"非安全敏感"}],
   "failOn": "high"
 }
 ```
 
-## 工程
+Git 输出禁用外部 diff/textconv，路径相对当前会话工作区。暂存检查读取 Git index；新增行才计入差异发现。错写参数、无效 Git ref 或不完整 diff 不会覆盖已有记录。
 
-```bash
-pnpm test       # 构建并执行测试
-```
+## 开发与许可
 
-## License
+`pnpm test` 构建并测试；未指定原生程序路径时，三项原生引擎集成测试明确跳过。CI 另有 Windows/Linux 原生引擎任务，使用固定版本、校验下载摘要和合成离线漏洞库。
 
-MIT（见 [LICENSE](../LICENSE)）
+插件和自有规则采用 [MIT](../LICENSE)。第三方程序未打包进插件，其许可和规则限制见 [第三方说明](../THIRD_PARTY_NOTICES.md)。静态检查提供可复核线索，不能替代项目测试或完整安全审计。

package/docs/VALIDATION.md

@@ -2,6 +2,24 @@
 
 本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
 
+## 0.4.1（2026-10-15）
+
+79 项 Windows 测试全部通过，包含下列三个真实原生引擎。新增同一行同时命中注入与高熵密钥的回归，确认其他规则的证据、返回值、历史、基线和导出也不再带出原值；截断的字符串使用相同判断。其余功能与客户端沿用 0.4.0 的验收范围。
+
+## 0.4.0（2026-10-15）
+
+本地环境：Windows、Node 24.16.0、官方 npm DSH 0.2.1-alpha.3。全部使用 E 盘隔离目录与合成数据，没有复制用户密钥或修改前台桌面窗口。
+
+- **78 项 Windows 测试通过，无跳过**，包含真实 Betterleaks 1.9.0、Semgrep CE 1.181.0、OSV-Scanner 2.7.0。普通未安装原生引擎的测试运行会明确跳过这三项，不能等同于原生验收。
+- **真实原生引擎**：合成令牌/占位符和脱敏、局部变量传播、参数化 SQL、DOMPurify 导入与同名参数、传递依赖的离线公告/修复版本/缺库/损坏锁文件。OSV 另覆盖 Git 忽略了临时目录的真实仓库，避免跳过快照后产生空结果。
+- **官方 DSH 网页端实际操作**：项目登记与空态、检查工具、增强扫描、脱敏证据、SARIF 下载、离线漏洞编号/修复版本、缺失程序、取消、修复复查、中文/英文切换、390px 窄屏。浏览器控制插件不可用，使用独立的无头系统 Chrome 与 Playwright；控制台/页面错误为 0，无横向溢出。
+- **自动检查回归**：默认关闭、未跟踪文件、手动结果隔离、已接受基线过滤、新一轮取消、过期事件竞态及被动上下文注册；不启动模型或擅自接受基线。
+- **发布包安装**：用官方 CLI 将最终本地 tarball 安装到新的隔离 profile，核对版本、十个工具、PEP 621、脱敏、SARIF、客户端及三份规则文件。公开 registry 与 CI 产物的一致性由独立发布流程核对。
+
+**验收边界**：本轮未操作原生桌面窗口；网页版结果不记作桌面端验收。文件预览仅验证了未打开对应聊天时的明确提示，没有完成活动聊天中的文件跳转。已知漏洞在线查询曾在真实 OSV 程序中检查样例依赖；离线匹配使用合成数据库，不代表完整公共漏洞库覆盖或准确率测评。未调用用户的真实模型完成一轮任务。
+
+CI 新增 Windows/Linux × Node 22/24，以及两种系统上的固定原生引擎任务；每个运行结果可在 [Actions](https://github.com/STARDUSTLC666/dsh-code-security/actions) 独立查看。扫描通过、相关功能测试通过、包已发布和桌面操作通过是不同结论。
+
 ## 原中文记录
 
 2026-09-13 修复：保留宿主 `subprocess.spawn` 的服务对象，避免方法独立传递后因 `this` 丢失而报错。该路径已在隔离宿主进程服务中实测通过。`secure_diff` 已通过真实宿主进程服务读取隔离 Git 仓库差异，正确识别变更文件和新增行。

package/lib/audit.d.ts

@@ -0,0 +1,27 @@
+import type { ResolvedSecureConfig, SourceEngine } from './config.js';
+import type { ProcessRunner } from './runner.js';
+import type { SecurePolicy } from './policy.js';
+import { type EngineCoverage } from './engines.js';
+export type ScanScope = {
+    kind: 'scan';
+    target?: string;
+} | {
+    kind: 'diff';
+    target?: string;
+    base: string;
+    staged: boolean;
+    includeUntracked?: boolean;
+};
+export declare function sourceEngines(value: unknown, defaults: SourceEngine[]): SourceEngine[];
+export declare function runSourceCheck(scope: ScanScope, cfg: ResolvedSecureConfig, cwd: string, runner: ProcessRunner, engines: SourceEngine[], policy: SecurePolicy, signal?: AbortSignal): Promise<{
+    findings: import("./scanner.js").Finding[];
+    engines: SourceEngine[];
+    coverage: EngineCoverage[];
+    complete: boolean;
+    scope: ScanScope;
+    warnings: string[];
+    root: string;
+    filesScanned: number;
+    filesSkipped: number;
+    durationMs: number;
+}>;

package/lib/audit.js

@@ -0,0 +1,109 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { policyIgnores } from './policy.js';
+import { parseDiff, runGitDiff, scanDiff } from './diff.js';
+import { isExcludedPath, scanPath } from './scanner.js';
+import { mergeFindings, scanExternal } from './engines.js';
+export function sourceEngines(value, defaults) {
+    if (value === undefined)
+        return [...defaults];
+    if (!Array.isArray(value) || !value.length || value.length > 3 || value.some(e => !['builtin', 'betterleaks', 'semgrep'].includes(e)) || new Set(value).size !== value.length)
+        throw new Error('engines 必须从 builtin、betterleaks、semgrep 中选择，不能重复或为空。');
+    return value;
+}
+export async function runSourceCheck(scope, cfg, cwd, runner, engines, policy, signal) {
+    const documents = [];
+    let documentBytes = 0, truncated = false;
+    const collect = (doc) => { const size = Buffer.byteLength(doc.text); if (documentBytes + size > 64 * 1024 * 1024) {
+        truncated = true;
+        return;
+    } ; documentBytes += size; documents.push(doc); };
+    let result;
+    if (scope.kind === 'scan')
+        result = await scanPath({ cwd, target: scope.target, maxFiles: cfg.maxFiles, maxFileBytes: cfg.maxFileBytes, policy, signal, ...(engines.some(e => e !== 'builtin') ? { onDocument: collect } : {}) });
+    else {
+        const diff = await runGitDiff(runner, cwd, scope.base, scope.target, 30000, scope.staged);
+        const scanned = scanDiff(diff, cwd, policy);
+        result = { root: scope.base, ...scanned, durationMs: 0, complete: true, warnings: [] };
+        if (engines.some(e => e !== 'builtin')) {
+            for (const file of parseDiff(diff, cwd)) {
+                signal?.throwIfAborted();
+                if (isExcludedPath(file.file, policy) || !file.added.length)
+                    continue;
+                if (documents.length >= cfg.maxFiles) {
+                    truncated = true;
+                    break;
+                }
+                const absolute = path.resolve(cwd, file.file), rel = path.relative(cwd, absolute);
+                if (rel.startsWith('..') || path.isAbsolute(rel))
+                    throw new Error('增量文件超出当前工作区');
+                let text;
+                if (scope.staged) {
+                    const shown = await runner.run(['git', 'show', ':./' + file.file], { cwd, timeoutMs: 30000, signal });
+                    if (shown.exitCode !== 0)
+                        throw new Error('无法读取暂存区文件，请刷新后重试');
+                    text = shown.stdout;
+                }
+                else {
+                    const stat = await fs.lstat(absolute);
+                    if (!stat.isFile() || stat.isSymbolicLink() || await fs.realpath(absolute) !== absolute)
+                        throw new Error('增量文件不是工作区内的普通文件');
+                    if (stat.size > cfg.maxFileBytes) {
+                        truncated = true;
+                        continue;
+                    }
+                    text = await fs.readFile(absolute, { encoding: 'utf8', signal });
+                }
+                if (Buffer.byteLength(text) > cfg.maxFileBytes) {
+                    truncated = true;
+                    continue;
+                }
+                const lines = text.split(/\r?\n/);
+                if (file.added.some(line => lines[line.line - 1] !== line.text))
+                    throw new Error('扫描期间文件已变化，请重新扫描；已有记录未覆盖');
+                collect({ file: file.file, text, selectedLines: new Set(file.added.map(line => line.line)) });
+            }
+            if (await runGitDiff(runner, cwd, scope.base, scope.target, 30000, scope.staged) !== diff)
+                throw new Error('扫描期间 Git 改动已变化，请重试');
+        }
+        if (scope.includeUntracked && !scope.staged) {
+            const untracked = await runner.run(['git', 'ls-files', '--others', '--exclude-standard', '-z', '--', scope.target ?? '.'], { cwd, signal, timeoutMs: 30000 });
+            if (untracked.exitCode !== 0)
+                throw new Error('无法读取未跟踪文件列表');
+            if (untracked.stdout && !untracked.stdout.endsWith('\0'))
+                throw new Error('未跟踪文件列表不完整，已有记录未覆盖');
+            const names = untracked.stdout.split('\0').filter(Boolean);
+            for (const name of names) {
+                signal?.throwIfAborted();
+                if (result.filesScanned >= cfg.maxFiles) {
+                    result.complete = false;
+                    result.warnings.push('已达到文件数量上限');
+                    break;
+                }
+                if (path.isAbsolute(name) || name.split(/[\\/]/).includes('..'))
+                    throw new Error('未跟踪文件超出当前工作区');
+                let added = 0;
+                const extra = await scanPath({ cwd, target: name, maxFiles: 1, maxFileBytes: cfg.maxFileBytes, policy, signal, onDocument(doc) { added = doc.text.split(/\r?\n/).length; if (engines.some(e => e !== 'builtin'))
+                        collect(doc); } });
+                result.filesChanged++;
+                result.filesScanned += extra.filesScanned;
+                result.filesSkipped += extra.filesSkipped;
+                result.addedLines += added;
+                result.findings.push(...extra.findings);
+                result.complete &&= extra.complete;
+                result.warnings.push(...extra.warnings);
+            }
+        }
+    }
+    const coverage = engines.includes('builtin') ? [{ engine: 'builtin', status: result.complete ? 'completed' : 'partial', findingsCount: result.findings.length, ...(result.complete ? {} : { reason: 'incomplete-coverage' }) }] : [];
+    let findings = engines.includes('builtin') ? result.findings : [];
+    const external = await Promise.all(engines.filter((e) => e !== 'builtin').map(e => scanExternal(e, documents, cfg, runner, signal)));
+    for (const checked of external) {
+        findings.push(...checked.findings.filter(f => !policyIgnores(policy, f.ruleId, f.file)));
+        coverage.push(truncated && checked.coverage.status === 'completed' ? { ...checked.coverage, status: 'partial', reason: 'snapshot-size-limit' } : checked.coverage);
+    }
+    if (engines.length > 1)
+        findings = mergeFindings(findings);
+    const { diff: _privateDiff, base: _base, ...publicResult } = result;
+    return { ...publicResult, findings, engines, coverage, complete: result.complete && !truncated && coverage.every(c => c.status === 'completed' || c.status === 'not-run' && c.reason === 'no-eligible-files'), scope };
+}

package/lib/automatic.d.ts

@@ -0,0 +1,18 @@
+import type { SecurityWorkbench } from './workbench.js';
+export declare class AutomaticSecurity {
+    private readonly workbench;
+    private readonly idleMs;
+    private readonly pending;
+    private readonly tasks;
+    private readonly revisions;
+    private readonly aliases;
+    private readonly alerts;
+    private closed;
+    constructor(workbench: SecurityWorkbench, idleMs?: number);
+    attach(host: any): () => void;
+    observe(session: any, event: any): Promise<void>;
+    context(agent: any): string;
+    private cancel;
+    whenIdle(): Promise<void>;
+    dispose(): void;
+}