dvalincode 0.21.0 → 0.23.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 +261 -27
- package/README.zh-CN.md +203 -23
- package/dist/agent/compact.d.ts +8 -0
- package/dist/agent/compact.js +44 -5
- package/dist/agent/compact.js.map +1 -1
- package/dist/agent/loop.d.ts +5 -0
- package/dist/agent/loop.js +18 -9
- package/dist/agent/loop.js.map +1 -1
- package/dist/agent/runner.d.ts +15 -3
- package/dist/agent/runner.js +99 -9
- package/dist/agent/runner.js.map +1 -1
- package/dist/agent/session.d.ts +7 -0
- package/dist/agent/session.js +32 -4
- package/dist/agent/session.js.map +1 -1
- package/dist/agent/types.d.ts +5 -1
- package/dist/agent/types.js.map +1 -1
- package/dist/audit/log.d.ts +5 -1
- package/dist/audit/log.js.map +1 -1
- package/dist/cli.js +2 -0
- package/dist/cli.js.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.js +223 -0
- package/dist/commands/agents.js.map +1 -0
- package/dist/commands/dvalin.d.ts +7 -1
- package/dist/commands/dvalin.js +209 -9
- package/dist/commands/dvalin.js.map +1 -1
- package/dist/commands/mcpInstall.d.ts +24 -0
- package/dist/commands/mcpInstall.js +62 -17
- package/dist/commands/mcpInstall.js.map +1 -1
- package/dist/commands/provider.js +6 -1
- package/dist/commands/provider.js.map +1 -1
- package/dist/commands/run.js +4 -2
- package/dist/commands/run.js.map +1 -1
- package/dist/commands/security.d.ts +15 -0
- package/dist/commands/security.js +273 -22
- package/dist/commands/security.js.map +1 -1
- package/dist/dvalinCli.js +2 -0
- package/dist/dvalinCli.js.map +1 -1
- package/dist/harness/run.d.ts +8 -2
- package/dist/harness/run.js +1 -1
- package/dist/harness/run.js.map +1 -1
- package/dist/mcp/agents.d.ts +41 -0
- package/dist/mcp/agents.js +129 -0
- package/dist/mcp/agents.js.map +1 -0
- package/dist/mcp/install.d.ts +43 -6
- package/dist/mcp/install.js +104 -1
- package/dist/mcp/install.js.map +1 -1
- package/dist/mcp/server.js +10 -2
- package/dist/mcp/server.js.map +1 -1
- package/dist/providers/anthropic.js +14 -2
- package/dist/providers/anthropic.js.map +1 -1
- package/dist/providers/openaiCompatible.js +7 -6
- package/dist/providers/openaiCompatible.js.map +1 -1
- package/dist/providers/retry.d.ts +32 -0
- package/dist/providers/retry.js +150 -0
- package/dist/providers/retry.js.map +1 -0
- package/dist/providers/trustedBaseUrls.js +1 -1
- package/dist/providers/trustedBaseUrls.js.map +1 -1
- package/dist/providers/types.d.ts +10 -0
- package/dist/remediation/automate.d.ts +1 -1
- package/dist/remediation/automate.js +2 -1
- package/dist/remediation/automate.js.map +1 -1
- package/dist/remediation/cases.d.ts +1 -0
- package/dist/remediation/cases.js +1 -0
- package/dist/remediation/cases.js.map +1 -1
- package/dist/remediation/codeQualityExport.d.ts +25 -0
- package/dist/remediation/codeQualityExport.js +24 -0
- package/dist/remediation/codeQualityExport.js.map +1 -0
- package/dist/remediation/codexSecurity.d.ts +54 -0
- package/dist/remediation/codexSecurity.js +366 -0
- package/dist/remediation/codexSecurity.js.map +1 -0
- package/dist/remediation/evasion.d.ts +61 -0
- package/dist/remediation/evasion.js +190 -0
- package/dist/remediation/evasion.js.map +1 -0
- package/dist/remediation/fixLoop.d.ts +255 -0
- package/dist/remediation/fixLoop.js +639 -0
- package/dist/remediation/fixLoop.js.map +1 -0
- package/dist/remediation/fixLoopStats.d.ts +93 -0
- package/dist/remediation/fixLoopStats.js +244 -0
- package/dist/remediation/fixLoopStats.js.map +1 -0
- package/dist/remediation/rebase.d.ts +44 -0
- package/dist/remediation/rebase.js +114 -0
- package/dist/remediation/rebase.js.map +1 -0
- package/dist/remediation/reproduce.d.ts +47 -0
- package/dist/remediation/reproduce.js +75 -0
- package/dist/remediation/reproduce.js.map +1 -0
- package/dist/remediation/sarif.d.ts +14 -1
- package/dist/remediation/sarif.js +21 -3
- package/dist/remediation/sarif.js.map +1 -1
- package/dist/remediation/scannerSuite.d.ts +52 -3
- package/dist/remediation/scannerSuite.js +347 -88
- package/dist/remediation/scannerSuite.js.map +1 -1
- package/dist/remediation/verify.d.ts +8 -0
- package/dist/remediation/verify.js +24 -11
- package/dist/remediation/verify.js.map +1 -1
- package/dist/security/config.d.ts +8 -2
- package/dist/security/config.js +10 -3
- package/dist/security/config.js.map +1 -1
- package/dist/security/contracts.js +15 -0
- package/dist/security/contracts.js.map +1 -1
- package/dist/security/fixRecord.d.ts +103 -8
- package/dist/security/fixRecord.js +113 -11
- package/dist/security/fixRecord.js.map +1 -1
- package/dist/security/fixRecordFile.d.ts +11 -2
- package/dist/security/fixRecordFile.js +20 -2
- package/dist/security/fixRecordFile.js.map +1 -1
- package/dist/security/fixRecordSignature.d.ts +104 -0
- package/dist/security/fixRecordSignature.js +227 -0
- package/dist/security/fixRecordSignature.js.map +1 -0
- package/dist/security/guardedScan.d.ts +39 -0
- package/dist/security/guardedScan.js +45 -0
- package/dist/security/guardedScan.js.map +1 -0
- package/dist/security/onboarding.d.ts +28 -0
- package/dist/security/onboarding.js +124 -0
- package/dist/security/onboarding.js.map +1 -0
- package/dist/security/reproduceInCi.d.ts +44 -0
- package/dist/security/reproduceInCi.js +96 -0
- package/dist/security/reproduceInCi.js.map +1 -0
- package/dist/security/reverify.d.ts +130 -0
- package/dist/security/reverify.js +361 -0
- package/dist/security/reverify.js.map +1 -0
- package/dist/security/suppressionGuard.d.ts +58 -0
- package/dist/security/suppressionGuard.js +216 -0
- package/dist/security/suppressionGuard.js.map +1 -0
- package/dist/security/verifyRun.js +14 -3
- package/dist/security/verifyRun.js.map +1 -1
- package/dist/security/workflow.d.ts +11 -1
- package/dist/security/workflow.js +2 -0
- package/dist/security/workflow.js.map +1 -1
- package/dist/server/routes/config.js +2 -0
- package/dist/server/routes/config.js.map +1 -1
- package/dist/server/routes/remediation.js +6 -5
- package/dist/server/routes/remediation.js.map +1 -1
- package/dist/tools/editFile.js +9 -2
- package/dist/tools/editFile.js.map +1 -1
- package/dist/tools/registry.d.ts +4 -1
- package/dist/tools/registry.js +29 -9
- package/dist/tools/registry.js.map +1 -1
- package/dist/tools/runSecuritySuite.d.ts +3 -0
- package/dist/tools/runSecuritySuite.js +2 -2
- package/dist/tools/runSecuritySuite.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -64,7 +64,7 @@ finds something.
|
|
|
64
64
|
Dvalin is the independent security runtime between code generation and merge.
|
|
65
65
|
Humans, coding agents, and CI call the same versioned contract for discovery,
|
|
66
66
|
remediation, and verification. It runs independently, or interoperates with
|
|
67
|
-
specialist systems such as Codex Security through portable SARIF. Its built-in
|
|
67
|
+
specialist systems such as Codex Security through sealed scan artifacts or portable SARIF. Its built-in
|
|
68
68
|
coding capability is a remediation executor — not the trust boundary, and not an
|
|
69
69
|
attempt to compete with every general-purpose coding agent. See the
|
|
70
70
|
[security-agent strategy](docs/SECURITY-AGENT-STRATEGY.md).
|
|
@@ -90,6 +90,155 @@ dvalin scanners install semgrep # review the command
|
|
|
90
90
|
dvalin scanners install semgrep --yes # execute it under Dvalin policy
|
|
91
91
|
```
|
|
92
92
|
|
|
93
|
+
### Make it the gate in one step
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
dvalin init
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`init` writes `dvalin.security.json` (fail on *new* findings at high or above),
|
|
100
|
+
names the checks your project actually has (`test`, `typecheck`, `build`,
|
|
101
|
+
`lint`) as what Dvalin runs before it calls a fix verified, records today's
|
|
102
|
+
findings as the accepted backlog in `.dvalin/baseline.json`, and writes a CI
|
|
103
|
+
gate for GitHub (`.github/workflows/dvalin.yml`) or GitLab
|
|
104
|
+
(`.gitlab/dvalin-security.yml`, with a Code Quality report for the merge
|
|
105
|
+
request widget). It never overwrites a file that is already there unless you
|
|
106
|
+
pass `--force`. Commit what it wrote, and the backlog stops blocking anyone:
|
|
107
|
+
only what a change adds fails.
|
|
108
|
+
|
|
109
|
+
To gate every commit locally too, add the [pre-commit](https://pre-commit.com) hook:
|
|
110
|
+
|
|
111
|
+
```yaml
|
|
112
|
+
# .pre-commit-config.yaml
|
|
113
|
+
repos:
|
|
114
|
+
- repo: https://github.com/arthurpanhku/dvalincode
|
|
115
|
+
rev: v0.22.0 # the hook ships in v0.22.0
|
|
116
|
+
hooks:
|
|
117
|
+
- id: dvalin-scan # or dvalin-scan-installed, to use the CLI you installed
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Measure with the scanner your CI gate uses
|
|
121
|
+
|
|
122
|
+
If Snyk is what blocks your merges, verify against Snyk. A fix judged "clean"
|
|
123
|
+
by a different engine is a fix the gate can still reject, and that mismatch is
|
|
124
|
+
what turns one agent repair into several rounds of push, fail, and rebase.
|
|
125
|
+
|
|
126
|
+
```sh
|
|
127
|
+
npm install -g snyk && snyk auth # or set SNYK_TOKEN
|
|
128
|
+
dvalin scan . --scanners builtin,snyk-code,snyk-oss
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`snyk-code` (SAST) and `snyk-oss` (dependencies) are engines like any other:
|
|
132
|
+
their findings carry the same fingerprints, coverage and gate, and a failed
|
|
133
|
+
login is reported as an engine error, which makes the scan `partial`, never
|
|
134
|
+
clean. They run only when named, because Snyk Code uploads source to Snyk.
|
|
135
|
+
Name them in `dvalin.security.json` to make them part of the policy, and
|
|
136
|
+
`reverify` will judge every fix with them.
|
|
137
|
+
|
|
138
|
+
If GitHub code scanning is the gate, use CodeQL the same way:
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
dvalin scan . --scanners builtin,codeql
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`codeql` builds one database per language outside the workspace and runs that
|
|
145
|
+
language's default code-scanning queries, so its findings are the ones the gate
|
|
146
|
+
reports. JavaScript/TypeScript, Python, Ruby, Java and C# are analysed without a
|
|
147
|
+
build; Go uses CodeQL's autobuild. Kotlin, C/C++ and Swift need the project's own
|
|
148
|
+
build, so when they are in the tree the run says so and the scan is `partial`,
|
|
149
|
+
not clean. It runs only when named — a database takes minutes, not seconds, and
|
|
150
|
+
the CodeQL CLI's license covers open-source code and GitHub Advanced Security
|
|
151
|
+
customers.
|
|
152
|
+
|
|
153
|
+
Ignores Snyk itself reports as accepted are honored and listed as coverage
|
|
154
|
+
exclusions. Ignores **the change under review adds** are not: when a fix is
|
|
155
|
+
judged, `.snyk`, `.semgrepignore`, `.trivyignore` and `.dvalincodeignore` are
|
|
156
|
+
restored to the base commit's version and new inline markers (`deepcode
|
|
157
|
+
ignore`, `nosemgrep`, `nosec`, `NOSONAR`, …) are blanked, so a finding that was
|
|
158
|
+
silenced rather than fixed still fails the fix. A suppression is a risk
|
|
159
|
+
decision a person makes in its own change, never a repair.
|
|
160
|
+
|
|
161
|
+
The same judgement applies wherever Dvalin says "verified": the fix loop,
|
|
162
|
+
`dvalin verify`, the MCP `dvalin_verify_findings` tool, single-round
|
|
163
|
+
`--fix --verify`, and CI `reverify`. Those records are `dvalin-fix-record/v3`,
|
|
164
|
+
which also fails a repair that hid a finding instead of fixing it — a sibling
|
|
165
|
+
sink, a deleted vulnerable file, deleted tests or assertions. Outside a git
|
|
166
|
+
repository, where the change cannot be determined, records stay v2 and say
|
|
167
|
+
that evasion was not evaluated.
|
|
168
|
+
|
|
169
|
+
### Let it loop until the gate would pass
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean --max-rounds 3 --executor codex
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`--until-clean` turns one fix attempt into a bounded loop. The executor edits;
|
|
176
|
+
Dvalin re-scans with the same engines and runs the project's checks itself;
|
|
177
|
+
the executor is sent **only what is still wrong** — targets still present,
|
|
178
|
+
findings its change introduced, failing checks with their last lines of
|
|
179
|
+
output, suppressions it added — and fixes again. Dependency findings go first.
|
|
180
|
+
|
|
181
|
+
The loop stops, and says which, when every target is gone with nothing
|
|
182
|
+
blocking introduced and every check passing (`verified`), when the round
|
|
183
|
+
budget runs out, when a round leaves the same problems open or the open set
|
|
184
|
+
stops shrinking (`stalled`), when the targets need a person — a dependency
|
|
185
|
+
with no fixed version (`not-auto-fixable`) — or when the engines or checks
|
|
186
|
+
cannot run (`unverifiable`). Suppressions the executor adds are undone before
|
|
187
|
+
each scan and stay open problems until removed. Every outcome issues a fix
|
|
188
|
+
record, and every round is logged under `~/.dvalincode/security/fix-loops/`;
|
|
189
|
+
`dvalin loop-stats` summarizes those logs — how often loops reach `verified`,
|
|
190
|
+
the median and p90 rounds to green, which stop rule fired, and what was still
|
|
191
|
+
open when a loop stalled (`--json`, `--since`, `--executor` to slice it).
|
|
192
|
+
|
|
193
|
+
Rounds are kept short without changing what decides them. The engines run side
|
|
194
|
+
by side, so a scan costs the slowest engine rather than the sum. Between rounds,
|
|
195
|
+
the engines that analyse one file at a time (Dvalin Built-in, Semgrep) rescan
|
|
196
|
+
only the files the change touched and the files the targets are in; the others
|
|
197
|
+
always scan the whole tree. That narrowed scan only steers the executor: any
|
|
198
|
+
round that would stop the loop is re-judged on a full scan of the same tree, and
|
|
199
|
+
only the full scan decides the outcome and goes into the record.
|
|
200
|
+
`--full-rescan` scans everything every round, and `loop-stats` reports scan time
|
|
201
|
+
per round and how often a full scan changed the decision.
|
|
202
|
+
|
|
203
|
+
For **code** findings the loop first asks for a reproduction: tests only, which
|
|
204
|
+
Dvalin runs on the unfixed code and requires to fail — by a failing assertion,
|
|
205
|
+
not a missing runner or a not-yet-written import. The tests are hashed; the
|
|
206
|
+
fix must then make them pass **unchanged**, and that run is a check in the
|
|
207
|
+
record. A finding no test could demonstrate stops the loop as
|
|
208
|
+
`not-reproduced` before anything is fixed: it may be a false positive, and a
|
|
209
|
+
person triages it. The runner is inferred (vitest, jest, mocha, `node --test`,
|
|
210
|
+
pytest, `go test`) or set with `--repro-command 'npx vitest run {files}'` or
|
|
211
|
+
`reproduce` in `dvalin.security.json` — never chosen by the executor.
|
|
212
|
+
|
|
213
|
+
Each fix round also rejects the evasions an agent reaches for when the goal is
|
|
214
|
+
"the scanner went quiet": moving the sink to a sibling (`eval` →
|
|
215
|
+
`new Function`, `exec` → `spawn` with `shell: true`), deleting the vulnerable
|
|
216
|
+
file, deleting tests, removing assertions. In practice the scanner alone is
|
|
217
|
+
fooled by the first one — the rule stops matching — and the reproduction test
|
|
218
|
+
and the evasion check are what catch it.
|
|
219
|
+
|
|
220
|
+
### Keep it on today's main, and close it in CI
|
|
221
|
+
|
|
222
|
+
```sh
|
|
223
|
+
dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean \
|
|
224
|
+
--rebase-onto origin/main --executor codex --draft-pr --sign-key ci.key
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
With `--rebase-onto` the loop fetches and rebases the fix onto upstream before
|
|
228
|
+
it starts and after every round, then judges it there. Conflicts go to the
|
|
229
|
+
executor — the conflicted files only, with "do not run git" — and Dvalin
|
|
230
|
+
continues the rebase itself; markers left in a file are a conflict not
|
|
231
|
+
resolved. If they cannot be resolved the rebase is aborted, the tree is left as
|
|
232
|
+
it was, and the loop stops as `rebase-conflict`. After each rebase the baseline
|
|
233
|
+
is re-scanned on the new base, so a finding a teammate landed on main is not
|
|
234
|
+
blamed on the fix.
|
|
235
|
+
|
|
236
|
+
`--draft-pr` commits the record at `.dvalin/fix-record.json`, and
|
|
237
|
+
[`docs/examples/dvalin-fix-loop.yml`](docs/examples/dvalin-fix-loop.yml)
|
|
238
|
+
re-executes it on the pull request with `reverify: true`: base and head
|
|
239
|
+
re-scanned, checks re-run, and the reproduction re-run with the fix reverted in
|
|
240
|
+
place (it must fail) and restored (it must pass) — then signed with the CI key.
|
|
241
|
+
|
|
93
242
|
For an incremental “no new high-risk findings” gate, commit the policy and
|
|
94
243
|
baseline with the repository:
|
|
95
244
|
|
|
@@ -114,7 +263,7 @@ steps:
|
|
|
114
263
|
- uses: actions/checkout@v5
|
|
115
264
|
with:
|
|
116
265
|
fetch-depth: 0 # so the scan can reach the base commit
|
|
117
|
-
- uses: arthurpanhku/dvalincode@v0.
|
|
266
|
+
- uses: arthurpanhku/dvalincode@v0.22.0
|
|
118
267
|
with:
|
|
119
268
|
fail-on: high
|
|
120
269
|
diff: true # only report on what this PR changed
|
|
@@ -138,7 +287,7 @@ engines were missing is not the same answer as "no findings" from a complete one
|
|
|
138
287
|
If your pipeline produced a fix record, hand it to the same action:
|
|
139
288
|
|
|
140
289
|
```yaml
|
|
141
|
-
- uses: arthurpanhku/dvalincode@v0.
|
|
290
|
+
- uses: arthurpanhku/dvalincode@v0.22.0
|
|
142
291
|
with:
|
|
143
292
|
fix-record: fix-record.json
|
|
144
293
|
```
|
|
@@ -146,7 +295,13 @@ If your pipeline produced a fix record, hand it to the same action:
|
|
|
146
295
|
The runner re-derives the record from the file alone — recomputing its hash and
|
|
147
296
|
re-deriving its verdict from its own evidence — and posts the result on the pull
|
|
148
297
|
request. A record that was edited after it was issued fails here, and fails the
|
|
149
|
-
job.
|
|
298
|
+
job.
|
|
299
|
+
|
|
300
|
+
Re-derivation proves the record is *self-consistent*. It cannot prove the record
|
|
301
|
+
was issued by anyone who actually ran anything: every field in it, the exit
|
|
302
|
+
codes included, is something a forger could write, and a self-consistent
|
|
303
|
+
forgery re-derives. Two things close that gap — re-execute the claim on the
|
|
304
|
+
runner, and sign what the runner observed.
|
|
150
305
|
|
|
151
306
|
```
|
|
152
307
|
🔏 Verified Fix Record
|
|
@@ -169,6 +324,52 @@ A repair that regressed says so in the same place, and fails the job with it:
|
|
|
169
324
|
- outcome: regressed
|
|
170
325
|
```
|
|
171
326
|
|
|
327
|
+
### Re-execute it on the runner, and sign what you saw
|
|
328
|
+
|
|
329
|
+
```yaml
|
|
330
|
+
- uses: actions/checkout@v5
|
|
331
|
+
with:
|
|
332
|
+
fetch-depth: 0 # the base commit has to be reachable
|
|
333
|
+
- run: npm ci # the project's checks run on the runner
|
|
334
|
+
- uses: arthurpanhku/dvalincode@v0.22.0 # reverify ships in v0.22.0; until it is tagged, pin a main commit SHA
|
|
335
|
+
with:
|
|
336
|
+
fix-record: fix-record.json
|
|
337
|
+
reverify: true
|
|
338
|
+
signing-key: ${{ secrets.DVALIN_SIGNING_KEY }} # optional
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
With `reverify: true` the claimed record contributes only *which targets* it
|
|
342
|
+
says it fixed and *who* the executor was. Everything else is observed again:
|
|
343
|
+
|
|
344
|
+
- the **base** commit is checked out and scanned, so each claimed target must
|
|
345
|
+
actually have existed there — a record cannot take credit for removing a
|
|
346
|
+
finding nobody had;
|
|
347
|
+
- the **head** is scanned, so "gone" is observed on the runner;
|
|
348
|
+
- the project's checks are run on the runner, with the checks, gate and
|
|
349
|
+
scanners read from the **base** commit's `dvalin.security.json` — a pull
|
|
350
|
+
request that relaxes its own gate or deletes its own checks is judged under
|
|
351
|
+
the rules it is trying to change;
|
|
352
|
+
- a fresh record is issued from those observations, and the job fails unless it
|
|
353
|
+
verifies.
|
|
354
|
+
|
|
355
|
+
With `signing-key` the fresh record is signed (Ed25519, over its hash). The key
|
|
356
|
+
is taken into memory and removed from the environment before the project's
|
|
357
|
+
checks run, so the code under review cannot read it. Downstream — a release
|
|
358
|
+
job, another repository, an auditor — can then require that signature:
|
|
359
|
+
|
|
360
|
+
```sh
|
|
361
|
+
dvalin keygen --out ci # once; store ci.key as a secret, publish ci.pub
|
|
362
|
+
dvalin verify-fix record.json --trusted-key ci.pub
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
A record that is unsigned, or signed only by a key you did not name, fails
|
|
366
|
+
under `--trusted-key`. A valid signature says *which key vouched for this
|
|
367
|
+
record*; whether that key deserves trust is your decision, and the reason to
|
|
368
|
+
trust a CI key is that the CI job re-executed the verification rather than
|
|
369
|
+
copying it. Locally, `dvalin reverify <record> --base origin/main` runs the same
|
|
370
|
+
re-execution, and `dvalin sign-fix` signs a record that re-derives.
|
|
371
|
+
[FVP-1 §4a, §5a →](docs/spec/FIX-VERIFICATION.md)
|
|
372
|
+
|
|
172
373
|
### Or let your agent call it
|
|
173
374
|
|
|
174
375
|
If an agent is writing the code, something other than that agent has to check
|
|
@@ -181,15 +382,35 @@ claude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .
|
|
|
181
382
|
One command configures the editor you actually use:
|
|
182
383
|
|
|
183
384
|
```sh
|
|
385
|
+
npx dvalincode mcp-install codex # ~/.codex/config.toml, via `codex mcp add`
|
|
184
386
|
npx dvalincode mcp-install cursor # .cursor/mcp.json
|
|
185
387
|
npx dvalincode mcp-install vscode # .vscode/mcp.json
|
|
186
388
|
npx dvalincode mcp-install claude-code # .mcp.json
|
|
389
|
+
npx dvalincode mcp-install gemini # .gemini/settings.json
|
|
390
|
+
npx dvalincode mcp-install opencode # opencode.json
|
|
187
391
|
```
|
|
188
392
|
|
|
189
|
-
|
|
393
|
+
For Codex, Dvalin delegates to the official `codex mcp add` command, so it safely
|
|
394
|
+
updates TOML without hand-editing user configuration. The other formats differ
|
|
395
|
+
in a way that fails silently — VS Code keys its servers under
|
|
190
396
|
`servers`, Cursor under `mcpServers` — so the command writes the right one and
|
|
191
397
|
merges into whatever is already there. [Editors and MCP →](integrations/mcp/)
|
|
192
398
|
|
|
399
|
+
Or let Dvalin find them. `agents` lists the coding agents on this machine and
|
|
400
|
+
where Dvalin is already connected; `agents connect` plans the rest, and writes
|
|
401
|
+
nothing until you add `--yes`:
|
|
402
|
+
|
|
403
|
+
```sh
|
|
404
|
+
npx dvalincode agents # which agents are here, and which have Dvalin
|
|
405
|
+
npx dvalincode agents connect # the plan: what each agent gets
|
|
406
|
+
npx dvalincode agents connect --yes # apply it
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
If you manage MCP servers with [CC Switch](https://github.com/farion1231/cc-switch),
|
|
410
|
+
`agents connect cc-switch --yes` hands Dvalin to it instead. CC Switch shows the
|
|
411
|
+
import, asks first, then syncs Dvalin into Claude Code, Codex, Gemini CLI and
|
|
412
|
+
OpenCode.
|
|
413
|
+
|
|
193
414
|
`dvalin_scan` accepts `diff: "uncommitted"`, which reports only on what the
|
|
194
415
|
agent just wrote rather than everything the repository already carried — the
|
|
195
416
|
difference between a usable answer and a wall of pre-existing findings. It never
|
|
@@ -217,10 +438,13 @@ handshake — which client, which version, and on what date is a table rather
|
|
|
217
438
|
than a sentence, because hand-written version numbers go stale quietly.
|
|
218
439
|
[Integration support ↓](#-integration-support) · [Agent integrations →](integrations/)
|
|
219
440
|
|
|
220
|
-
The repository also contains one [
|
|
221
|
-
with
|
|
222
|
-
|
|
223
|
-
|
|
441
|
+
The repository also contains one [portable Codex/Claude plugin payload](integrations/dvalin-security/)
|
|
442
|
+
with the current root Agent Plugins manifest, compatibility manifests, the
|
|
443
|
+
shared security-gate skill, and a Claude-compatible MCP configuration. A repo-local
|
|
444
|
+
marketplace makes it discoverable in Codex desktop; installing it lets task
|
|
445
|
+
context trigger the gate instead of requiring every developer to remember a scan prompt.
|
|
446
|
+
For Codex, `mcp-install codex` separately binds the server to the active project;
|
|
447
|
+
the plugin does not risk scanning its own installed cache directory.
|
|
224
448
|
Codex honors the scan's read-only MCP annotation. Claude Code requires one
|
|
225
449
|
explicit MCP permission by design; the plugin documents the exact scan-only
|
|
226
450
|
allow rule instead of asking users to bypass all permissions.
|
|
@@ -231,40 +455,44 @@ One server, reached the way each tool expects:
|
|
|
231
455
|
|
|
232
456
|
| Harness | How Dvalin reaches it |
|
|
233
457
|
|---|---|
|
|
234
|
-
| **Claude Code** | [
|
|
235
|
-
| **Codex** | [
|
|
458
|
+
| **Claude Code** | [portable plugin](integrations/dvalin-security/) or `claude mcp add` · [standalone skill](integrations/claude-code/) |
|
|
459
|
+
| **Codex** | `dvalincode mcp-install codex` · [portable plugin](integrations/dvalin-security/) · [sealed scan + SARIF interop](integrations/codex-security/) with Codex Security |
|
|
236
460
|
| **Cursor** | `dvalincode mcp-install cursor` |
|
|
237
461
|
| **VS Code** | `dvalincode mcp-install vscode` · [extension](editors/vscode/) for Problems, coverage/gate status, and offline VFR verification — *built, not yet published* |
|
|
462
|
+
| **Gemini CLI** | `dvalincode mcp-install gemini` |
|
|
463
|
+
| **OpenCode** | `dvalincode mcp-install opencode` |
|
|
464
|
+
| **CC Switch** | `dvalin agents connect cc-switch` — one import, synced into each agent CC Switch manages |
|
|
238
465
|
| **Windsurf · Zed** | stdio MCP through their own settings — [server command](integrations/mcp/) |
|
|
239
466
|
| **Any MCP client** | [MCP registry](https://registry.modelcontextprotocol.io/): `io.github.arthurpanhku/dvalincode` |
|
|
240
467
|
| **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings inline on the pull request diff |
|
|
468
|
+
| **GitLab CI** | `dvalin init --ci gitlab` — new findings gate the merge request, shown in its Code Quality widget |
|
|
469
|
+
| **pre-commit** | [`dvalin-scan` hook](.pre-commit-hooks.yaml) — the same policy gate before every commit |
|
|
241
470
|
| **Any CI** | `dvalin scan . --fail-on high`, SARIF out for code scanning |
|
|
242
471
|
|
|
243
|
-
The MCP config formats are not interchangeable —
|
|
244
|
-
|
|
472
|
+
The MCP config formats are not interchangeable — Codex uses TOML through its own
|
|
473
|
+
CLI, VS Code keys its servers under
|
|
474
|
+
`servers`, Cursor under `mcpServers`, OpenCode under `mcp` with the command line
|
|
475
|
+
in one array, and the wrong one fails silently — so
|
|
245
476
|
`mcp-install` writes the right shape and merges into whatever is already there.
|
|
246
477
|
[Editors and MCP →](integrations/mcp/)
|
|
247
478
|
|
|
248
479
|
### Or interoperate with Codex Security
|
|
249
480
|
|
|
250
|
-
[Codex Security](https://github.com/openai/codex-security)
|
|
251
|
-
sealed
|
|
252
|
-
|
|
481
|
+
[Codex Security](https://github.com/openai/codex-security) writes completed,
|
|
482
|
+
sealed scans with a manifest, structured findings, and coverage. Import those
|
|
483
|
+
portable artifacts without coupling Dvalin to its private application state:
|
|
253
484
|
|
|
254
485
|
```sh
|
|
255
486
|
DVALIN_CODEX_SCAN_DIR=/tmp/codex-security-results
|
|
256
487
|
npx @openai/codex-security scan . --output-dir "$DVALIN_CODEX_SCAN_DIR"
|
|
257
|
-
|
|
258
|
-
--export-format sarif --source-root "$PWD" --output /tmp/codex-security.sarif
|
|
259
|
-
|
|
260
|
-
dvalin import /tmp/codex-security.sarif .
|
|
488
|
+
dvalin import "$DVALIN_CODEX_SCAN_DIR" .
|
|
261
489
|
dvalin scan . --fail-on high
|
|
262
490
|
```
|
|
263
491
|
|
|
264
|
-
The import
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
492
|
+
The import verifies manifest-recorded artifact hashes, creates stable Dvalin
|
|
493
|
+
remediation cases, and reports exclusions and deferred work as explicit
|
|
494
|
+
complete, partial, or unknown coverage. `--no-persist` validates the handoff
|
|
495
|
+
without changing the backlog. SARIF remains the findings-only fallback.
|
|
268
496
|
[Integration guide →](integrations/codex-security/)
|
|
269
497
|
|
|
270
498
|
### Then let it fix what it found
|
|
@@ -339,15 +567,18 @@ answer does not change depending on who asks it.
|
|
|
339
567
|
|
|
340
568
|
| Stage of the loop | Where you are | How Dvalin gets there | Status |
|
|
341
569
|
|---|---|---|---|
|
|
342
|
-
| **Writing the code** | Claude Code | [
|
|
343
|
-
| | Codex | [
|
|
570
|
+
| **Writing the code** | Claude Code | [portable plugin](integrations/dvalin-security/) · `claude mcp add` · `mcp-install claude-code` | ✅ session verified |
|
|
571
|
+
| | Codex | `mcp-install codex` · [portable plugin](integrations/dvalin-security/) · [sealed scan + SARIF interop](integrations/codex-security/) | ✅ session verified · capture below |
|
|
344
572
|
| | Cursor | `dvalincode mcp-install cursor` | ⚙️ config verified |
|
|
573
|
+
| | Gemini CLI · OpenCode | `mcp-install gemini\|opencode` · `dvalin agents connect` | ⚙️ config verified |
|
|
574
|
+
| | CC Switch | `dvalin agents connect cc-switch` | ⚙️ link format tested, not yet imported |
|
|
345
575
|
| | Windsurf · Zed | stdio MCP through their own settings | ⚙️ documented, unverified |
|
|
346
576
|
| | Any MCP client | registry `io.github.arthurpanhku/dvalincode` | ⚙️ published |
|
|
347
577
|
| **Reading it back** | VS Code | `mcp-install vscode` · [extension](editors/vscode/) for Problems, coverage and gate status | ✅ editor verified |
|
|
348
578
|
| **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
579
|
| | 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 |
|
|
580
|
+
| **Believing the result** | anyone, offline | `dvalin verify-fix record.json --trusted-key ci.pub` | ✅ no workspace, no network, no Dvalin state |
|
|
581
|
+
| | the merge gate | `reverify: true` — base and head re-scanned, checks re-run on the runner, fresh record signed | ✅ covered by the test suite |
|
|
351
582
|
|
|
352
583
|
**✅** means a real client was driven end to end and the tool call was observed.
|
|
353
584
|
**⚙️** means the configuration is generated and its shape is tested, but no
|
|
@@ -364,6 +595,8 @@ config file that loads is not evidence that a tool was ever called.
|
|
|
364
595
|
| 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
596
|
| 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
597
|
| Cursor | — | 2026-09-04 | `mcp-install cursor` writes `.cursor/mcp.json` under `mcpServers`; no session has been captured |
|
|
598
|
+
| Gemini CLI · OpenCode | — | 2026-11-11 | `mcp-install` writes the shapes their own docs specify (Gemini: `mcpServers` in `settings.json`; OpenCode: the V1 `mcp` entry, which V2 still reads); no session has been captured |
|
|
599
|
+
| CC Switch | — | 2026-11-11 | the `ccswitch://` link follows CC Switch's deep-link guide and importer source; not yet opened in a running CC Switch |
|
|
367
600
|
|
|
368
601
|
That weekly workflow exists because an earlier version of this claim named two
|
|
369
602
|
CLI versions by hand, both went stale within weeks, and nothing said so. It now
|
|
@@ -1161,6 +1394,7 @@ Full source references: [docs/REFERENCES.md](docs/REFERENCES.md)
|
|
|
1161
1394
|
| badhope | [@weed33834](https://github.com/weed33834) |
|
|
1162
1395
|
| Samran Asif | [@webdevsamran](https://github.com/webdevsamran) |
|
|
1163
1396
|
| dchaudhari7177 | [@dchaudhari7177](https://github.com/dchaudhari7177) |
|
|
1397
|
+
| TayfurYldz | [@TayfurYldz](https://github.com/TayfurYldz) |
|
|
1164
1398
|
|
|
1165
1399
|
See the [complete contribution history](https://github.com/arthurpanhku/dvalincode/graphs/contributors), including automated dependency and maintenance updates.
|
|
1166
1400
|
|