dvalincode

<p align="center">
  <img src="assets/logo.png" alt="DvalinCode" width="480">
</p>

<p align="center">
  <b>English</b> · <a href="README.zh-CN.md">中文</a> · <a href="https://dvalincode.dev">🌐 dvalincode.dev</a>
</p>

<p align="center">
  <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>
  <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>
  <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>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License"></a>
  <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>
  <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>
  <a href="#-providers"><img src="https://img.shields.io/badge/LLM-OpenAI%20·%20Claude%20·%20DeepSeek%20·%20Ollama%20·%20Groq-7C3AED?style=for-the-badge" alt="LLM Support"></a>
  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/i18n-EN%20·%20中文-orange?style=for-the-badge" alt="English / 中文"></a>
</p>

<p align="center">
  <b>Open security engineering for code written by humans and AI agents.</b><br>
  <b>Every repair carries its own proof.</b>
</p>

When an agent fixes a security finding, someone has to decide whether the fix
worked. Almost every tool asks the model that wrote it — which is the one
question a model cannot answer against its own interest.

**Dvalin decides instead, and hands you the proof.** It re-scans, runs your
project's own tests itself, and reads the exit codes from processes it started.
Who wrote the repair — our agent, Claude Code, Codex, Copilot, a person — is
recorded and never consulted. The result is a **Verified Fix Record**: a small
JSON file anyone can re-check offline, on a laptop with no network and no
Dvalin state.

```sh
dvalin verify-fix fix-record.json
```
```
Fix record 2c9d71ac03e0 · VERIFIED · scan-and-checks
  executor: claude-code (recorded, not consulted)
  targets: 1 before · 0 remaining
  coverage: complete → complete
  ✓ test: npm run test (exit 0)
  audit: run verify-36509f42 @ 414644c75af0
```

That record says something narrow on purpose: *these findings were gone, and
these checks were observed to pass.* It is not a claim that your code is safe,
and Dvalin will not let it be read as one — every record carries what the scan
actually covered, and a repair no check could confirm does not pass.
[The open profile →](docs/spec/FIX-VERIFICATION.md)

Dvalin is the independent security runtime between code generation and merge.
Humans, coding agents, and CI call the same versioned contract for discovery,
remediation, and verification. It runs independently, or interoperates with
specialist systems such as Codex Security through portable SARIF. Its built-in
coding capability is a remediation executor — not the trust boundary, and not an
attempt to compete with every general-purpose coding agent. See the
[security-agent strategy](docs/SECURITY-AGENT-STRATEGY.md).

---

## ⏱️ 30 seconds, no install, no API key

```sh
npx dvalincode security scan .
# After installing the package: dvalin scan .
```

That is the whole thing. It runs the built-in rules for injection, hardcoded
secrets, XSS, `eval`, and unsafe shell use against the current directory and
prints what it found. No account, no model, no config, no code leaves your
machine. The default policy runs only Dvalin Built-in, so the first scan always
works. Add optional engines explicitly, or inspect their fixed install commands:

```sh
dvalin scanners list
dvalin scanners install semgrep       # review the command
dvalin scanners install semgrep --yes # execute it under Dvalin policy
```

For an incremental “no new high-risk findings” gate, commit the policy and
baseline with the repository:

```sh
dvalin init
dvalin baseline
dvalin scan
```

This creates `dvalin.security.json` and `.dvalin/baseline.json`. Suppressions
require a reason and may have an owner and expiry date. Scan output is a
versioned envelope with a deterministic gate result and a resumable workflow ID.

### Or put it on every pull request — nothing to install at all

```yaml
# .github/workflows/security.yml
permissions:
  contents: read
  security-events: write
steps:
  - uses: actions/checkout@v5
    with:
      fetch-depth: 0        # so the scan can reach the base commit
  - uses: arthurpanhku/dvalincode@v0.18.0
    with:
      fail-on: high
      diff: true            # only report on what this PR changed
```

Findings land inline on the pull request diff and in your Security tab.
No API key, no secrets, no model — the scan is deterministic and local to the
runner. [Full example →](docs/examples/dvalin-scan.yml)

`diff: true` reports only on lines the pull request changed, so the gate blocks
what this change *adds* instead of everything the repository already carried.
That is what makes the check adoptable on a codebase that was not clean to
begin with. Drop it to scan the whole repository.

Every comment states what the scan **covered** — `complete`, `partial`, or
`unknown` — beside the result, because "no findings" from a run where half the
engines were missing is not the same answer as "no findings" from a complete one.

### And publish the proof next to the diff

If your pipeline produced a fix record, hand it to the same action:

```yaml
  - uses: arthurpanhku/dvalincode@v0.18.0
    with:
      fix-record: fix-record.json
```

The runner re-derives the record from the file alone — recomputing its hash and
re-deriving its verdict from its own evidence — and posts the result on the pull
request. A record that was edited after it was issued fails here, and fails the
job. The reviewer does not have to trust the pipeline that produced it, or us.

```
🔏 Verified Fix Record
✅ ce504a995395 · VERIFIED · scan-and-checks
- repaired by claude-code — recorded, and not consulted for this verdict
- targets: 1 before → 0 remaining
- coverage: complete → complete
- ✓ test: `npm run test` (exit 0)
- audit chain: verify-eeb1bae7 @ 80881867270d
```

### Or let your agent call it

If an agent is writing the code, something other than that agent has to check
it. DvalinCode is an MCP server, so any agent that speaks MCP can:

```sh
claude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .
```

One command configures the editor you actually use:

```sh
npx dvalincode mcp-install cursor        # .cursor/mcp.json
npx dvalincode mcp-install vscode        # .vscode/mcp.json
npx dvalincode mcp-install claude-code   # .mcp.json
```

The formats differ in a way that fails silently — VS Code keys its servers under
`servers`, Cursor under `mcpServers` — so the command writes the right one and
merges into whatever is already there. [Editors and MCP →](integrations/mcp/)

`dvalin_scan` accepts `diff: "uncommitted"`, which reports only on what the
agent just wrote rather than everything the repository already carried — the
difference between a usable answer and a wall of pre-existing findings. It never
runs a model or edits the target workspace. It records a
small local workflow so an agent can retrieve one finding by fingerprint and
request an independent re-scan through `dvalin_get_finding` and
`dvalin_verify_findings`.

That last one is the point: an agent that has just written a repair can ask for
an independent verdict on it. Dvalin re-scans, runs the project's own checks
itself, and returns a **Verified Fix Record** — what was targeted, what remains,
which commands ran and the exit codes Dvalin observed, and how much of the
codebase was actually covered. Whoever wrote the repair is recorded and never
consulted. `dvalin_verify_fix` re-derives such a record offline, so the reviewer
receiving it does not have to trust the tool that issued it.
[FVP-1 →](docs/spec/FIX-VERIFICATION.md) Responses include MCP `structuredContent`; scanner
readiness is available through `dvalin_list_scanners`. The same server exposes
`dvalin_run_task` as an optional implementation helper, plus session and audit
evidence tools.

Verified end to end against Claude Code 2.1.226 and Codex 0.147.0, driving a
real tool call against the published package rather than only completing a
handshake. [Agent integrations →](integrations/)

### Wherever you already work

One server, reached the way each tool expects:

| Harness | How Dvalin reaches it |
|---|---|
| **Claude Code** | `dvalincode mcp-install claude-code`, or `claude mcp add` · [skill](integrations/claude-code/) |
| **Codex** | `codex mcp add` · [SARIF interop](integrations/codex-security/) with Codex Security |
| **Cursor** | `dvalincode mcp-install cursor` |
| **VS Code** | `dvalincode mcp-install vscode` · [extension](editors/vscode/) for the Problems panel — *built, not yet published* |
| **Windsurf · Zed** | stdio MCP through their own settings — [server command](integrations/mcp/) |
| **Any MCP client** | [MCP registry](https://registry.modelcontextprotocol.io/): `io.github.arthurpanhku/dvalincode` |
| **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings inline on the pull request diff |
| **Any CI** | `dvalin scan . --fail-on high`, SARIF out for code scanning |

The MCP config formats are not interchangeable — VS Code keys its servers under
`servers`, Cursor under `mcpServers`, and the wrong one fails silently — so
`mcp-install` writes the right shape and merges into whatever is already there.
[Editors and MCP →]