dvalincode 0.16.1 → 0.18.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.
Files changed (129) hide show
  1. package/README.md +203 -44
  2. package/README.zh-CN.md +171 -38
  3. package/THIRD_PARTY_NOTICES.md +98 -43
  4. package/dist/agent/loop.d.ts +1 -1
  5. package/dist/agent/loop.js +2 -1
  6. package/dist/agent/loop.js.map +1 -1
  7. package/dist/agent/runner.js +2 -2
  8. package/dist/agent/runner.js.map +1 -1
  9. package/dist/cli.js +6 -1
  10. package/dist/cli.js.map +1 -1
  11. package/dist/commands/chat.js +3 -2
  12. package/dist/commands/chat.js.map +1 -1
  13. package/dist/commands/data.js +2 -1
  14. package/dist/commands/data.js.map +1 -1
  15. package/dist/commands/dvalin.d.ts +9 -1
  16. package/dist/commands/dvalin.js +185 -44
  17. package/dist/commands/dvalin.js.map +1 -1
  18. package/dist/commands/evidence.js +17 -3
  19. package/dist/commands/evidence.js.map +1 -1
  20. package/dist/commands/mcpInstall.d.ts +2 -0
  21. package/dist/commands/mcpInstall.js +69 -0
  22. package/dist/commands/mcpInstall.js.map +1 -0
  23. package/dist/commands/mcpServe.js +3 -2
  24. package/dist/commands/mcpServe.js.map +1 -1
  25. package/dist/commands/policy.js +2 -1
  26. package/dist/commands/policy.js.map +1 -1
  27. package/dist/commands/report.js +6 -3
  28. package/dist/commands/report.js.map +1 -1
  29. package/dist/commands/runTool.d.ts +20 -0
  30. package/dist/commands/runTool.js +73 -13
  31. package/dist/commands/runTool.js.map +1 -1
  32. package/dist/commands/security.d.ts +47 -0
  33. package/dist/commands/security.js +415 -0
  34. package/dist/commands/security.js.map +1 -0
  35. package/dist/commands/tools.d.ts +11 -1
  36. package/dist/commands/tools.js +24 -3
  37. package/dist/commands/tools.js.map +1 -1
  38. package/dist/commands/update.js +2 -1
  39. package/dist/commands/update.js.map +1 -1
  40. package/dist/core/exitCodes.d.ts +38 -0
  41. package/dist/core/exitCodes.js +38 -0
  42. package/dist/core/exitCodes.js.map +1 -0
  43. package/dist/dvalinCli.d.ts +3 -0
  44. package/dist/dvalinCli.js +36 -0
  45. package/dist/dvalinCli.js.map +1 -0
  46. package/dist/dvalinIndex.d.ts +2 -0
  47. package/dist/dvalinIndex.js +9 -0
  48. package/dist/dvalinIndex.js.map +1 -0
  49. package/dist/evidence/pack.d.ts +8 -0
  50. package/dist/evidence/pack.js +16 -0
  51. package/dist/evidence/pack.js.map +1 -1
  52. package/dist/index.js +2 -1
  53. package/dist/index.js.map +1 -1
  54. package/dist/mcp/install.d.ts +48 -0
  55. package/dist/mcp/install.js +74 -0
  56. package/dist/mcp/install.js.map +1 -0
  57. package/dist/mcp/server.d.ts +12 -1
  58. package/dist/mcp/server.js +233 -14
  59. package/dist/mcp/server.js.map +1 -1
  60. package/dist/remediation/automate.d.ts +4 -1
  61. package/dist/remediation/automate.js +35 -18
  62. package/dist/remediation/automate.js.map +1 -1
  63. package/dist/remediation/diffScope.d.ts +29 -0
  64. package/dist/remediation/diffScope.js +107 -0
  65. package/dist/remediation/diffScope.js.map +1 -0
  66. package/dist/remediation/executor.d.ts +60 -0
  67. package/dist/remediation/executor.js +144 -0
  68. package/dist/remediation/executor.js.map +1 -0
  69. package/dist/remediation/localScan.d.ts +2 -1
  70. package/dist/remediation/localScan.js +73 -3
  71. package/dist/remediation/localScan.js.map +1 -1
  72. package/dist/remediation/sarif.d.ts +6 -0
  73. package/dist/remediation/sarif.js +36 -14
  74. package/dist/remediation/sarif.js.map +1 -1
  75. package/dist/remediation/scannerSuite.d.ts +21 -0
  76. package/dist/remediation/scannerSuite.js +65 -4
  77. package/dist/remediation/scannerSuite.js.map +1 -1
  78. package/dist/remediation/verify.d.ts +38 -0
  79. package/dist/remediation/verify.js +116 -0
  80. package/dist/remediation/verify.js.map +1 -0
  81. package/dist/security/baseline.d.ts +7 -0
  82. package/dist/security/baseline.js +26 -0
  83. package/dist/security/baseline.js.map +1 -0
  84. package/dist/security/config.d.ts +32 -0
  85. package/dist/security/config.js +131 -0
  86. package/dist/security/config.js.map +1 -0
  87. package/dist/security/contracts.d.ts +149 -0
  88. package/dist/security/contracts.js +231 -0
  89. package/dist/security/contracts.js.map +1 -0
  90. package/dist/security/fixRecord.d.ts +125 -0
  91. package/dist/security/fixRecord.js +169 -0
  92. package/dist/security/fixRecord.js.map +1 -0
  93. package/dist/security/fixRecordFile.d.ts +8 -0
  94. package/dist/security/fixRecordFile.js +37 -0
  95. package/dist/security/fixRecordFile.js.map +1 -0
  96. package/dist/security/fixRecordStore.d.ts +23 -0
  97. package/dist/security/fixRecordStore.js +74 -0
  98. package/dist/security/fixRecordStore.js.map +1 -0
  99. package/dist/security/render.d.ts +8 -0
  100. package/dist/security/render.js +20 -0
  101. package/dist/security/render.js.map +1 -0
  102. package/dist/security/suppressions.d.ts +12 -0
  103. package/dist/security/suppressions.js +60 -0
  104. package/dist/security/suppressions.js.map +1 -0
  105. package/dist/security/verifyRun.d.ts +21 -0
  106. package/dist/security/verifyRun.js +74 -0
  107. package/dist/security/verifyRun.js.map +1 -0
  108. package/dist/security/workflow.d.ts +98 -0
  109. package/dist/security/workflow.js +263 -0
  110. package/dist/security/workflow.js.map +1 -0
  111. package/dist/server/routes/remediation.d.ts +19 -0
  112. package/dist/server/routes/remediation.js +90 -18
  113. package/dist/server/routes/remediation.js.map +1 -1
  114. package/dist/tools/registry.d.ts +9 -0
  115. package/dist/tools/registry.js +11 -0
  116. package/dist/tools/registry.js.map +1 -1
  117. package/dist/tools/runCheck.d.ts +6 -0
  118. package/dist/tools/runCheck.js +1 -1
  119. package/dist/tools/runCheck.js.map +1 -1
  120. package/dist/tools/runSecuritySuite.d.ts +3 -0
  121. package/dist/tools/runSecuritySuite.js +18 -11
  122. package/dist/tools/runSecuritySuite.js.map +1 -1
  123. package/dist/tui/app.js +21 -2
  124. package/dist/tui/app.js.map +1 -1
  125. package/dist/tui/render.js +2 -0
  126. package/dist/tui/render.js.map +1 -1
  127. package/dist/version.d.ts +1 -1
  128. package/dist/version.js +1 -1
  129. package/package.json +17 -10
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-323%20%2F%20323%20%E2%9C%93-success?style=for-the-badge" alt="Tests"></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>
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>
@@ -18,23 +18,80 @@
18
18
  </p>
19
19
 
20
20
  <p align="center">
21
- <b>Find the security holes in your repo, fix them, and prove the fix — in one command.</b><br>
22
- Every fix is diffed, tested, re-scanned, and recorded in a tamper-evident audit log before it can become a PR.
21
+ <b>Open security engineering for code written by humans and AI agents.</b><br>
22
+ <b>Every repair carries its own proof.</b>
23
23
  </p>
24
24
 
25
+ When an agent fixes a security finding, someone has to decide whether the fix
26
+ worked. Almost every tool asks the model that wrote it — which is the one
27
+ question a model cannot answer against its own interest.
28
+
29
+ **Dvalin decides instead, and hands you the proof.** It re-scans, runs your
30
+ project's own tests itself, and reads the exit codes from processes it started.
31
+ Who wrote the repair — our agent, Claude Code, Codex, Copilot, a person — is
32
+ recorded and never consulted. The result is a **Verified Fix Record**: a small
33
+ JSON file anyone can re-check offline, on a laptop with no network and no
34
+ Dvalin state.
35
+
36
+ ```sh
37
+ dvalin verify-fix fix-record.json
38
+ ```
39
+ ```
40
+ Fix record 2c9d71ac03e0 · VERIFIED · scan-and-checks
41
+ executor: claude-code (recorded, not consulted)
42
+ targets: 1 before · 0 remaining
43
+ coverage: complete → complete
44
+ ✓ test: npm run test (exit 0)
45
+ audit: run verify-36509f42 @ 414644c75af0
46
+ ```
47
+
48
+ That record says something narrow on purpose: *these findings were gone, and
49
+ these checks were observed to pass.* It is not a claim that your code is safe,
50
+ and Dvalin will not let it be read as one — every record carries what the scan
51
+ actually covered, and a repair no check could confirm does not pass.
52
+ [The open profile →](docs/spec/FIX-VERIFICATION.md)
53
+
54
+ Dvalin is the independent security runtime between code generation and merge.
55
+ Humans, coding agents, and CI call the same versioned contract for discovery,
56
+ remediation, and verification. It runs independently, or interoperates with
57
+ specialist systems such as Codex Security through portable SARIF. Its built-in
58
+ coding capability is a remediation executor — not the trust boundary, and not an
59
+ attempt to compete with every general-purpose coding agent. See the
60
+ [security-agent strategy](docs/SECURITY-AGENT-STRATEGY.md).
61
+
25
62
  ---
26
63
 
27
64
  ## ⏱️ 30 seconds, no install, no API key
28
65
 
29
66
  ```sh
30
- npx dvalincode dvalin .
67
+ npx dvalincode security scan .
68
+ # After installing the package: dvalin scan .
31
69
  ```
32
70
 
33
71
  That is the whole thing. It runs the built-in rules for injection, hardcoded
34
72
  secrets, XSS, `eval`, and unsafe shell use against the current directory and
35
73
  prints what it found. No account, no model, no config, no code leaves your
36
- machine. Add `--scanners builtin,semgrep,trivy,osv-scanner` to pull in whichever
37
- of those engines you already have on `PATH`.
74
+ machine. The default policy runs only Dvalin Built-in, so the first scan always
75
+ works. Add optional engines explicitly, or inspect their fixed install commands:
76
+
77
+ ```sh
78
+ dvalin scanners list
79
+ dvalin scanners install semgrep # review the command
80
+ dvalin scanners install semgrep --yes # execute it under Dvalin policy
81
+ ```
82
+
83
+ For an incremental “no new high-risk findings” gate, commit the policy and
84
+ baseline with the repository:
85
+
86
+ ```sh
87
+ dvalin init
88
+ dvalin baseline
89
+ dvalin scan
90
+ ```
91
+
92
+ This creates `dvalin.security.json` and `.dvalin/baseline.json`. Suppressions
93
+ require a reason and may have an owner and expiry date. Scan output is a
94
+ versioned envelope with a deterministic gate result and a resumable workflow ID.
38
95
 
39
96
  ### Or put it on every pull request — nothing to install at all
40
97
 
@@ -45,15 +102,52 @@ permissions:
45
102
  security-events: write
46
103
  steps:
47
104
  - uses: actions/checkout@v5
48
- - uses: arthurpanhku/dvalincode@v0.15.0
105
+ with:
106
+ fetch-depth: 0 # so the scan can reach the base commit
107
+ - uses: arthurpanhku/dvalincode@v0.18.0
49
108
  with:
50
109
  fail-on: high
110
+ diff: true # only report on what this PR changed
51
111
  ```
52
112
 
53
113
  Findings land inline on the pull request diff and in your Security tab.
54
114
  No API key, no secrets, no model — the scan is deterministic and local to the
55
115
  runner. [Full example →](docs/examples/dvalin-scan.yml)
56
116
 
117
+ `diff: true` reports only on lines the pull request changed, so the gate blocks
118
+ what this change *adds* instead of everything the repository already carried.
119
+ That is what makes the check adoptable on a codebase that was not clean to
120
+ begin with. Drop it to scan the whole repository.
121
+
122
+ Every comment states what the scan **covered** — `complete`, `partial`, or
123
+ `unknown` — beside the result, because "no findings" from a run where half the
124
+ engines were missing is not the same answer as "no findings" from a complete one.
125
+
126
+ ### And publish the proof next to the diff
127
+
128
+ If your pipeline produced a fix record, hand it to the same action:
129
+
130
+ ```yaml
131
+ - uses: arthurpanhku/dvalincode@v0.18.0
132
+ with:
133
+ fix-record: fix-record.json
134
+ ```
135
+
136
+ The runner re-derives the record from the file alone — recomputing its hash and
137
+ re-deriving its verdict from its own evidence — and posts the result on the pull
138
+ request. A record that was edited after it was issued fails here, and fails the
139
+ job. The reviewer does not have to trust the pipeline that produced it, or us.
140
+
141
+ ```
142
+ 🔏 Verified Fix Record
143
+ ✅ ce504a995395 · VERIFIED · scan-and-checks
144
+ - repaired by claude-code — recorded, and not consulted for this verdict
145
+ - targets: 1 before → 0 remaining
146
+ - coverage: complete → complete
147
+ - ✓ test: `npm run test` (exit 0)
148
+ - audit chain: verify-eeb1bae7 @ 80881867270d
149
+ ```
150
+
57
151
  ### Or let your agent call it
58
152
 
59
153
  If an agent is writing the code, something other than that agent has to check
@@ -63,12 +157,83 @@ it. DvalinCode is an MCP server, so any agent that speaks MCP can:
63
157
  claude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .
64
158
  ```
65
159
 
66
- `dvalin_scan` is read-only and deterministic — no model runs, no credentials are
67
- needed, no files are touched — so an agent can call it after every edit. A real
68
- call against a vulnerable fixture returns in ~170ms with a ~600 byte payload.
69
- The same server also exposes `dvalin_run_task` for delegating a whole governed
70
- task, plus the session and audit-evidence tools.
71
- [Agent integrations →](integrations/)
160
+ One command configures the editor you actually use:
161
+
162
+ ```sh
163
+ npx dvalincode mcp-install cursor # .cursor/mcp.json
164
+ npx dvalincode mcp-install vscode # .vscode/mcp.json
165
+ npx dvalincode mcp-install claude-code # .mcp.json
166
+ ```
167
+
168
+ The formats differ in a way that fails silently — VS Code keys its servers under
169
+ `servers`, Cursor under `mcpServers` — so the command writes the right one and
170
+ merges into whatever is already there. [Editors and MCP →](integrations/mcp/)
171
+
172
+ `dvalin_scan` accepts `diff: "uncommitted"`, which reports only on what the
173
+ agent just wrote rather than everything the repository already carried — the
174
+ 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`.
179
+
180
+ That last one is the point: an agent that has just written a repair can ask for
181
+ an independent verdict on it. Dvalin re-scans, runs the project's own checks
182
+ 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
186
+ receiving it does not have to trust the tool that issued it.
187
+ [FVP-1 →](docs/spec/FIX-VERIFICATION.md) Responses include MCP `structuredContent`; scanner
188
+ readiness is available through `dvalin_list_scanners`. The same server exposes
189
+ `dvalin_run_task` as an optional implementation helper, plus session and audit
190
+ evidence tools.
191
+
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/)
195
+
196
+ ### Wherever you already work
197
+
198
+ One server, reached the way each tool expects:
199
+
200
+ | Harness | How Dvalin reaches it |
201
+ |---|---|
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 |
204
+ | **Cursor** | `dvalincode mcp-install cursor` |
205
+ | **VS Code** | `dvalincode mcp-install vscode` · [extension](editors/vscode/) for the Problems panel — *built, not yet published* |
206
+ | **Windsurf · Zed** | stdio MCP through their own settings — [server command](integrations/mcp/) |
207
+ | **Any MCP client** | [MCP registry](https://registry.modelcontextprotocol.io/): `io.github.arthurpanhku/dvalincode` |
208
+ | **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings inline on the pull request diff |
209
+ | **Any CI** | `dvalin scan . --fail-on high`, SARIF out for code scanning |
210
+
211
+ The MCP config formats are not interchangeable — VS Code keys its servers under
212
+ `servers`, Cursor under `mcpServers`, and the wrong one fails silently — so
213
+ `mcp-install` writes the right shape and merges into whatever is already there.
214
+ [Editors and MCP →](integrations/mcp/)
215
+
216
+ ### Or interoperate with Codex Security
217
+
218
+ [Codex Security](https://github.com/openai/codex-security) can export a completed,
219
+ sealed scan as SARIF. Import that portable projection without coupling Dvalin to
220
+ Codex Security's private state directory:
221
+
222
+ ```sh
223
+ DVALIN_CODEX_SCAN_DIR=/tmp/codex-security-results
224
+ npx @openai/codex-security scan . --output-dir "$DVALIN_CODEX_SCAN_DIR"
225
+ npx @openai/codex-security export "$DVALIN_CODEX_SCAN_DIR" \
226
+ --export-format sarif --source-root "$PWD" --output /tmp/codex-security.sarif
227
+
228
+ dvalin import /tmp/codex-security.sarif .
229
+ dvalin scan . --fail-on high
230
+ ```
231
+
232
+ The import creates stable Dvalin remediation cases; `--no-persist` validates the
233
+ handoff without changing the backlog. Keep Codex Security's original manifest,
234
+ findings, and coverage artifacts together—Dvalin imports the SARIF finding
235
+ projection but does not rewrite its sealed bundle or reinterpret its coverage.
236
+ [Integration guide →](integrations/codex-security/)
72
237
 
73
238
  ### Then let it fix what it found
74
239
 
@@ -168,13 +333,14 @@ If you are the person who has to approve this class of tool, start at
168
333
 
169
334
  ## 🎯 Core Goal
170
335
 
171
- > **Make AI coding approvable for regulated and security-sensitive teams.**
336
+ > **Make every code-producing human or agent pass the same independent security gate.**
172
337
 
173
- DvalinCode is built as an **approvable agent runtime**, not just another coding
174
- agent app. The core product is not only "AI writes code"; it is the evidence a
175
- security, compliance, or platform team needs to safely allow AI coding in
176
- financial services, healthcare, internal enterprise platforms, and other
177
- confidential codebases.
338
+ DvalinCode is built as an **agent-compatible security runtime**, not another
339
+ general coding-agent benchmark entry. The core product is scan evidence,
340
+ policy, baseline, deterministic verification, and portable interfaces that a
341
+ human developer, an external agent, or CI can all call. The bundled coding agent
342
+ stays capable enough to implement and test focused remediations reliably; its
343
+ model prose never decides whether the security gate passed.
178
344
 
179
345
  - **Any model** — every OpenAI-compatible endpoint is a first-class citizen, local models included. Your workflow should never be hostage to one vendor's pricing, rate limits, or quality swings.
180
346
  - **Safe by default** — three-tier approvals with diff preview, an undo stack, and sandboxed shell execution. An agent you can trust on full-auto.
@@ -422,12 +588,12 @@ not claim third-party ISO certification.
422
588
  <img src="assets/hero.png" alt="Dvalin Security health showing 22/100 F with 4 high and 6 medium findings, and a Findings list locating each eval to a line in the NodeGoat-derived route" width="100%">
423
589
  </p>
424
590
 
425
- **The verified result — the three `eval` call sites replaced by a constrained
426
- numeric parser, one new injection regression test, all four open-source engines
427
- complete, 0 findings, 100/100 · A:**
591
+ **The verified result — a real model-driven Verify turn inspected the repair,
592
+ ran the regression tests and all four open-source engines, then the deterministic
593
+ server re-scan reported complete coverage, a passing gate, 0 findings, 100/100 · A:**
428
594
 
429
595
  <p align="center">
430
- <img src="assets/dvalin-scan-after.jpg" alt="Dvalin verified re-scan showing 100/100 A, zero findings, and the remediation run that produced it" width="100%">
596
+ <img src="assets/dvalin-verify-local.jpg" alt="A local Dvalin model-driven Verify run showing its test evidence beside a deterministic 100/100 A re-scan, complete four-engine coverage, and a passing gate" width="100%">
431
597
  </p>
432
598
 
433
599
  **Home → Code → Dvalin — the current workspaces:**
@@ -668,7 +834,7 @@ RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE
668
834
  npm test
669
835
  ```
670
836
 
671
- **323 tests · 49 files · all green.**
837
+ **442 tests · 62 files · all green.**
672
838
 
673
839
  ---
674
840
 
@@ -789,7 +955,7 @@ Contributions welcome. The codebase is intentionally small and surgical — see
789
955
  ```sh
790
956
  git clone https://github.com/arthurpanhku/dvalincode
791
957
  cd dvalincode && npm install
792
- npm test # 323/323 ✅
958
+ npm test # 442/442 ✅
793
959
  npm run typecheck
794
960
  ```
795
961
 
@@ -825,6 +991,10 @@ ecosystem:
825
991
  similar coding agents clarified user expectations around terminal agents,
826
992
  plan/build modes, permission prompts, project-local context, sandboxing,
827
993
  session lifecycle, MCP integration, and diff-first editing workflows.
994
+ - [OpenAI Codex Security](https://github.com/openai/codex-security) and its
995
+ public documentation informed Dvalin's specialist security-agent research and
996
+ portable SARIF handoff. Dvalin remains an independent, competing security
997
+ runtime.
828
998
  - The `AGENTS.md` project-instruction convention, common in coding-agent tools,
829
999
  informed DvalinCode's project-local instruction loading behavior.
830
1000
  - CodeQL, GitHub Code Scanning, Semgrep, SARIF, OpenSSF Scorecard, and ISO/IEC
@@ -842,31 +1012,20 @@ Full source references: [docs/REFERENCES.md](docs/REFERENCES.md)
842
1012
 
843
1013
  ---
844
1014
 
845
- ## ⭐ Star Growth
846
-
847
- <p align="center">
848
- <a href="https://www.star-history.com/#arthurpanhku/dvalincode&Date">
849
- <picture>
850
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=arthurpanhku/dvalincode&type=Date&theme=dark">
851
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=arthurpanhku/dvalincode&type=Date">
852
- <img alt="DvalinCode Star History Chart" src="https://api.star-history.com/svg?repos=arthurpanhku/dvalincode&type=Date">
853
- </picture>
854
- </a>
855
- </p>
856
-
857
- ---
858
-
859
1015
  ## 💛 Thanks to Our Contributors
860
1016
 
861
1017
  <p align="center">
862
1018
  Every issue, idea, documentation improvement, test, and code contribution helps make DvalinCode better.
863
1019
  </p>
864
1020
 
865
- <p align="center">
866
- <a href="https://github.com/arthurpanhku/dvalincode/graphs/contributors">
867
- <img src="https://contrib.rocks/image?repo=arthurpanhku/dvalincode" alt="DvalinCode contributors">
868
- </a>
869
- </p>
1021
+ | Contributor | GitHub profile |
1022
+ | --- | --- |
1023
+ | Arthur Pan | [@arthurpanhku](https://github.com/arthurpanhku) |
1024
+ | Shivas | [@shivasb42](https://github.com/shivasb42) |
1025
+ | Aditya | [@adity982](https://github.com/adity982) |
1026
+ | badhope | [@weed33834](https://github.com/weed33834) |
1027
+
1028
+ See the [complete contribution history](https://github.com/arthurpanhku/dvalincode/graphs/contributors), including automated dependency and maintenance updates.
870
1029
 
871
1030
  <p align="center">
872
1031
  <sub>Want to join them? Read the <a href="CONTRIBUTING.md">contribution guide</a> and send your first pull request.</sub>
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-323%20%2F%20323%20%E2%9C%93-success?style=for-the-badge" alt="Tests"></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>
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>
@@ -18,21 +18,71 @@
18
18
  </p>
19
19
 
20
20
  <p align="center">
21
- <b>找出仓库里的安全漏洞,修掉它,并且证明确实修好了 —— 一条命令。</b><br>
22
- 每一处修复都会先出 diff、跑测试、重新扫描,并写入防篡改审计日志,然后才允许变成 PR。
21
+ <b>为人类和 AI Agent 编写的代码提供开放安全工程能力。</b><br>
22
+ <b>每一次修复,都自带证明。</b>
23
23
  </p>
24
24
 
25
+ Agent 修好了一个安全问题之后,总得有人判断它到底修好没有。市面上几乎所有工具都是
26
+ 去问那个写下修复的模型 —— 而这恰恰是模型最无法违背自身利益去诚实回答的问题。
27
+
28
+ **Dvalin 自己来判断,并把证明交给你。** 它重新扫描、亲自跑你项目的测试,看的是它
29
+ 自己启动的进程返回的退出码。修复是谁写的 —— 我们的 agent、Claude Code、Codex、
30
+ Copilot,还是人 —— 只被记录,绝不参与判定。产物是一份 **Verified Fix Record**:
31
+ 一个很小的 JSON,任何人都能离线复验,不需要联网,也不需要任何 Dvalin 的本地状态。
32
+
33
+ ```sh
34
+ dvalin verify-fix fix-record.json
35
+ ```
36
+ ```
37
+ Fix record 2c9d71ac03e0 · VERIFIED · scan-and-checks
38
+ executor: claude-code (recorded, not consulted)
39
+ targets: 1 before · 0 remaining
40
+ coverage: complete → complete
41
+ ✓ test: npm run test (exit 0)
42
+ audit: run verify-36509f42 @ 414644c75af0
43
+ ```
44
+
45
+ 这份记录声称的东西刻意很窄:*这些 finding 消失了,这些检查被观察到通过了。* 它不是
46
+ 「你的代码安全了」这种断言,Dvalin 也不允许它被这样解读 —— 每份记录都带着这次扫描
47
+ 究竟覆盖了什么,而一个没有任何检查能确认的修复,不会通过。
48
+ [开放规范 →](docs/spec/FIX-VERIFICATION.md)
49
+
50
+ Dvalin 是放在“代码生成”和“允许合并”之间的独立安全运行时。人类开发者、Coding
51
+ Agent 和 CI 调用同一套版本化协议完成发现、修复与验证。它既可以独立运行,也可以通过
52
+ 可移植的 SARIF 与 Codex Security 等专业系统互操作。内置 Coding 能力只负责可靠地执行
53
+ 聚焦修复,不是安全结论的信任边界,也不以打败所有通用 Coding Agent 为目标。
54
+ 详见[安全 Agent 战略](docs/SECURITY-AGENT-STRATEGY.md)。
55
+
25
56
  ---
26
57
 
27
58
  ## ⏱️ 30 秒,免安装,不需要 API Key
28
59
 
29
60
  ```sh
30
- npx dvalincode dvalin .
61
+ npx dvalincode security scan .
62
+ # 安装 npm 包后也可直接运行:dvalin scan .
31
63
  ```
32
64
 
33
65
  就这一条。它用内置规则扫描当前目录里的注入、硬编码密钥、XSS、`eval` 和不安全的
34
66
  shell 调用,然后把结果打出来。不需要注册、不需要模型、不需要配置,代码不出本机。
35
- 想接入你已经装好的引擎,加上 `--scanners builtin,semgrep,trivy,osv-scanner` 即可。
67
+ 默认只启用一定存在的 Dvalin Built-in;可选引擎必须显式启用,其固定安装命令可以先审查:
68
+
69
+ ```sh
70
+ dvalin scanners list
71
+ dvalin scanners install semgrep # 只显示并审查命令
72
+ dvalin scanners install semgrep --yes # 在 Dvalin 策略约束下执行
73
+ ```
74
+
75
+ 要建立“禁止新增高风险问题”的增量门禁,把策略和基线一并提交到仓库:
76
+
77
+ ```sh
78
+ dvalin init
79
+ dvalin baseline
80
+ dvalin scan
81
+ ```
82
+
83
+ 这会创建 `dvalin.security.json` 和 `.dvalin/baseline.json`。每条 suppression 都必须
84
+ 写原因,还可以设置 owner 和过期时间。扫描输出是版本化 envelope,包含确定性 gate
85
+ 结果和可恢复的 workflow ID。
36
86
 
37
87
  ### 或者挂到每个 PR 上 —— 完全不用装任何东西
38
88
 
@@ -43,15 +93,50 @@ permissions:
43
93
  security-events: write
44
94
  steps:
45
95
  - uses: actions/checkout@v5
46
- - uses: arthurpanhku/dvalincode@v0.15.0
96
+ with:
97
+ fetch-depth: 0 # 让扫描能取到 base commit
98
+ - uses: arthurpanhku/dvalincode@v0.18.0
47
99
  with:
48
100
  fail-on: high
101
+ diff: true # 只报告这个 PR 改动的部分
49
102
  ```
50
103
 
51
104
  扫描结果会直接标注在 PR 的 diff 上,同时进入仓库的 Security 页。不需要 API Key、
52
105
  不需要任何 secret、不调用模型 —— 扫描是确定性的,且只在 runner 本地进行。
53
106
  [完整示例 →](docs/examples/dvalin-scan.yml)
54
107
 
108
+ `diff: true` 只报告 PR 改动到的行,因此这道门禁拦的是这次改动**新引入**的问题,
109
+ 而不是仓库里本来就有的一堆存量问题。这正是它能在一个并不干净的代码库上被接受的
110
+ 原因。去掉它就是全仓库扫描。
111
+
112
+ 每条评论都会在结论旁边写明这次扫描的**覆盖率** —— `complete` / `partial` /
113
+ `unknown`。因为「没发现问题」在半数引擎没装的情况下,和在完整扫描下,根本不是同一个
114
+ 答案。
115
+
116
+ ### 再把证明贴到 diff 旁边
117
+
118
+ 如果你的流水线产出了 fix record,把它交给同一个 action:
119
+
120
+ ```yaml
121
+ - uses: arthurpanhku/dvalincode@v0.18.0
122
+ with:
123
+ fix-record: fix-record.json
124
+ ```
125
+
126
+ runner 会仅凭这个文件本身重新推导它 —— 重算哈希,并从它自己的证据重新推出结论 ——
127
+ 然后把结果发到 PR 上。一份签发之后被改过的记录会在这里失败,并让整个 job 失败。
128
+ 审查者不需要信任产出它的流水线,也不需要信任我们。
129
+
130
+ ```
131
+ 🔏 Verified Fix Record
132
+ ✅ ce504a995395 · VERIFIED · scan-and-checks
133
+ - repaired by claude-code — recorded, and not consulted for this verdict
134
+ - targets: 1 before → 0 remaining
135
+ - coverage: complete → complete
136
+ - ✓ test: `npm run test` (exit 0)
137
+ - audit chain: verify-eeb1bae7 @ 80881867270d
138
+ ```
139
+
55
140
  ### 或者让你的 agent 调用它
56
141
 
57
142
  如果代码是 agent 写的,那检查它的就不能是同一个 agent。DvalinCode 本身是个 MCP
@@ -61,10 +146,65 @@ server,任何支持 MCP 的 agent 都能接:
61
146
  claude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .
62
147
  ```
63
148
 
64
- `dvalin_scan` 只读且确定性 —— 不跑模型、不需要任何凭据、不改文件 —— 所以 agent
65
- 可以每次改完就调一次。对一个真实漏洞样本的实测:约 170ms 返回,payload 约 600 字节。
66
- 同一个 server 还提供 `dvalin_run_task`(委派完整的受管任务)以及会话、审计证据工具。
67
- [Agent 集成 →](integrations/)
149
+ 一条命令配好你实际在用的编辑器:
150
+
151
+ ```sh
152
+ npx dvalincode mcp-install cursor # .cursor/mcp.json
153
+ npx dvalincode mcp-install vscode # .vscode/mcp.json
154
+ npx dvalincode mcp-install claude-code # .mcp.json
155
+ ```
156
+
157
+ 这几家的格式不一样,而且写错不会报错——VS Code 的 key 是 `servers`,Cursor 是
158
+ `mcpServers`,填反了编辑器会照单全收然后当没看见。这条命令会写对,并且合并进已有
159
+ 配置而不是覆盖。[编辑器与 MCP →](integrations/mcp/)
160
+
161
+ `dvalin_scan` 支持 `diff: "uncommitted"`,只报告 agent 刚写的部分,而不是仓库里的全部存量问题。它不跑模型,也不会修改目标 workspace;它只持久化一份精简的本地安全
162
+ workflow。Agent 可以用 fingerprint 精确读取单条发现,再通过 `dvalin_get_finding` 和
163
+ `dvalin_verify_findings` 请求独立复扫。响应包含 MCP `structuredContent`,并可通过
164
+ `dvalin_list_scanners` 查询组件是否就绪。同一 server 也提供可选的 `dvalin_run_task`
165
+ 实现助手,以及 session 和审计证据工具。
166
+
167
+ 已针对 Claude Code 2.1.226 和 Codex 0.147.0 做过端到端验证 —— 是用已发布的包真实发起
168
+ 工具调用,而不只是握手成功。[Agent 集成 →](integrations/)
169
+
170
+ ### 你在哪儿干活,它就在哪儿
171
+
172
+ 同一个 server,按每个工具各自的方式接进去:
173
+
174
+ | Harness | 怎么接 |
175
+ |---|---|
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/) |
178
+ | **Cursor** | `dvalincode mcp-install cursor` |
179
+ | **VS Code** | `dvalincode mcp-install vscode` · 在 Problems 面板出结果的[扩展](editors/vscode/) —— *已构建,尚未发布* |
180
+ | **Windsurf · Zed** | 在各自设置里配 stdio MCP —— [server 命令](integrations/mcp/) |
181
+ | **任意 MCP 客户端** | [MCP registry](https://registry.modelcontextprotocol.io/):`io.github.arthurpanhku/dvalincode` |
182
+ | **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) —— 结果直接标在 PR diff 上 |
183
+ | **任意 CI** | `dvalin scan . --fail-on high`,输出 SARIF 供 code scanning 用 |
184
+
185
+ 各家的 MCP 配置格式并不通用——VS Code 的 key 是 `servers`,Cursor 是 `mcpServers`,
186
+ 填错了不会报错只会静默失效——所以 `mcp-install` 会写对格式,并合并进已有配置。
187
+ [编辑器与 MCP →](integrations/mcp/)
188
+
189
+ ### 或者和 Codex Security 互操作
190
+
191
+ [Codex Security](https://github.com/openai/codex-security) 可以把已完成且密封的扫描
192
+ 导出为 SARIF。Dvalin 只导入这个可移植投影,不耦合 Codex Security 的私有状态目录:
193
+
194
+ ```sh
195
+ DVALIN_CODEX_SCAN_DIR=/tmp/codex-security-results
196
+ npx @openai/codex-security scan . --output-dir "$DVALIN_CODEX_SCAN_DIR"
197
+ npx @openai/codex-security export "$DVALIN_CODEX_SCAN_DIR" \
198
+ --export-format sarif --source-root "$PWD" --output /tmp/codex-security.sarif
199
+
200
+ dvalin import /tmp/codex-security.sarif .
201
+ dvalin scan . --fail-on high
202
+ ```
203
+
204
+ 导入会生成稳定的 Dvalin remediation case;`--no-persist` 可以只校验交接件而不修改
205
+ backlog。请继续保存 Codex Security 原始的 manifest、findings 和 coverage 工件——Dvalin
206
+ 只导入 SARIF finding 投影,不会改写其密封 bundle,也不会重新解释其覆盖率。
207
+ [集成指南 →](integrations/codex-security/)
68
208
 
69
209
  ### 然后让它把找到的问题修掉
70
210
 
@@ -155,11 +295,12 @@ dvalincode report verify # 重新推导上次运行审计日志的哈希链
155
295
 
156
296
  ## 🎯 核心目标
157
297
 
158
- > **让高合规与安全敏感团队也能批准 AI 编码。**
298
+ > **让每一个写代码的人类或 Agent,都通过同一套独立安全门禁。**
159
299
 
160
- DvalinCode 的定位是 **可审批的 Agent 运行时(runtime)**,而不只是又一个
161
- 编码 Agent 应用。核心产品不只是“AI 能写代码”,而是金融、医疗、政企、内部平台
162
- 等高保密代码库在引入 AI 编码前所需要的安全、合规和审计证据。
300
+ DvalinCode 的定位是 **Agent 可调用的安全运行时**,而不是又一个通用 Coding Agent
301
+ 榜单参赛者。核心产品是扫描证据、策略、基线、确定性验证,以及能被人类、外部 Agent
302
+ 和 CI 共同调用的便携接口。自带 Coding Agent 只需保持可靠完成聚焦修复和测试的能力;
303
+ 模型的文字声明永远不能决定安全 gate 是否通过。
163
304
 
164
305
  - **模型自由** —— 任何 OpenAI 兼容端点都是一等公民,包括本地模型。你的工作流不应被任何一家厂商的定价、限流或质量波动绑架。
165
306
  - **默认安全** —— 三档审批 + diff 预审、撤销栈、沙箱化 shell 执行。一个敢放心开全自动的 Agent。
@@ -357,11 +498,11 @@ DvalinCode 维护项目级治理证据,便于开源用户和企业安全评审
357
498
  <img src="assets/hero.png" alt="Dvalin 安全健康分显示 22/100 F、4 条高危与 6 条中危,Findings 列表把每处 eval 定位到 NodeGoat 改编路由的具体行" width="100%">
358
499
  </p>
359
500
 
360
- **验证后的结果——3 处 `eval` 调用改为受约束的数值解析、新增 1 条注入回归测试、
361
- 4 个开源引擎均完成,0 条发现,100/100 · A:**
501
+ **验证后的结果——真实模型驱动的 Verify 回合检查修复、运行回归测试和 4 个开源引擎,
502
+ 随后服务端确定性复扫显示完整覆盖、gate 通过、0 条发现、100/100 · A:**
362
503
 
363
504
  <p align="center">
364
- <img src="assets/dvalin-scan-after.jpg" alt="Dvalin 验证复扫显示 100/100 A、0 条发现,以及产生该结果的修复会话" width="100%">
505
+ <img src="assets/dvalin-verify-local.jpg" alt="Dvalin 本地真实模型 Verify 回合及其确定性复扫:100/100 A、四引擎完整覆盖、gate 通过、0 条发现" width="100%">
365
506
  </p>
366
507
 
367
508
  **Home → Code → Dvalin——当前三个工作区:**
@@ -589,7 +730,7 @@ RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE
589
730
  npm test
590
731
  ```
591
732
 
592
- **323 个测试 · 49 个文件 · 全部通过。**
733
+ **442 个测试 · 62 个文件 · 全部通过。**
593
734
 
594
735
  ---
595
736
 
@@ -716,7 +857,7 @@ Linux 与 macOS 命令通过 <code>/bin/sh</code> 执行;Windows 命令通过
716
857
  ```sh
717
858
  git clone https://github.com/arthurpanhku/dvalincode
718
859
  cd dvalincode && npm install
719
- npm test # 323/323 ✅
860
+ npm test # 442/442 ✅
720
861
  npm run typecheck
721
862
  ```
722
863
 
@@ -746,6 +887,9 @@ agentic coding 生态;DvalinCode 的产品方向和架构设计也受到了这
746
887
  - OpenAI Codex / Codex CLI、Claude Code、Aider、opencode、Cursor、Cline
747
888
  等编码 Agent 帮助明确了用户对终端 Agent、plan/build 模式、权限提示、
748
889
  项目本地上下文、沙箱、session lifecycle、MCP 集成和 diff-first 编辑工作流的期待。
890
+ - [OpenAI Codex Security](https://github.com/openai/codex-security) 及其公开文档为
891
+ Dvalin 的专业安全 Agent 研究和可移植 SARIF 交接提供了参考;Dvalin 仍是独立且参与
892
+ 竞争的安全运行时。
749
893
  - `AGENTS.md` 项目指令约定在编码 Agent 工具中较常见,也影响了 DvalinCode
750
894
  加载项目本地指令的行为设计。
751
895
  - CodeQL、GitHub Code Scanning、Semgrep、SARIF、OpenSSF Scorecard 与
@@ -761,31 +905,20 @@ prompt、UI 文案、工具 schema、模块布局和产品实现均为原创;
761
905
 
762
906
  ---
763
907
 
764
- ## ⭐ Star 增长趋势
765
-
766
- <p align="center">
767
- <a href="https://www.star-history.com/#arthurpanhku/dvalincode&Date">
768
- <picture>
769
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=arthurpanhku/dvalincode&type=Date&theme=dark">
770
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=arthurpanhku/dvalincode&type=Date">
771
- <img alt="DvalinCode Star 增长趋势图" src="https://api.star-history.com/svg?repos=arthurpanhku/dvalincode&type=Date">
772
- </picture>
773
- </a>
774
- </p>
775
-
776
- ---
777
-
778
908
  ## 💛 感谢每一位贡献者
779
909
 
780
910
  <p align="center">
781
911
  每一个 Issue、想法、文档改进、测试和代码贡献,都在帮助 DvalinCode 变得更好。
782
912
  </p>
783
913
 
784
- <p align="center">
785
- <a href="https://github.com/arthurpanhku/dvalincode/graphs/contributors">
786
- <img src="https://contrib.rocks/image?repo=arthurpanhku/dvalincode" alt="DvalinCode 贡献者">
787
- </a>
788
- </p>
914
+ | 贡献者 | GitHub 主页 |
915
+ | --- | --- |
916
+ | Arthur Pan | [@arthurpanhku](https://github.com/arthurpanhku) |
917
+ | Shivas | [@shivasb42](https://github.com/shivasb42) |
918
+ | Aditya | [@adity982](https://github.com/adity982) |
919
+ | badhope | [@weed33834](https://github.com/weed33834) |
920
+
921
+ 查看[完整贡献记录](https://github.com/arthurpanhku/dvalincode/graphs/contributors),其中也包含自动依赖更新和维护记录。
789
922
 
790
923
  <p align="center">
791
924
  <sub>也想加入?阅读<a href="CONTRIBUTING.md">贡献指南</a>,提交你的第一个 Pull Request。</sub>