dvalincode 0.18.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,7 +9,7 @@
9
9
  <p align="center">
10
10
  <a href="https://github.com/arthurpanhku/dvalincode/releases/latest"><img src="https://img.shields.io/github/v/release/arthurpanhku/dvalincode?style=for-the-badge&color=818cf8&label=Release" alt="Release"></a>
11
11
  <a href="https://github.com/arthurpanhku/dvalincode/releases"><img src="https://img.shields.io/github/downloads/arthurpanhku/dvalincode/total?style=for-the-badge&color=blue&label=Downloads" alt="Downloads"></a>
12
- <a href="#-tests"><img src="https://img.shields.io/badge/Tests-442%20%2F%20442%20%E2%9C%93-success?style=for-the-badge" alt="Tests"></a>
12
+ <a href="#-tests"><img src="https://img.shields.io/badge/Tests-584%20%2F%20584%20%E2%9C%93-success?style=for-the-badge" alt="Tests"></a>
13
13
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License"></a>
14
14
  <a href="https://scorecard.dev/viewer/?uri=github.com/arthurpanhku/dvalincode"><img src="https://api.scorecard.dev/projects/github.com/arthurpanhku/dvalincode/badge" alt="OpenSSF Scorecard"></a>
15
15
  <a href="#-quick-install"><img src="https://img.shields.io/badge/Platforms-macOS%20·%20Windows%20·%20Linux-blue?style=for-the-badge" alt="Platforms"></a>
@@ -41,6 +41,8 @@ Fix record 2c9d71ac03e0 · VERIFIED · scan-and-checks
41
41
  executor: claude-code (recorded, not consulted)
42
42
  targets: 1 before · 0 remaining
43
43
  coverage: complete → complete
44
+ introduced: 0 (gate high/new)
45
+ outcome: verified
44
46
  ✓ test: npm run test (exit 0)
45
47
  audit: run verify-36509f42 @ 414644c75af0
46
48
  ```
@@ -51,6 +53,14 @@ and Dvalin will not let it be read as one — every record carries what the scan
51
53
  actually covered, and a repair no check could confirm does not pass.
52
54
  [The open profile →](docs/spec/FIX-VERIFICATION.md)
53
55
 
56
+ A repair is a change, and a change can add as well as remove. So the record also
57
+ carries what the re-scan saw that the first scan did not, and the gate threshold
58
+ the verdict was reached under: a fix that removes an `eval` and introduces an SQL
59
+ injection is recorded as `regressed` and does not verify. Neither does a record
60
+ whose issuer never looked — `introduced: not determined` fails, because a
61
+ verifier that skips the question must not score better than one that asks it and
62
+ finds something.
63
+
54
64
  Dvalin is the independent security runtime between code generation and merge.
55
65
  Humans, coding agents, and CI call the same versioned contract for discovery,
56
66
  remediation, and verification. It runs independently, or interoperates with
@@ -144,10 +154,21 @@ job. The reviewer does not have to trust the pipeline that produced it, or us.
144
154
  - repaired by claude-code — recorded, and not consulted for this verdict
145
155
  - targets: 1 before → 0 remaining
146
156
  - coverage: complete → complete
157
+ - introduced: none (gate high/new)
158
+ - outcome: verified
147
159
  - ✓ test: `npm run test` (exit 0)
148
160
  - audit chain: verify-eeb1bae7 @ 80881867270d
149
161
  ```
150
162
 
163
+ A repair that regressed says so in the same place, and fails the job with it:
164
+
165
+ ```
166
+ ❌ 916e2eeaf065 · NOT VERIFIED · scan-and-checks
167
+ - introduced: 1 finding(s) the first scan did not report (gate high/new)
168
+ - critical dvalin/sql-injection — src/db.ts:31
169
+ - outcome: regressed
170
+ ```
171
+
151
172
  ### Or let your agent call it
152
173
 
153
174
  If an agent is writing the code, something other than that agent has to check
@@ -172,26 +193,37 @@ merges into whatever is already there. [Editors and MCP →](integrations/mcp/)
172
193
  `dvalin_scan` accepts `diff: "uncommitted"`, which reports only on what the
173
194
  agent just wrote rather than everything the repository already carried — the
174
195
  difference between a usable answer and a wall of pre-existing findings. It never
175
- runs a model or edits the target workspace. It records a
176
- small local workflow so an agent can retrieve one finding by fingerprint and
177
- request an independent re-scan through `dvalin_get_finding` and
178
- `dvalin_verify_findings`.
196
+ runs a model, edits the target workspace, or persists Dvalin state, so clients
197
+ can allow the preview by default. When a finding will be repaired, the agent
198
+ explicitly calls `dvalin_begin_verification` to record a small local workflow;
199
+ it can then retrieve the finding by fingerprint and request an independent
200
+ re-scan through `dvalin_get_finding` and `dvalin_verify_findings`.
179
201
 
180
202
  That last one is the point: an agent that has just written a repair can ask for
181
203
  an independent verdict on it. Dvalin re-scans, runs the project's own checks
182
204
  itself, and returns a **Verified Fix Record** — what was targeted, what remains,
183
- which commands ran and the exit codes Dvalin observed, and how much of the
184
- codebase was actually covered. Whoever wrote the repair is recorded and never
185
- consulted. `dvalin_verify_fix` re-derives such a record offline, so the reviewer
205
+ what the repair introduced that was not there before, the gate the verdict was
206
+ reached under, which commands ran and the exit codes Dvalin observed, and how
207
+ much of the codebase was actually covered. Whoever wrote the repair is recorded
208
+ and never consulted. `dvalin_verify_fix` re-derives such a record offline, so the reviewer
186
209
  receiving it does not have to trust the tool that issued it.
187
210
  [FVP-1 →](docs/spec/FIX-VERIFICATION.md) Responses include MCP `structuredContent`; scanner
188
211
  readiness is available through `dvalin_list_scanners`. The same server exposes
189
212
  `dvalin_run_task` as an optional implementation helper, plus session and audit
190
213
  evidence tools.
191
214
 
192
- Verified end to end against Claude Code 2.1.226 and Codex 0.147.0, driving a
193
- real tool call against the published package rather than only completing a
194
- handshake. [Agent integrations →](integrations/)
215
+ Every client below has been driven to a real tool call rather than only a
216
+ handshake — which client, which version, and on what date is a table rather
217
+ than a sentence, because hand-written version numbers go stale quietly.
218
+ [Integration support ↓](#-integration-support) · [Agent integrations →](integrations/)
219
+
220
+ The repository also contains one [dual Codex/Claude plugin payload](integrations/dvalin-security/)
221
+ with both native manifests, the shared security-gate skill, and the local MCP
222
+ server configuration. Installing it makes the gate discoverable from task
223
+ context instead of requiring every developer to remember a scan prompt.
224
+ Codex honors the scan's read-only MCP annotation. Claude Code requires one
225
+ explicit MCP permission by design; the plugin documents the exact scan-only
226
+ allow rule instead of asking users to bypass all permissions.
195
227
 
196
228
  ### Wherever you already work
197
229
 
@@ -199,10 +231,10 @@ One server, reached the way each tool expects:
199
231
 
200
232
  | Harness | How Dvalin reaches it |
201
233
  |---|---|
202
- | **Claude Code** | `dvalincode mcp-install claude-code`, or `claude mcp add` · [skill](integrations/claude-code/) |
203
- | **Codex** | `codex mcp add` · [SARIF interop](integrations/codex-security/) with Codex Security |
234
+ | **Claude Code** | [dual plugin](integrations/dvalin-security/) or `claude mcp add` · [standalone skill](integrations/claude-code/) |
235
+ | **Codex** | [dual plugin](integrations/dvalin-security/) or `codex mcp add` · [SARIF interop](integrations/codex-security/) with Codex Security |
204
236
  | **Cursor** | `dvalincode mcp-install cursor` |
205
- | **VS Code** | `dvalincode mcp-install vscode` · [extension](editors/vscode/) for the Problems panel — *built, not yet published* |
237
+ | **VS Code** | `dvalincode mcp-install vscode` · [extension](editors/vscode/) for Problems, coverage/gate status, and offline VFR verification — *built, not yet published* |
206
238
  | **Windsurf · Zed** | stdio MCP through their own settings — [server command](integrations/mcp/) |
207
239
  | **Any MCP client** | [MCP registry](https://registry.modelcontextprotocol.io/): `io.github.arthurpanhku/dvalincode` |
208
240
  | **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings inline on the pull request diff |
@@ -294,6 +326,76 @@ dvalincode report verify # re-derive the hash chain of the last run's audit l
294
326
 
295
327
  ---
296
328
 
329
+ ## 🧩 Integration support
330
+
331
+ Code written with an AI assistant passes through four sets of hands before it
332
+ merges: the agent that writes it, the editor the developer reads it back in, the
333
+ pull request that gates it, and the reviewer who has to believe the result. A
334
+ security answer that exists in only one of those places is not a gate — it is a
335
+ suggestion the next stage is free to ignore.
336
+
337
+ Dvalin is one MCP server and one deterministic scan behind all four, so the
338
+ answer does not change depending on who asks it.
339
+
340
+ | Stage of the loop | Where you are | How Dvalin gets there | Status |
341
+ |---|---|---|---|
342
+ | **Writing the code** | Claude Code | [dual plugin](integrations/dvalin-security/) · `claude mcp add` · `mcp-install claude-code` | ✅ session verified |
343
+ | | Codex | [dual plugin](integrations/dvalin-security/) · `codex mcp add` · [SARIF interop](integrations/codex-security/) | ✅ session verified · capture pending |
344
+ | | Cursor | `dvalincode mcp-install cursor` | ⚙️ config verified |
345
+ | | Windsurf · Zed | stdio MCP through their own settings | ⚙️ documented, unverified |
346
+ | | Any MCP client | registry `io.github.arthurpanhku/dvalincode` | ⚙️ published |
347
+ | **Reading it back** | VS Code | `mcp-install vscode` · [extension](editors/vscode/) for Problems, coverage and gate status | ✅ editor verified |
348
+ | **Gating the merge** | GitHub Actions | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings on the diff, fix records re-derived on the runner | ✅ runs on this repository's own CI |
349
+ | | Any CI | `dvalin scan . --fail-on high`, SARIF out for code scanning | ✅ the exit code is the contract |
350
+ | **Believing the result** | anyone, offline | `dvalin verify-fix record.json` | ✅ no workspace, no network, no Dvalin state |
351
+
352
+ **✅** means a real client was driven end to end and the tool call was observed.
353
+ **⚙️** means the configuration is generated and its shape is tested, but no
354
+ session has been captured. The difference is not smoothed over here, because a
355
+ config file that loads is not evidence that a tool was ever called.
356
+
357
+ ### What each claim rests on
358
+
359
+ | Client | Version | Checked | How |
360
+ |---|---|---|---|
361
+ | Claude Code | CLI 2.1.260 | 2026-09-04 | server connected, `dvalin_scan` called with only that tool allow-listed, three findings returned — capture below |
362
+ | Claude Code | CLI 2.1.251 | 2026-08-31 | weekly [`harness-interop`](.github/workflows/harness-interop.yml) — a real handshake against the built binary, which needs no credentials |
363
+ | Codex | CLI 0.149.1 | 2026-09-03 | by hand on macOS: scan called under `approval=never` in a read-only sandbox, no workflow state written |
364
+ | Codex | CLI 0.151.0 | 2026-08-31 | weekly `harness-interop` — the server spec is accepted and stored as stdio. **Not a handshake**: the tool-call step stays skipped until `CODEX_API_KEY` is set |
365
+ | VS Code | 1.134.0 · extension 0.18.0 | 2026-09-03 | packaged VSIX in a clean profile; finding, gate and coverage rendered in the editor — capture below |
366
+ | Cursor | — | 2026-09-04 | `mcp-install cursor` writes `.cursor/mcp.json` under `mcpServers`; no session has been captured |
367
+
368
+ That weekly workflow exists because an earlier version of this claim named two
369
+ CLI versions by hand, both went stale within weeks, and nothing said so. It now
370
+ re-checks against whatever those tools shipped that week, so the dates above
371
+ either move on their own or stop moving in public.
372
+
373
+ ### The same finding, in each place
374
+
375
+ **Claude Code** — one read-only tool allow-listed, and the MCP call itself:
376
+
377
+ ![A Claude Code session calling the Dvalin MCP server](docs/screenshots/10-claude-code-session.png)
378
+
379
+ **Codex** — capture pending.
380
+
381
+ <!--
382
+ The Codex session capture belongs here, as docs/screenshots/11-codex-session.png.
383
+ To produce it on a machine with the Codex CLI installed and authenticated:
384
+
385
+ codex mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .
386
+ codex exec --sandbox read-only \
387
+ "Scan this workspace with Dvalin and list every finding with rule id, file, line and severity."
388
+
389
+ Or set the CODEX_API_KEY repository secret, and .github/workflows/harness-interop.yml
390
+ stops skipping its "Codex calls a tool" step every Monday.
391
+ -->
392
+
393
+ **VS Code** — the same scanner contract, as squiggles and a status bar:
394
+
395
+ ![A Dvalin finding and its coverage status inside VS Code](docs/screenshots/09-vscode-dvalin-integration.png)
396
+
397
+ ---
398
+
297
399
  ## 🏛️ And it survives a security review
298
400
 
299
401
  That last command is the part that matters once more than one person depends on
@@ -659,6 +761,19 @@ Headless `run` and `mcp-serve` keep the same policy and audit chokepoint as
659
761
  the interactive clients. See the [unattended recipes](docs/RECIPES-UNATTENDED.md)
660
762
  for cron, CI, and external-agent examples.
661
763
 
764
+ A run that scanned or filed a fix record also carries a `verification` envelope
765
+ beside its answer — in `json`, in `stream-json`, and in the MCP `dvalin_run_task`
766
+ result. `coverageStatus` is the *weakest* coverage the run has evidence of, so
767
+ one complete scan cannot speak for a partial one, and any record it produced is
768
+ listed by path for offline re-derivation. A CI gate can read it directly:
769
+
770
+ ```sh
771
+ jq -e '.verification.coverageStatus == "complete"' run.json || exit 1
772
+ ```
773
+
774
+ That is the same rule the pull-request comment applies, on the surface with no
775
+ human watching. [Harness mode →](docs/HARNESS-MODE.md)
776
+
662
777
  ### Windows
663
778
 
664
779
  Download `dvalincode-v*-windows-x64.zip` from [Releases](https://github.com/arthurpanhku/dvalincode/releases/latest), unzip, then double-click `start.bat`.
@@ -834,7 +949,8 @@ RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE
834
949
  npm test
835
950
  ```
836
951
 
837
- **442 tests · 62 files · all green.**
952
+ **584 core tests · 74 files · all green.** The VS Code extension has a separate
953
+ 37-test suite plus one opt-in published-package integration test.
838
954
 
839
955
  ---
840
956
 
@@ -955,7 +1071,7 @@ Contributions welcome. The codebase is intentionally small and surgical — see
955
1071
  ```sh
956
1072
  git clone https://github.com/arthurpanhku/dvalincode
957
1073
  cd dvalincode && npm install
958
- npm test # 442/442 ✅
1074
+ npm test # 584/584 core tests ✅
959
1075
  npm run typecheck
960
1076
  ```
961
1077
 
@@ -1024,6 +1140,8 @@ Full source references: [docs/REFERENCES.md](docs/REFERENCES.md)
1024
1140
  | Shivas | [@shivasb42](https://github.com/shivasb42) |
1025
1141
  | Aditya | [@adity982](https://github.com/adity982) |
1026
1142
  | badhope | [@weed33834](https://github.com/weed33834) |
1143
+ | Samran Asif | [@webdevsamran](https://github.com/webdevsamran) |
1144
+ | dchaudhari7177 | [@dchaudhari7177](https://github.com/dchaudhari7177) |
1027
1145
 
1028
1146
  See the [complete contribution history](https://github.com/arthurpanhku/dvalincode/graphs/contributors), including automated dependency and maintenance updates.
1029
1147
 
package/README.zh-CN.md CHANGED
@@ -9,7 +9,7 @@
9
9
  <p align="center">
10
10
  <a href="https://github.com/arthurpanhku/dvalincode/releases/latest"><img src="https://img.shields.io/github/v/release/arthurpanhku/dvalincode?style=for-the-badge&color=818cf8&label=Release" alt="Release"></a>
11
11
  <a href="https://github.com/arthurpanhku/dvalincode/releases"><img src="https://img.shields.io/github/downloads/arthurpanhku/dvalincode/total?style=for-the-badge&color=blue&label=Downloads" alt="Downloads"></a>
12
- <a href="#-测试"><img src="https://img.shields.io/badge/Tests-442%20%2F%20442%20%E2%9C%93-success?style=for-the-badge" alt="Tests"></a>
12
+ <a href="#-测试"><img src="https://img.shields.io/badge/Tests-584%20%2F%20584%20%E2%9C%93-success?style=for-the-badge" alt="Tests"></a>
13
13
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License"></a>
14
14
  <a href="https://scorecard.dev/viewer/?uri=github.com/arthurpanhku/dvalincode"><img src="https://api.scorecard.dev/projects/github.com/arthurpanhku/dvalincode/badge" alt="OpenSSF Scorecard"></a>
15
15
  <a href="#-一行安装"><img src="https://img.shields.io/badge/Platforms-macOS%20·%20Windows%20·%20Linux-blue?style=for-the-badge" alt="Platforms"></a>
@@ -38,6 +38,8 @@ Fix record 2c9d71ac03e0 · VERIFIED · scan-and-checks
38
38
  executor: claude-code (recorded, not consulted)
39
39
  targets: 1 before · 0 remaining
40
40
  coverage: complete → complete
41
+ introduced: 0 (gate high/new)
42
+ outcome: verified
41
43
  ✓ test: npm run test (exit 0)
42
44
  audit: run verify-36509f42 @ 414644c75af0
43
45
  ```
@@ -47,6 +49,12 @@ Fix record 2c9d71ac03e0 · VERIFIED · scan-and-checks
47
49
  究竟覆盖了什么,而一个没有任何检查能确认的修复,不会通过。
48
50
  [开放规范 →](docs/spec/FIX-VERIFICATION.md)
49
51
 
52
+ 修复本身也是一次改动,而改动既会移除问题,也可能带来新问题。所以记录里还带着复扫
53
+ 看到、而首扫没有看到的东西,以及这次判定所依据的门禁阈值:一个删掉了 `eval`、却引入
54
+ 了 SQL 注入的修复,会被记为 `regressed`,不予通过。签发方根本没去看的记录同样不通过
55
+ —— `introduced: not determined` 直接失败,因为「不去查」绝不能比「查了并且查出问题」
56
+ 得分更高。
57
+
50
58
  Dvalin 是放在“代码生成”和“允许合并”之间的独立安全运行时。人类开发者、Coding
51
59
  Agent 和 CI 调用同一套版本化协议完成发现、修复与验证。它既可以独立运行,也可以通过
52
60
  可移植的 SARIF 与 Codex Security 等专业系统互操作。内置 Coding 能力只负责可靠地执行
@@ -133,10 +141,21 @@ runner 会仅凭这个文件本身重新推导它 —— 重算哈希,并从
133
141
  - repaired by claude-code — recorded, and not consulted for this verdict
134
142
  - targets: 1 before → 0 remaining
135
143
  - coverage: complete → complete
144
+ - introduced: none (gate high/new)
145
+ - outcome: verified
136
146
  - ✓ test: `npm run test` (exit 0)
137
147
  - audit chain: verify-eeb1bae7 @ 80881867270d
138
148
  ```
139
149
 
150
+ 引入了新问题的修复,会在同一个地方说清楚,并让这个 job 失败:
151
+
152
+ ```
153
+ ❌ 916e2eeaf065 · NOT VERIFIED · scan-and-checks
154
+ - introduced: 1 finding(s) the first scan did not report (gate high/new)
155
+ - critical dvalin/sql-injection — src/db.ts:31
156
+ - outcome: regressed
157
+ ```
158
+
140
159
  ### 或者让你的 agent 调用它
141
160
 
142
161
  如果代码是 agent 写的,那检查它的就不能是同一个 agent。DvalinCode 本身是个 MCP
@@ -158,14 +177,21 @@ npx dvalincode mcp-install claude-code # .mcp.json
158
177
  `mcpServers`,填反了编辑器会照单全收然后当没看见。这条命令会写对,并且合并进已有
159
178
  配置而不是覆盖。[编辑器与 MCP →](integrations/mcp/)
160
179
 
161
- `dvalin_scan` 支持 `diff: "uncommitted"`,只报告 agent 刚写的部分,而不是仓库里的全部存量问题。它不跑模型,也不会修改目标 workspace;它只持久化一份精简的本地安全
162
- workflow。Agent 可以用 fingerprint 精确读取单条发现,再通过 `dvalin_get_finding` 和
180
+ `dvalin_scan` 支持 `diff: "uncommitted"`,只报告 agent 刚写的部分,而不是仓库里的全部存量问题。它不跑模型、不修改目标 workspace、也不持久化 Dvalin 状态,因此客户端可以默认允许这次预览。确认要修复某条发现后,Agent 再显式调用
181
+ `dvalin_begin_verification` 创建精简的本地安全 workflow,用 fingerprint 精确读取单条发现,再通过 `dvalin_get_finding` 和
163
182
  `dvalin_verify_findings` 请求独立复扫。响应包含 MCP `structuredContent`,并可通过
164
183
  `dvalin_list_scanners` 查询组件是否就绪。同一 server 也提供可选的 `dvalin_run_task`
165
184
  实现助手,以及 session 和审计证据工具。
166
185
 
167
- 已针对 Claude Code 2.1.226 和 Codex 0.147.0 做过端到端验证 —— 是用已发布的包真实发起
168
- 工具调用,而不只是握手成功。[Agent 集成 →](integrations/)
186
+ 下面每一个客户端都被驱动到了真实的工具调用,而不只是握手成功 —— 具体是哪个客户端、
187
+ 哪个版本、哪一天验的,写成了表格而不是一句话,因为手写的版本号会悄无声息地过期。
188
+ [集成支持 ↓](#-集成支持) · [Agent 集成 →](integrations/)
189
+
190
+ 仓库还提供一份 [Codex/Claude 双兼容插件](integrations/dvalin-security/):同时包含两套
191
+ 原生 manifest、共享安全门禁 skill 和本地 MCP server 配置。安装后,agent 可根据任务
192
+ 上下文自动发现门禁,不再依赖每位开发者记住扫描提示词。
193
+ Codex 会采纳扫描工具的只读 MCP 标注;Claude Code 按其安全设计仍需显式授权一次。
194
+ 插件给出精确到只读扫描工具的 allow 规则,不要求用户绕过所有权限。
169
195
 
170
196
  ### 你在哪儿干活,它就在哪儿
171
197
 
@@ -173,10 +199,10 @@ workflow。Agent 可以用 fingerprint 精确读取单条发现,再通过 `dva
173
199
 
174
200
  | Harness | 怎么接 |
175
201
  |---|---|
176
- | **Claude Code** | `dvalincode mcp-install claude-code`,或 `claude mcp add` · [skill](integrations/claude-code/) |
177
- | **Codex** | `codex mcp add` · 与 Codex Security 的 [SARIF 互操作](integrations/codex-security/) |
202
+ | **Claude Code** | [双兼容插件](integrations/dvalin-security/),或 `claude mcp add` · [独立 skill](integrations/claude-code/) |
203
+ | **Codex** | [双兼容插件](integrations/dvalin-security/),或 `codex mcp add` · 与 Codex Security 的 [SARIF 互操作](integrations/codex-security/) |
178
204
  | **Cursor** | `dvalincode mcp-install cursor` |
179
- | **VS Code** | `dvalincode mcp-install vscode` · 在 Problems 面板出结果的[扩展](editors/vscode/) —— *已构建,尚未发布* |
205
+ | **VS Code** | `dvalincode mcp-install vscode` · 在 Problems、coverage/gate 状态和离线 VFR 校验中展示结果的[扩展](editors/vscode/) —— *已构建,尚未发布* |
180
206
  | **Windsurf · Zed** | 在各自设置里配 stdio MCP —— [server 命令](integrations/mcp/) |
181
207
  | **任意 MCP 客户端** | [MCP registry](https://registry.modelcontextprotocol.io/):`io.github.arthurpanhku/dvalincode` |
182
208
  | **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) —— 结果直接标在 PR diff 上 |
@@ -258,6 +284,72 @@ dvalincode report verify # 重新推导上次运行审计日志的哈希链
258
284
 
259
285
  ---
260
286
 
287
+ ## 🧩 集成支持
288
+
289
+ AI 协助写出来的代码,在合并之前会经过四道手:写它的 agent、开发者读它的编辑器、
290
+ 拦它的 Pull Request,以及最后必须相信这个结论的评审者。一个只存在于其中一处的安全
291
+ 结论不是门禁,只是一条下一环节可以无视的建议。
292
+
293
+ Dvalin 在这四处背后是同一个 MCP server、同一次确定性扫描 —— 所以答案不会因为谁在问
294
+ 而改变。
295
+
296
+ | 开发环节 | 你在哪儿 | Dvalin 怎么接进去 | 状态 |
297
+ |---|---|---|---|
298
+ | **写代码** | Claude Code | [双兼容插件](integrations/dvalin-security/) · `claude mcp add` · `mcp-install claude-code` | ✅ 会话已验证 |
299
+ | | Codex | [双兼容插件](integrations/dvalin-security/) · `codex mcp add` · [SARIF 互操作](integrations/codex-security/) | ✅ 会话已验证 · 截图待补 |
300
+ | | Cursor | `dvalincode mcp-install cursor` | ⚙️ 配置已验证 |
301
+ | | Windsurf · Zed | 通过它们自己的设置接 stdio MCP | ⚙️ 已文档化,未验证 |
302
+ | | 任意 MCP 客户端 | registry `io.github.arthurpanhku/dvalincode` | ⚙️ 已发布 |
303
+ | **回头读代码** | VS Code | `mcp-install vscode` · [扩展](editors/vscode/):Problems、覆盖度与门禁状态 | ✅ 编辑器内已验证 |
304
+ | **卡住合并** | GitHub Actions | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) —— finding 落在 diff 上,fix record 在 runner 上重新推导 | ✅ 本仓库自己的 CI 就在跑 |
305
+ | | 任意 CI | `dvalin scan . --fail-on high`,输出 SARIF | ✅ 退出码就是契约 |
306
+ | **相信这个结论** | 任何人,离线 | `dvalin verify-fix record.json` | ✅ 不需要 workspace、网络或任何 Dvalin 状态 |
307
+
308
+ **✅** 表示真实客户端被端到端驱动过,并且观察到了工具调用。
309
+ **⚙️** 表示配置能生成、格式经过测试,但还没有抓到会话记录。这个区别这里不含糊过去 ——
310
+ 一个能被加载的配置文件,不能证明工具真的被调用过。
311
+
312
+ ### 每一条结论的依据
313
+
314
+ | 客户端 | 版本 | 检查时间 | 怎么检查的 |
315
+ |---|---|---|---|
316
+ | Claude Code | CLI 2.1.260 | 2026-09-04 | server 连上,只放行 `dvalin_scan` 一个工具并被真实调用,返回 3 条 finding —— 见下方截图 |
317
+ | Claude Code | CLI 2.1.251 | 2026-08-31 | 每周的 [`harness-interop`](.github/workflows/harness-interop.yml):对构建产物做真实握手,这一步不需要任何凭据 |
318
+ | Codex | CLI 0.149.1 | 2026-09-03 | 在 macOS 上人工执行:`approval=never` 的只读沙箱里调用了 scan,没有写入任何 workflow 状态 |
319
+ | Codex | CLI 0.151.0 | 2026-08-31 | 每周的 `harness-interop`:server 配置被接受并按 stdio 存下。**这不是握手** —— 在设置 `CODEX_API_KEY` 之前,调用工具那一步一直是 skipped |
320
+ | VS Code | 1.134.0 · 扩展 0.18.0 | 2026-09-03 | 干净 profile 里安装打包好的 VSIX;finding、门禁和覆盖度都出现在编辑器里 —— 见下方截图 |
321
+ | Cursor | — | 2026-09-04 | `mcp-install cursor` 会把 `.cursor/mcp.json` 写成 `mcpServers` 结构;但还没有抓到会话记录 |
322
+
323
+ 那个每周任务之所以存在,是因为这段话的早期版本手写了两个 CLI 版本号,两个都在几周内
324
+ 过期,而没有任何东西提醒过。现在它每周对着这些工具的当周版本重跑一次 —— 上面这些日期
325
+ 要么自己往前走,要么就公开地停在那里。
326
+
327
+ ### 同一条 finding,在不同的地方
328
+
329
+ **Claude Code** —— 只放行了一个只读工具,以及那次 MCP 调用本身:
330
+
331
+ ![Claude Code 会话调用 Dvalin MCP server](docs/screenshots/10-claude-code-session.png)
332
+
333
+ **Codex** —— 截图待补。
334
+
335
+ <!--
336
+ Codex 的会话截图放这里,命名为 docs/screenshots/11-codex-session.png。
337
+ 在装好并认证过 Codex CLI 的机器上这样产出:
338
+
339
+ codex mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .
340
+ codex exec --sandbox read-only \
341
+ "Scan this workspace with Dvalin and list every finding with rule id, file, line and severity."
342
+
343
+ 或者配好 CODEX_API_KEY 这个仓库 secret,.github/workflows/harness-interop.yml
344
+ 每周一就不会再跳过它的 "Codex calls a tool" 那一步。
345
+ -->
346
+
347
+ **VS Code** —— 同一套扫描器契约,变成波浪线和状态栏:
348
+
349
+ ![VS Code 里的 Dvalin finding 与覆盖度状态](docs/screenshots/09-vscode-dvalin-integration.png)
350
+
351
+ ---
352
+
261
353
  ## 🏛️ 而且它过得了安全评审
262
354
 
263
355
  当依赖这套工具的不止你一个人时,上面那条命令才是真正要紧的东西。DvalinCode 是一个
@@ -565,6 +657,18 @@ dvalincode mcp-serve # 供外部 Agent 调用的任务级 stdio MCP
565
657
  无头 `run` 和 `mcp-serve` 与交互客户端共用同一个策略与审计关卡。cron、CI
566
658
  和外部 Agent 示例见[无人值守配方](docs/RECIPES-UNATTENDED.md)。
567
659
 
660
+ 扫描过、或者产出过 fix record 的运行,还会在结果旁边带上一份 `verification` 信封 ——
661
+ `json`、`stream-json` 以及 MCP `dvalin_run_task` 的返回里都有。`coverageStatus` 取的
662
+ 是这次运行**有证据支持的最弱**覆盖度,因此一次完整扫描不能替一次部分扫描背书;产出
663
+ 的记录按路径列出,可离线复验。CI 门禁可以直接读它:
664
+
665
+ ```sh
666
+ jq -e '.verification.coverageStatus == "complete"' run.json || exit 1
667
+ ```
668
+
669
+ 这和 PR 评论用的是同一条规则,只是用在没有人盯着的那个界面上。
670
+ [Harness 模式 →](docs/HARNESS-MODE.md)
671
+
568
672
  ### Windows
569
673
 
570
674
  从 [Releases](https://github.com/arthurpanhku/dvalincode/releases/latest) 下载 `dvalincode-v*-windows-x64.zip`,解压后双击 `start.bat`。
@@ -730,7 +834,8 @@ RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE
730
834
  npm test
731
835
  ```
732
836
 
733
- **442 个测试 · 62 个文件 · 全部通过。**
837
+ **584 个核心测试 · 74 个文件 · 全部通过。** VS Code 扩展另有 37 个测试,
838
+ 以及一个可选的已发布包集成测试。
734
839
 
735
840
  ---
736
841
 
@@ -857,7 +962,7 @@ Linux 与 macOS 命令通过 <code>/bin/sh</code> 执行;Windows 命令通过
857
962
  ```sh
858
963
  git clone https://github.com/arthurpanhku/dvalincode
859
964
  cd dvalincode && npm install
860
- npm test # 442/442 ✅
965
+ npm test # 584/584 核心测试 ✅
861
966
  npm run typecheck
862
967
  ```
863
968
 
@@ -917,6 +1022,8 @@ prompt、UI 文案、工具 schema、模块布局和产品实现均为原创;
917
1022
  | Shivas | [@shivasb42](https://github.com/shivasb42) |
918
1023
  | Aditya | [@adity982](https://github.com/adity982) |
919
1024
  | badhope | [@weed33834](https://github.com/weed33834) |
1025
+ | Samran Asif | [@webdevsamran](https://github.com/webdevsamran) |
1026
+ | dchaudhari7177 | [@dchaudhari7177](https://github.com/dchaudhari7177) |
920
1027
 
921
1028
  查看[完整贡献记录](https://github.com/arthurpanhku/dvalincode/graphs/contributors),其中也包含自动依赖更新和维护记录。
922
1029
 
@@ -1,5 +1,7 @@
1
1
  import type { Command } from 'commander';
2
- import { type SecurityCoverage } from '../security/contracts.js';
2
+ import { snapshotFinding, type SecurityCoverage } from '../security/contracts.js';
3
+ import { type FixExecutor } from '../security/fixRecord.js';
4
+ import type { SecurityCheckEvidence } from '../security/workflow.js';
3
5
  import { type DvalinScannerId, type DvalinScanSuiteResult } from '../remediation/scannerSuite.js';
4
6
  declare const SEVERITIES: readonly ['critical', 'high', 'medium', 'low'];
5
7
  type FailSeverity = typeof SEVERITIES[number] | 'none';
@@ -7,6 +9,36 @@ export declare function parseDvalinScannerIds(value: string): DvalinScannerId[];
7
9
  export declare function dvalinFailureThresholdMet(result: DvalinScanSuiteResult, threshold: FailSeverity): boolean;
8
10
  export declare function renderDvalinResult(result: DvalinScanSuiteResult, root: string, limit?: number, coverage?: SecurityCoverage): string;
9
11
  export declare function registerDvalinCommand(program: Command): void;
12
+ /**
13
+ * Assemble the record for one `--fix --verify` run.
14
+ *
15
+ * Extracted from the run so the evidence it carries can be asserted without
16
+ * standing up an executor, a worktree, and a git tree. The gap that made this
17
+ * worth extracting: with the assembly inline, a change that stopped supplying
18
+ * the regression evidence broke nothing any test could see.
19
+ */
20
+ export declare function buildRunFixRecord(input: {
21
+ root: string;
22
+ executor: FixExecutor;
23
+ before: DvalinScanSuiteResult;
24
+ after: DvalinScanSuiteResult;
25
+ targets: DvalinScanSuiteResult['findings'];
26
+ baseline: DvalinScanSuiteResult['findings'];
27
+ checks: SecurityCheckEvidence[];
28
+ changes?: {
29
+ files: string[];
30
+ diffHash: string;
31
+ };
32
+ }): import("../security/fixRecord.js").VerifiedFixRecord;
33
+ /**
34
+ * What the re-scan sees that the baseline did not — the repair's side effects.
35
+ *
36
+ * Compared against the baseline rather than the targets, so a finding that was
37
+ * already in the repository before the repair is not blamed on it. Unfiltered
38
+ * by severity: the record keeps the observation, and the recorded threshold
39
+ * decides what blocks.
40
+ */
41
+ export declare function introducedSince(baseline: DvalinScanSuiteResult['findings'], after: DvalinScanSuiteResult): ReturnType<typeof snapshotFinding>[];
10
42
  /**
11
43
  * Parse `git status --porcelain -z`.
12
44
  *
@@ -255,23 +255,15 @@ async function runAutomatedRemediation(input) {
255
255
  // Issued whether or not the gate passed: a record that says a repair did not
256
256
  // verify is exactly as useful as one that says it did, and dropping it on
257
257
  // failure would leave the only unrecorded outcome the one worth recording.
258
- const record = buildFixRecord({
259
- projectId: securityProjectId(input.root),
258
+ const record = buildRunFixRecord({
259
+ root: input.root,
260
260
  executor: fixExecutorFor(executor.id),
261
- before: {
262
- scanId: input.before.id,
263
- completedAt: input.before.completedAt,
264
- coverage: deriveCoverage(input.before),
265
- targets: input.findings.map(snapshotFinding),
266
- },
267
- after: {
268
- scanId: after.id,
269
- completedAt: after.completedAt,
270
- coverage: deriveCoverage(after),
271
- remainingTargets: remainingTargets(input.findings, after),
272
- },
273
- changes: await changesFrom(cwd),
261
+ before: input.before,
262
+ after,
263
+ targets: input.findings,
264
+ baseline: input.baselineFindings,
274
265
  checks: verification.evidence,
266
+ changes: await changesFrom(cwd),
275
267
  });
276
268
  saveFixRecord(record);
277
269
  if (input.recordPath) {
@@ -310,6 +302,56 @@ function remainingTargets(originals, after) {
310
302
  .map(snapshotFinding)
311
303
  .filter(target => present.has(target.targetFingerprint));
312
304
  }
305
+ /**
306
+ * Assemble the record for one `--fix --verify` run.
307
+ *
308
+ * Extracted from the run so the evidence it carries can be asserted without
309
+ * standing up an executor, a worktree, and a git tree. The gap that made this
310
+ * worth extracting: with the assembly inline, a change that stopped supplying
311
+ * the regression evidence broke nothing any test could see.
312
+ */
313
+ export function buildRunFixRecord(input) {
314
+ return buildFixRecord({
315
+ projectId: securityProjectId(input.root),
316
+ executor: input.executor,
317
+ before: {
318
+ scanId: input.before.id,
319
+ completedAt: input.before.completedAt,
320
+ coverage: deriveCoverage(input.before),
321
+ targets: input.targets.map(snapshotFinding),
322
+ },
323
+ after: {
324
+ scanId: input.after.id,
325
+ completedAt: input.after.completedAt,
326
+ coverage: deriveCoverage(input.after),
327
+ remainingTargets: remainingTargets(input.targets, input.after),
328
+ },
329
+ regression: {
330
+ // `high` and `new` encode the rule this path already applied through
331
+ // `evaluateVerificationGate`, which failed on findings scoring 7 or more
332
+ // that the baseline did not have. Recording it makes that rule part of
333
+ // the record instead of a property of whichever command issued it.
334
+ gate: { threshold: 'high', mode: 'new' },
335
+ introduced: introducedSince(input.baseline, input.after),
336
+ },
337
+ ...(input.changes ? { changes: input.changes } : {}),
338
+ checks: input.checks,
339
+ });
340
+ }
341
+ /**
342
+ * What the re-scan sees that the baseline did not — the repair's side effects.
343
+ *
344
+ * Compared against the baseline rather than the targets, so a finding that was
345
+ * already in the repository before the repair is not blamed on it. Unfiltered
346
+ * by severity: the record keeps the observation, and the recorded threshold
347
+ * decides what blocks.
348
+ */
349
+ export function introducedSince(baseline, after) {
350
+ const known = new Set(baseline.map(finding => snapshotFinding(finding).fingerprint));
351
+ return after.findings
352
+ .map(snapshotFinding)
353
+ .filter(finding => !known.has(finding.fingerprint));
354
+ }
313
355
  /**
314
356
  * The changed files and a hash of the change itself.
315
357
  *