dsh-code-security 0.3.7 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 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` 敏感项和禁用依赖审计配置的问题，报告真实证据行号。
+- 结合有限上下文识别已有豁免和跨行配置，仅报告涉及新增行的问题；校验差异块行数，格式错误或不完整时明确报错。
+- 全量、单文件与增量扫描统一排除策略和工作区相对路径，兼容旧记录中 `./` 前缀的基线指纹。
+- 固定 Git 输出格式与当前工作区范围，禁用外部 diff/textconv，拒绝被误当成 Git 选项的基线参数和错误类型的 `staged` 参数。
+- 补充隔离 Git 回归场景；范围、兼容注意事项及后续计划见[本轮迭代记录](docs/ITERATION-2026-10-12.md)。
+
 ## 0.3.7 (2026-10-05)
 
 - 扫描、策略、报告和 git diff 使用当前会话工作区；支持取消并跳过目录联接。锁定合并历史与基线写入，损坏记录和无效策略明确报错并保留原文件。

package/README.en.md

@@ -8,11 +8,14 @@ Run local static security checks on code or Git changes and verify fixes.
 
 [![npm](https://img.shields.io/npm/v/dsh-code-security)](https://www.npmjs.com/package/dsh-code-security) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-code-security-downloads.svg)](https://www.npmjs.com/package/dsh-code-security)
 
+Feedback and contributions are welcome: report [issues](https://github.com/STARDUSTLC666/dsh-code-security/issues) or submit [pull requests](https://github.com/STARDUSTLC666/dsh-code-security/pulls).
+
 ## 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
 
@@ -26,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

@@ -8,11 +8,14 @@
 
 [![npm](https://img.shields.io/npm/v/dsh-code-security)](https://www.npmjs.com/package/dsh-code-security) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-code-security-downloads.svg)](https://www.npmjs.com/package/dsh-code-security)
 
+欢迎使用，遇到问题或有改进建议，请提交 [issues](https://github.com/STARDUSTLC666/dsh-code-security/issues) 和 [PR](https://github.com/STARDUSTLC666/dsh-code-security/pulls)。
+
 ## 功能
 
 - 扫描文件、目录或 Git diff，报告规则、位置与代码证据。
-- 复扫修复结果，维护问题基线和检查策略。
-- 导出 Markdown / SARIF 报告，检查依赖清单。
+- 在 DSH 设置中查看新增问题、检查覆盖、脱敏证据，并复查修复结果。
+- 可选 Betterleaks 密钥检测、Semgrep CE 数据流规则、OSV 依赖漏洞审计。
+- 导出 Markdown / SARIF，维护基线；可按项目开启安静的自动改动检查。
 
 ## 安装
 
@@ -26,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/ITERATION-2026-10-12.md

@@ -0,0 +1,53 @@
+# dsh-code-security 第一轮迭代
+
+日期：2026-10-12。基于 `91d4d8c770cfaa796d07b7b770a627c3bce8f49e`，本轮版本为 `0.3.8`。此页记录源码迭代和本地验证；发布 CI、npm 完整性及隔离安装结果在发布后独立核验。
+
+这轮先解决增量审查的漏报、范围和证据一致性。原有 37 项测试全部通过，但新增回归测试在旧实现上复现了中文路径、文件级规则等问题被误判为通过。
+
+## 已实现
+
+| 场景 | 原行为 | 当前行为 |
+| :-- | :-- | :-- |
+| 中文/转义文件名 | Git 引号与八进制路径解析失败，可能返回零发现并通过 | 解码 UTF-8 与 Git 的 C 转义，保留正确文件和行号 |
+| 新增私钥、`.env` 敏感项、`audit=false` | 增量扫描跳过文件级规则 | 全量和增量共用匹配，定位实际证据；保留跨行配置检测 |
+| 未改动的豁免注释、危险代码 | 缺少上下文，已有 next-line 豁免失效 | 读取少量上下文，只报告证据涉及新增行的问题 |
+| 仓库子目录作为会话工作区 | 带入兄弟目录改动，路径基准偏离工作区 | Git 范围和证据路径均相对当前会话工作区 |
+| 策略排除 | 增量扫描未应用排除，直接选择文件也绕过排除 | 三种扫描入口统一排除；报告实际扫描和跳过数量 |
+| 基线一致性 | 全量的 `./src/a.js` 与增量的 `src/a.js` 指纹不同 | 规范相对路径，并从保存的证据重算旧基线指纹 |
+| Git 个性化配置/参数 | 颜色、前缀影响解析；`--quiet` 可误当基线 | 固定输出格式，禁用外部 diff/textconv，校验参数类型 |
+| 差异块缺失行 | 接受不完整差异并给出部分结果 | 校验差异块行数，异常时保留原扫描状态并报错 |
+
+主要代码：[diff.ts](../src/diff.ts)、[scanner.ts](../src/scanner.ts)、[tools.ts](../src/tools.ts)、[state.ts](../src/state.ts)。已同步仓库跟踪的 `lib/` 构建产物。
+
+## 验证
+
+- `pnpm test`：53/53 通过，0 失败，0 跳过；包含 TypeScript 构建。
+- 新增 16 项回归测试，其中 9 项使用本地隔离 Git 仓库。覆盖中文路径、暂存区与工作树不一致、Git 输出偏好、子工作区、基线兼容、外部转换器与排除计数等。
+- 工具调用链覆盖 `secure_scan` / `secure_diff` / `secure_baseline` / `secure_fix_verify` / `secure_report` / `secure_export`，验证写入状态、结果渲染文本和 SARIF 路径。
+- 环境：Windows，Node `24.16.0`，pnpm `11.7.0`，Git `2.54.0.windows.1`。
+- 本页所列测试未在真实 DSH Web/桌面界面执行点击、输入或视觉验收；本地运行环境为 Windows/Node 24，Linux CI 与 npm 发布验收另行记录。
+
+回归入口：[diff.test.mjs](../test/diff.test.mjs)、[git-diff.test.mjs](../test/git-diff.test.mjs)。测试仓库位于 E 盘项目内的 `test/.tmp/`，测试结束后仅清理经过路径校验的自建子目录。
+
+## 兼容注意
+
+未新增依赖；继续沿用项目已有的 MIT 许可与 `proper-lockfile@4.1.2`（MIT），Node 声明保持 `^22.19.0 || >=24.0.0`。原工具名和参数结构保留，增量输出增加明确的扫描/跳过计数。
+
+旧记录的 `./` 前缀兼容已验证。`SEC-303`、`SEC-305`、`SEC-404` 的证据由“整个文件开头”改成“实际匹配片段”；旧基线若使用前一种片段，可能被视为新增。应复扫并人工确认后重新接受，不能自动把新证据全部豁免。
+
+增量检查只涵盖 Git 显示的文本差异，仍不包含未跟踪文件。上下文为前后各 3 行；超出上下文的跨行结构、通用数据流和复杂语言语义未由本轮解决。差异块校验可以发现块内截断，但不代表已解决所有收集上限下的完整性判断。
+
+## 下一轮优先项
+
+以下来自当前代码静态检查，尚未在本轮实现或验收。
+
+1. **扫描完整性门禁。** `scanPath` 遇到不存在目标、读取失败或文件数上限时，应返回明确的完整性状态；`passed` 不能仅因发现为空而为真。还应检查宿主 stdout 收集上限带来的整体截断。
+2. **复扫范围校验。** `secure_fix_verify` 应核对上次与本次目标/覆盖范围，避免把没有重新扫描的问题误报为关闭；部分复扫应输出“未验证”。
+3. **规则准确性与隐私。** 补充安全/危险样例集，优先处理普通字符串、块注释、已使用安全 Loader 等误报；为密钥证据增加默认脱敏，并设计不依赖明文片段的稳定指纹。
+4. **依赖清单解析。** 为标准 `pyproject.toml`、Cargo 依赖区段和损坏清单补测试，再评估采用 MIT/兼容许可的 TOML 解析器；当前 SBOM-lite 不能当作漏洞数据库扫描。
+
+后续功能迭代仍需补单插件真实 DSH 界面验收和更广的跨平台 CI；本版发布验证独立进行。
+
+## Git 行为依据
+
+输出格式、工作区相对范围和外部转换器开关按 [Git diff 官方文档](https://git-scm.com/docs/git-diff) 实现；文件名转义依据 [core.quotePath 官方说明](https://git-scm.com/docs/git-config#Documentation/git-config.txt-corequotePath)。

package/docs/USAGE.en.md

@@ -1,31 +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**.
+
+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.
+
+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.
+
+## 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"]}
+```
+
+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"}
 ```
 
-## License
+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,77 +1,97 @@
-# dsh-code-security 使用说明
+# 代码安全检查使用说明
 
-[返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
+[返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证范围](VALIDATION.md)
 
-## 本次改进
+## 从一次修改开始
 
-相对 stateDir 默认在会话工作区的 .code-security。并发扫描保留双方历史；记录损坏时先备份排查，不会默默重建。扫描不跟随符号链接或目录联接；静态规则不能代替完整安全审计。
+在项目聊天中说：“检查当前改动的安全问题，给出证据，修好后再复查。”也可以打开 DSH「设置 → 代码安全」，选择项目后点击「检查代码」或「检查改动」。
 
-## 工具
+工作台登记当前会话的项目目录，不接受浏览器传入任意磁盘路径。项目尚未出现时，先在该项目聊天中运行一次安全检查，再刷新项目。检查可以在关闭面板后继续；取消检查会等待进程退出，不覆盖之前的结果。
 
-| 工具 | 作用 | 写操作 |
+结果区区分新增和已接受的问题，并显示严重度、置信度、规则、位置、来源及脱敏证据。可筛选高风险问题、复制位置、导出 SARIF/Markdown。打开文件需要先打开对应的项目聊天；否则复制位置即可。
+
+## 选择检查深度
+
+| 引擎 | 检查内容 | 默认行为 |
 | :-- | :-- | :-- |
-| `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
-```
+| 内置规则 | 40+ 条注入、反序列化、弱加密、凭据、危险配置、路径与网络模式 | 启用，本地运行 |
+| Betterleaks 1.9.0 | 平台格式与通用密钥规则 | 可选，关闭在线密钥有效性验证 |
+| Semgrep CE 1.181.0 | 本插件自有的 JS/TS 命令、HTML、SQL 与 Python 命令输入传播规则 | 可选，本地运行，关闭指标与版本查询 |
+| OSV-Scanner 2.7.0 | 锁文件中的实际依赖版本与已知漏洞 | 在依赖检查中单独选择 |
 
-## 卸载
+增强程序由用户安装，不随插件自动下载。在「增强工具与自动检查」填写可执行文件路径，或将程序加入 PATH，保存后点击「检查工具」。设置对当前 DSH profile 生效；自动检查开关按项目保存。只选择需要的引擎，未安装时可继续使用内置规则。
 
-```bash
-dsh plugin --profile web remove dsh-code-security
-```
+扫描状态包含覆盖情况：执行完成、部分完成、未安装、超时、失败、没有可检查文件。选中但失败的引擎不会被当成通过；没有符合该引擎的文件会明确标注未运行。同一位置、同类问题合并展示并保留来源。
+
+内置 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)。
+
+## 安静的自动检查
 
-卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
+默认关闭。在项目的增强设置中启用「每轮完成后检查改动」并保存：
 
-## 使用
+1. 主会话一轮结束后，合并等待约 1.8 秒再检查；新一轮开始会取消旧检查。
+2. 只用内置规则检查本地 Git 改动和未跟踪的新文件，不运行模型或外部扫描程序。
+3. 只把未被手动基线接受的新增高风险模式，作为证据提供给后续对话提示。没有弹窗，也不会自动修改代码或接受基线。
+4. 结果放在独立的 automatic 目录，保留手动增强扫描和复查记录。非 Git 项目或检查失败会在设置中提示手动核对。
 
-```text
-secure_scan { target: src }
-secure_diff { base: HEAD }
-secure_fix_verify { target: src }
-secure_baseline { reason: 历史遗留 }
-secure_deps { target: . }
+它不是定时监控，也不会在 DSH 关闭后运行。提醒发生在后续对话中，不是主动发起一轮新对话。
+
+## 工具参数
+
+| 工具 | 主要参数与用途 | 写入 |
+| :-- | :-- | :-- |
+| 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"]}
 ```
 
-策略示例（`.code-security.json`）：
+以上是 secure_scan 的参数。secure_fix_verify 默认使用上次的 target、Git base、暂存模式和引擎；检查失败时不判定旧问题已修复。规则不再命中与实际功能测试通过是两项不同证据。
+
+升级前的增量记录未保存完整范围，需先重新执行 secure_diff，之后才能按原范围复查。
+
+## 范围、策略和记录
+
+默认跳过 node_modules、.git、构建目录和 .code-security，也不跟随符号链接/目录联接。默认文件上限 5000、每文件 2 MiB；增强快照总量最多 64 MiB。超过限制、无法读取或格式无效时明确显示不完整。当前检查工作区或指定 Git 差异，不遍历所有 Git 历史提交。
+
+相对 stateDir 默认位于当前会话项目的 .code-security。并发写入使用锁与原子替换；记录损坏时保留原文件并报错。旧记录、历史和基线读取时会迁移为脱敏证据，并保留基于原始证据计算的指纹。不会向模型或报告返回完整检测到的密钥。
+
+策略文件 `.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,20 @@
 
 本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
 
+## 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;
+}