riskdiff-cli 0.0.0-stage → 2.0.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/LICENSE +21 -0
- package/README.md +526 -2
- package/bin/riskdiff.js +148 -0
- package/package.json +32 -4
- package/schema/riskdiff.schema.json +43 -0
- package/src/ai.js +124 -0
- package/src/analyze.js +27 -0
- package/src/config.js +122 -0
- package/src/deps.js +127 -0
- package/src/diff.js +72 -0
- package/src/git.js +90 -0
- package/src/hook.js +43 -0
- package/src/mcp.js +99 -0
- package/src/packages.js +153 -0
- package/src/popular.js +60 -0
- package/src/report.js +141 -0
- package/src/rules.js +244 -0
- package/src/score.js +90 -0
- package/src/source.js +70 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 zeitgeistz
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,527 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# 🎯 riskdiff
|
|
4
|
+
|
|
5
|
+
**Know which part of a diff to review first.**
|
|
6
|
+
|
|
7
|
+
riskdiff reads a `git diff`, scores every hunk for risk, and sorts the hunks riskiest first.
|
|
8
|
+
It's built for the moment an AI agent hands you 14 changed files and you have five minutes to review them.
|
|
9
|
+
|
|
10
|
+
[](https://github.com/zeitgeistz/riskdiff/actions/workflows/ci.yml)
|
|
11
|
+
[](https://github.com/zeitgeistz/riskdiff/releases)
|
|
12
|
+
[](LICENSE)
|
|
13
|
+

|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
[Quick start](#-quick-start) · [What it catches](#-what-it-catches) · [Integrations](#-integrations) · [How scoring works](#-how-scoring-works) · [FAQ](#-faq)
|
|
17
|
+
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
$ riskdiff
|
|
24
|
+
riskdiff · 5 files, 5 hunks · 1 high · 2 medium · 1 low
|
|
25
|
+
|
|
26
|
+
⚠ Tests weakened: 1 test skipped or focused, 1 hunk removed assertions
|
|
27
|
+
|
|
28
|
+
HIGH 50 src/routes/admin.js:2
|
|
29
|
+
+0 −1
|
|
30
|
+
• Removes an authentication or permission check [auth-check-removed +50]
|
|
31
|
+
|
|
32
|
+
MEDIUM 40 test/users.test.js:1
|
|
33
|
+
+1 −2
|
|
34
|
+
• Skips or focuses tests [test-skipped +20]
|
|
35
|
+
• Removes test assertions [assertion-removed +20]
|
|
36
|
+
|
|
37
|
+
MEDIUM 25 src/db/users.js:2
|
|
38
|
+
+1 −1
|
|
39
|
+
• SQL built from string concatenation or interpolation [sql-injection +25]
|
|
40
|
+
|
|
41
|
+
LOW 15 package.json:3
|
|
42
|
+
+2 −1
|
|
43
|
+
• Adds or changes a dependency [new-dependency +15]
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
In this diff the agent removed `requireAuth`, skipped a failing test instead of fixing it, swapped a parameterized query for string interpolation, and added a package called `react-codeshift`, a name AI models are known to invent. The harmless formatting change in `src/format.js` scored 0 and is hidden.
|
|
47
|
+
|
|
48
|
+
## 🤔 Why
|
|
49
|
+
|
|
50
|
+
AI writes a growing share of code, but reviewing it hasn't gotten faster:
|
|
51
|
+
|
|
52
|
+
- **96%** of developers don't fully trust AI-generated code, and surveys describe review as the new bottleneck ([Sonar, 2026](https://www.sonarsource.com/blog/state-of-code-developer-survey-report-the-current-reality-of-ai-coding/)).
|
|
53
|
+
- The top frustration is code that is **"almost right, but not quite"** ([Stack Overflow survey via VentureBeat](https://venturebeat.com/technology/stack-overflow-data-reveals-the-hidden-productivity-tax-of-almost-right-ai-code)).
|
|
54
|
+
- Agents skip tests, weaken assertions, and add packages instead of using the ones you already have.
|
|
55
|
+
|
|
56
|
+
A big diff gets read top to bottom, and attention runs out before the dangerous line. riskdiff doesn't replace review. It tells you **where to spend it**.
|
|
57
|
+
|
|
58
|
+
## ✨ Features
|
|
59
|
+
|
|
60
|
+
- 🧭 **Ranks hunks, not files.** Points you at `file:line`, not "somewhere in this 400-line file".
|
|
61
|
+
- 🔍 **27 built-in rules** for security, data, tests, dependencies, and infrastructure.
|
|
62
|
+
- 📦 **Package check.** Catches dependencies that don't exist, were published last week, look like a popular package, or duplicate a library you already use.
|
|
63
|
+
- 🧠 **Ignores moved code and comments.** Removal rules only fire when something actually disappears, and `// don't use eval()` isn't a call to `eval`.
|
|
64
|
+
- 🧪 **Test tamper warning.** One line tells you when a diff skipped tests, removed assertions, or deleted test files.
|
|
65
|
+
- ⚙️ **Configurable.** Ignore paths, turn rules off, change weights, and add your own rules in `.riskdiff.json`, or silence one hunk with `riskdiff-ignore`.
|
|
66
|
+
- 📦 **Zero dependencies.** Only Node.js and git.
|
|
67
|
+
- 🖥️ **Four output formats:** colored terminal, JSON for tools and agents, Markdown for PR comments, SARIF for code scanning.
|
|
68
|
+
- ⚙️ **GitHub Action:** `uses: zeitgeistz/riskdiff@v1` comments a risk table on every PR and fails the check on high risk.
|
|
69
|
+
- 🚦 **CI gate:** `--fail-on high` exits with code 1.
|
|
70
|
+
- 🤖 **Claude Code plugin:** a hook warns Claude right after it makes a risky edit, an MCP tool lets it scan any range, and a skill walks you through the review.
|
|
71
|
+
- ✦ **Optional AI second opinion** (`--ai`): Claude marks each flagged hunk as likely real or a likely false positive, with one sentence of why. Off by default.
|
|
72
|
+
|
|
73
|
+
## 🚀 Quick start
|
|
74
|
+
|
|
75
|
+
Requires **Node.js 18.11+** and **git**.
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
# Run without installing
|
|
79
|
+
npx -y github:zeitgeistz/riskdiff
|
|
80
|
+
|
|
81
|
+
# Or install globally
|
|
82
|
+
npm install -g github:zeitgeistz/riskdiff
|
|
83
|
+
riskdiff
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## 📖 Usage
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
riskdiff # working tree + staged + untracked changes vs HEAD
|
|
90
|
+
riskdiff --staged # staged changes only (what you're about to commit)
|
|
91
|
+
riskdiff main...HEAD # everything on this branch since it left main
|
|
92
|
+
riskdiff HEAD~3 # any range git diff accepts
|
|
93
|
+
git diff main | riskdiff # read a diff from stdin
|
|
94
|
+
riskdiff - < change.patch # or from a file
|
|
95
|
+
riskdiff hook # Claude Code PostToolUse hook (see Integrations)
|
|
96
|
+
riskdiff mcp # MCP server over stdio (see Integrations)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
| Option | Description |
|
|
100
|
+
|---|---|
|
|
101
|
+
| `--json` | Machine-readable output (see [JSON output](#-json-output)) |
|
|
102
|
+
| `--md` | Markdown table, ready for a PR comment |
|
|
103
|
+
| `--sarif` | SARIF 2.1.0 for GitHub code scanning (see [GitHub Action](#%EF%B8%8F-github-action)) |
|
|
104
|
+
| `-o`, `--output <file>` | Write the report to a file instead of stdout |
|
|
105
|
+
| `--check-packages` | Look new npm and PyPI dependencies up in their registries (see [Package check](#-package-check)) |
|
|
106
|
+
| `--ai` | Ask Claude for a second opinion on the riskiest hunks (see [AI second opinion](#-ai-second-opinion)) |
|
|
107
|
+
| `--code` | Print the changed lines under each hunk |
|
|
108
|
+
| `--fail-on <level>` | Exit with code `1` if any hunk is at or above `low`, `medium`, or `high` |
|
|
109
|
+
| `--config <path>` | Use this config file instead of `.riskdiff.json` in the repo root |
|
|
110
|
+
| `--no-untracked` | Leave out untracked files (included by default when no range is given) |
|
|
111
|
+
| `--no-color` | Disable colors (also respects `NO_COLOR`) |
|
|
112
|
+
| `-h`, `--help` | Show help |
|
|
113
|
+
| `-v`, `--version` | Show version |
|
|
114
|
+
|
|
115
|
+
**Exit codes:** `0` OK · `1` `--fail-on` threshold reached · `2` usage, config, or git error.
|
|
116
|
+
|
|
117
|
+
Untracked files that aren't in `.gitignore` are included as new files. Binary files and files over 1 MB are skipped.
|
|
118
|
+
|
|
119
|
+
## ⚙️ Configuration
|
|
120
|
+
|
|
121
|
+
Put a `.riskdiff.json` in your repo root. Every key is optional.
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"$schema": "https://raw.githubusercontent.com/zeitgeistz/riskdiff/main/schema/riskdiff.schema.json",
|
|
126
|
+
"ignore": ["dist/**", "*.min.js", "**/__snapshots__/**"],
|
|
127
|
+
"rules": {
|
|
128
|
+
"todo-added": false,
|
|
129
|
+
"new-dependency": 25
|
|
130
|
+
},
|
|
131
|
+
"customRules": [
|
|
132
|
+
{
|
|
133
|
+
"id": "no-console",
|
|
134
|
+
"weight": 5,
|
|
135
|
+
"reason": "Adds console.log",
|
|
136
|
+
"added": ["console\\.log\\("]
|
|
137
|
+
}
|
|
138
|
+
],
|
|
139
|
+
"failOn": "high"
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
| Key | What it does |
|
|
144
|
+
|---|---|
|
|
145
|
+
| `checkPackages` | `true` runs the [registry check](#-package-check) on every run. |
|
|
146
|
+
| `ignore` | Globs for files to skip. `**` matches any folders, `*` anything except `/`. A pattern with no `/` matches the file name anywhere, like `.gitignore`. |
|
|
147
|
+
| `rules` | `false` turns a rule off. A number sets its weight. |
|
|
148
|
+
| `customRules` | Your own rules. Each needs `id`, `weight`, `reason`, and exactly one of `path` (regex string), `added`, or `removed` (arrays of regex strings). Optional: `flags` (e.g. `"i"`) and `raw: true` to also match inside comments. |
|
|
149
|
+
| `failOn` | Default for `--fail-on`. The flag wins when both are set. |
|
|
150
|
+
|
|
151
|
+
riskdiff exits with code `2` and a clear message if the config has an unknown key, a bad regex, or a rule id that doesn't exist.
|
|
152
|
+
|
|
153
|
+
## 🙈 Ignoring a finding
|
|
154
|
+
|
|
155
|
+
Add `riskdiff-ignore` in a comment on any added line of the hunk:
|
|
156
|
+
|
|
157
|
+
```js
|
|
158
|
+
// riskdiff-ignore auth-check-removed: auth now runs in the gateway middleware
|
|
159
|
+
router.get('/users', listUsers);
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
- `riskdiff-ignore rule-a, rule-b` silences those rules for that hunk.
|
|
163
|
+
- `riskdiff-ignore` on its own silences every rule for that hunk.
|
|
164
|
+
- Anything after the rule ids is free text, so you can leave the reason for reviewers.
|
|
165
|
+
|
|
166
|
+
Comments are otherwise ignored: `// don't call eval()` doesn't count as calling `eval`, and deleting a commented-out `requireAuth` doesn't count as removing an auth check. Two rules still read comments on purpose: `hardcoded-secret` (a key in a comment still leaks) and `todo-added`.
|
|
167
|
+
|
|
168
|
+
## 🔍 What it catches
|
|
169
|
+
|
|
170
|
+
### Code that was added
|
|
171
|
+
|
|
172
|
+
| Rule | Weight | Catches |
|
|
173
|
+
|---|---:|---|
|
|
174
|
+
| `hardcoded-secret` | 50 | `apiKey = "..."`, AWS `AKIA…`, `sk-…`, `ghp_…`, Slack tokens, private keys |
|
|
175
|
+
| `destructive-sql` | 35 | `DROP TABLE`, `TRUNCATE`, `DELETE FROM` without `WHERE` |
|
|
176
|
+
| `dangerous-exec` | 30 | `eval`, `new Function`, `child_process`, `os.system`, `shell=True` |
|
|
177
|
+
| `security-disabled` | 30 | `verify=False`, `rejectUnauthorized: false`, CORS `*`, CSRF exemptions |
|
|
178
|
+
| `sql-injection` | 25 | SQL built with `+`, `${}`, f-strings, or `%` formatting |
|
|
179
|
+
| `test-skipped` | 20 | `it.skip`, `.only`, `xit`, `@pytest.mark.skip`, `@Disabled`, `t.Skip()` |
|
|
180
|
+
| `swallowed-error` | 15 | `catch (e) {}`, `except: pass`, `.catch(() => {})` |
|
|
181
|
+
| `new-dependency` | 15 | New or changed entries in `package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, and more |
|
|
182
|
+
| `package-lookalike` | 30 | A new npm/PyPI dependency one or two letters away from a popular package (`reqeusts`, `expresss`) |
|
|
183
|
+
| `duplicate-dependency` | 15 | A new library that does the same job as one you already have (`axios` next to `node-fetch`, `moment` next to `dayjs`) |
|
|
184
|
+
| `todo-added` | 5 | New `TODO`, `FIXME`, `HACK`, `XXX` |
|
|
185
|
+
|
|
186
|
+
### Code that was removed
|
|
187
|
+
|
|
188
|
+
| Rule | Weight | Catches |
|
|
189
|
+
|---|---:|---|
|
|
190
|
+
| `auth-check-removed` | 50 | `requireAuth`, `isAuthenticated`, `authorize…`, `@login_required`, `@PreAuthorize`, `@UseGuards` |
|
|
191
|
+
| `test-file-deleted` | 25 | A whole test file deleted |
|
|
192
|
+
| `error-handling-removed` | 20 | `try`/`catch`/`except`/`throw`/`raise`, Go `if err != nil` |
|
|
193
|
+
| `validation-removed` | 20 | `validate…()`, `sanitize…()`, `escape…()`, schema `.parse()`, zod, Joi |
|
|
194
|
+
| `assertion-removed` | 20 | `expect(`, `assert…`, `self.assert…` in test files |
|
|
195
|
+
|
|
196
|
+
### Sensitive places
|
|
197
|
+
|
|
198
|
+
| Rule | Weight | Path matches |
|
|
199
|
+
|---|---:|---|
|
|
200
|
+
| `env-file` | 30 | `.env`, `.env.production` (not `.env.example`) |
|
|
201
|
+
| `auth-code` | 25 | `auth`, `login`, `session`, `password`, `permission`, `oauth`, `jwt`, `rbac` |
|
|
202
|
+
| `payment-code` | 25 | `payment`, `billing`, `checkout`, `invoice`, `stripe`, `subscription` |
|
|
203
|
+
| `crypto-code` | 20 | `crypto`, `encrypt`, `cipher`, `hash`, `signature` |
|
|
204
|
+
| `migration` | 20 | `migrations/`, `*.sql`, `schema.prisma` |
|
|
205
|
+
| `ci-infra` | 20 | `.github/workflows/`, `Dockerfile`, `docker-compose`, `*.tf`, `k8s/`, `helm/` |
|
|
206
|
+
| `lockfile` | 3 | `package-lock.json`, `yarn.lock`, `poetry.lock`, `go.sum`, … |
|
|
207
|
+
| `large-change` | 0–10 | +1 for every 25 changed lines in the hunk (not for lockfiles) |
|
|
208
|
+
|
|
209
|
+
## 📦 Package check
|
|
210
|
+
|
|
211
|
+
AI models invent package names, and attackers register those names on npm and PyPI to catch anyone who installs them ("slopsquatting"). Agents also add a new library instead of using the one already in the project.
|
|
212
|
+
|
|
213
|
+
Two checks always run, offline:
|
|
214
|
+
|
|
215
|
+
- **`package-lookalike`**: the name is one or two edits away from a popular package.
|
|
216
|
+
- **`duplicate-dependency`**: the new library does the same job as one already in the manifest (HTTP clients, date libraries, test runners, validators, loggers, ORMs, and more).
|
|
217
|
+
|
|
218
|
+
Add `--check-packages` (or `"checkPackages": true` in the config) to also look each new npm and PyPI dependency up in its registry:
|
|
219
|
+
|
|
220
|
+
| Rule | Weight | Flags a dependency that… |
|
|
221
|
+
|---|---:|---|
|
|
222
|
+
| `package-not-found` | 50 | doesn't exist in the registry (hallucinated, or a private package) |
|
|
223
|
+
| `package-new` | 30 | was first published in the last 30 days |
|
|
224
|
+
| `package-low-downloads` | 15 | had fewer than 500 npm downloads last week |
|
|
225
|
+
| `package-deprecated` | 15 | is deprecated on npm or yanked on PyPI |
|
|
226
|
+
|
|
227
|
+
```text
|
|
228
|
+
HIGH 110 requirements.txt:1
|
|
229
|
+
• reqeusts does not exist on PyPI; possibly a hallucinated name [package-not-found +50]
|
|
230
|
+
• reqeusts looks like requests; check it is the package you meant [package-lookalike +30]
|
|
231
|
+
• Adds or changes a dependency [new-dependency +15]
|
|
232
|
+
• Adds requests and httpx, which do the same job (HTTP client) [duplicate-dependency +15]
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
The check only sends package **names** to `registry.npmjs.org`, `api.npmjs.org`, and `pypi.org`. No code leaves your machine. If a registry can't be reached, riskdiff prints a warning on stderr and scores the rest as usual.
|
|
236
|
+
|
|
237
|
+
For a private package that riskdiff reports as not found, turn the rule off in `.riskdiff.json` or add a `"//": "riskdiff-ignore package-not-found"` line next to it.
|
|
238
|
+
|
|
239
|
+
## ✦ AI second opinion
|
|
240
|
+
|
|
241
|
+
Regex rules are fast, but they can't tell `eval(trustedConstant)` from `eval(req.body.code)`. `--ai` sends the riskiest hunks (up to 15, at most 40 lines each, with their findings) to Claude and asks for one verdict per hunk:
|
|
242
|
+
|
|
243
|
+
```text
|
|
244
|
+
HIGH 55 src/run.js:12
|
|
245
|
+
• Runs dynamic code or shell commands [dangerous-exec +30]
|
|
246
|
+
• SQL built from string concatenation or interpolation [sql-injection +25]
|
|
247
|
+
AI: likely real — the query interpolates req.query.id straight into SQL.
|
|
248
|
+
|
|
249
|
+
MEDIUM 30 scripts/build.js:3
|
|
250
|
+
• Runs dynamic code or shell commands [dangerous-exec +30]
|
|
251
|
+
AI: likely false positive — execSync runs a fixed "npm run build" string.
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
```bash
|
|
255
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
256
|
+
riskdiff --ai
|
|
257
|
+
RISKDIFF_AI_MODEL=claude-haiku-5-5 riskdiff --ai # pick another model
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
- **Off unless you pass `--ai`.** Without it nothing leaves your machine.
|
|
261
|
+
- **Scores and `--fail-on` don't change.** The verdict is an annotation (`ai` in JSON, a 🤖 line in Markdown), so CI gates stay deterministic.
|
|
262
|
+
- Uses `claude-opus-5-5` at low effort by default. Any API problem (no key, rate limit, network) prints a warning and the report still comes out.
|
|
263
|
+
|
|
264
|
+
## 🧮 How scoring works
|
|
265
|
+
|
|
266
|
+
1. The diff is split into **hunks** (the `@@ … @@` blocks).
|
|
267
|
+
2. Each rule is checked against the hunk's file path, added lines, and removed lines. A rule counts **once per hunk**.
|
|
268
|
+
3. The hunk's **score** is the sum of the weights that matched, plus the size bonus.
|
|
269
|
+
4. The score maps to a **level**:
|
|
270
|
+
|
|
271
|
+
| Level | Score |
|
|
272
|
+
|---|---|
|
|
273
|
+
| 🔴 **High** | 50+ |
|
|
274
|
+
| 🟠 **Medium** | 25–49 |
|
|
275
|
+
| 🔵 **Low** | 1–24 |
|
|
276
|
+
| ⚪ None | 0 (hidden) |
|
|
277
|
+
|
|
278
|
+
Rules stack. One removed auth check is already **high**. A new SQL string (`25`) in `src/auth/login.js` (`+25`) is also **high**, because the same mistake matters more in auth code.
|
|
279
|
+
|
|
280
|
+
Removal rules compare counts: if a hunk removes one `try` and adds one back, nothing was removed. Deleted files are handled by `test-file-deleted` only, so deleting dead code doesn't set off every removal rule.
|
|
281
|
+
|
|
282
|
+
## 🔌 Integrations
|
|
283
|
+
|
|
284
|
+
### 🤖 Claude Code plugin
|
|
285
|
+
|
|
286
|
+
This repo is a Claude Code plugin marketplace. Install it once:
|
|
287
|
+
|
|
288
|
+
```text
|
|
289
|
+
/plugin marketplace add zeitgeistz/riskdiff
|
|
290
|
+
/plugin install riskdiff@riskdiff
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
On Claude Code 2.1.275 or later, one line does both: `/plugin install riskdiff --marketplace zeitgeistz/riskdiff`.
|
|
294
|
+
|
|
295
|
+
You get three things:
|
|
296
|
+
|
|
297
|
+
| Part | What it does |
|
|
298
|
+
|---|---|
|
|
299
|
+
| **Hook** | After every `Edit` or `Write`, scans that file's uncommitted changes. If a hunk is medium or high risk, Claude sees the findings right away and either fixes them or explains why they're safe. Safe edits add nothing to the conversation. It never blocks an edit. |
|
|
300
|
+
| **MCP tool** `riskdiff_scan` | Claude can scan any range on demand (`range`, `staged`, `checkPackages`, `minLevel`, `cwd`) and gets JSON back. |
|
|
301
|
+
| **Skill** `/zeit-riskdiff` | Runs a full review: riskiest hunks first, with Claude explaining each one. |
|
|
302
|
+
|
|
303
|
+
Everything runs locally with the plugin's own copy of riskdiff, so only Node.js is needed.
|
|
304
|
+
|
|
305
|
+
<details>
|
|
306
|
+
<summary><b>Without the plugin</b></summary>
|
|
307
|
+
|
|
308
|
+
Use the hook on its own by adding this to `.claude/settings.json` (riskdiff installed globally):
|
|
309
|
+
|
|
310
|
+
```json
|
|
311
|
+
{
|
|
312
|
+
"hooks": {
|
|
313
|
+
"PostToolUse": [
|
|
314
|
+
{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "riskdiff hook", "timeout": 30 }] }
|
|
315
|
+
]
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
Add the MCP server to any MCP client:
|
|
321
|
+
|
|
322
|
+
```bash
|
|
323
|
+
claude mcp add riskdiff -- npx -y github:zeitgeistz/riskdiff#v2.0.0 mcp
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
Or copy just the skill:
|
|
327
|
+
|
|
328
|
+
```bash
|
|
329
|
+
# macOS / Linux
|
|
330
|
+
cp -r skills/zeit-riskdiff ~/.claude/skills/
|
|
331
|
+
|
|
332
|
+
# Windows (PowerShell)
|
|
333
|
+
Copy-Item -Recurse skills\zeit-riskdiff $HOME\.claude\skills\
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Then type `/zeit-riskdiff` in Claude Code, or ask *"what's risky in this change?"*.
|
|
337
|
+
|
|
338
|
+
</details>
|
|
339
|
+
|
|
340
|
+
### 🪝 Git pre-commit hook
|
|
341
|
+
|
|
342
|
+
Block commits that contain high-risk changes:
|
|
343
|
+
|
|
344
|
+
```bash
|
|
345
|
+
cat > .git/hooks/pre-commit <<'EOF'
|
|
346
|
+
#!/bin/sh
|
|
347
|
+
npx -y github:zeitgeistz/riskdiff#v2.0.0 --staged --fail-on high
|
|
348
|
+
EOF
|
|
349
|
+
chmod +x .git/hooks/pre-commit
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
Use `git commit --no-verify` to bypass it when you've reviewed the change.
|
|
353
|
+
|
|
354
|
+
### ⚙️ GitHub Action
|
|
355
|
+
|
|
356
|
+
Comments a risk table on every pull request (and keeps updating the same comment), writes it to the job summary, and fails the check on high-risk changes:
|
|
357
|
+
|
|
358
|
+
```yaml
|
|
359
|
+
name: riskdiff
|
|
360
|
+
on: pull_request
|
|
361
|
+
|
|
362
|
+
permissions:
|
|
363
|
+
contents: read
|
|
364
|
+
pull-requests: write
|
|
365
|
+
|
|
366
|
+
jobs:
|
|
367
|
+
riskdiff:
|
|
368
|
+
runs-on: ubuntu-latest
|
|
369
|
+
steps:
|
|
370
|
+
- uses: actions/checkout@v4
|
|
371
|
+
with:
|
|
372
|
+
fetch-depth: 0
|
|
373
|
+
- uses: actions/setup-node@v4
|
|
374
|
+
with:
|
|
375
|
+
node-version: 22
|
|
376
|
+
- uses: zeitgeistz/riskdiff@v1
|
|
377
|
+
with:
|
|
378
|
+
fail-on: high
|
|
379
|
+
check-packages: true
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
| Input | Default | Description |
|
|
383
|
+
|---|---|---|
|
|
384
|
+
| `base` | PR base branch | Ref to compare against. On `push` events the default is the previous commit. |
|
|
385
|
+
| `fail-on` | `high` | Fail if any hunk is at or above `low`, `medium`, or `high`. `''` never fails. |
|
|
386
|
+
| `comment` | `true` | Post or update a PR comment. Skipped quietly on fork PRs with read-only tokens. |
|
|
387
|
+
| `check-packages` | `false` | Run the [registry check](#-package-check). |
|
|
388
|
+
| `sarif` | `false` | Also write a SARIF file (see below). |
|
|
389
|
+
| `github-token` | `github.token` | Token for the PR comment. |
|
|
390
|
+
|
|
391
|
+
Outputs: `high`, `medium`, `low` (counts), `report` (Markdown path), and `sarif-file`.
|
|
392
|
+
|
|
393
|
+
#### Code scanning (SARIF)
|
|
394
|
+
|
|
395
|
+
Show findings as annotations on the PR diff and in the repo's **Security → Code scanning** tab:
|
|
396
|
+
|
|
397
|
+
```yaml
|
|
398
|
+
permissions:
|
|
399
|
+
contents: read
|
|
400
|
+
pull-requests: write
|
|
401
|
+
security-events: write
|
|
402
|
+
steps:
|
|
403
|
+
# ...checkout and setup-node as above
|
|
404
|
+
- id: riskdiff
|
|
405
|
+
uses: zeitgeistz/riskdiff@v1
|
|
406
|
+
with:
|
|
407
|
+
sarif: true
|
|
408
|
+
- uses: github/codeql-action/upload-sarif@v3
|
|
409
|
+
if: always()
|
|
410
|
+
with:
|
|
411
|
+
sarif_file: ${{ steps.riskdiff.outputs.sarif-file }}
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
Locally, `riskdiff --sarif -o riskdiff.sarif` writes the same file.
|
|
415
|
+
|
|
416
|
+
## 🧾 JSON output
|
|
417
|
+
|
|
418
|
+
`riskdiff --json` prints a summary plus every hunk, riskiest first:
|
|
419
|
+
|
|
420
|
+
```json
|
|
421
|
+
{
|
|
422
|
+
"summary": { "files": 5, "hunks": 5, "high": 1, "medium": 2, "low": 1, "none": 1 },
|
|
423
|
+
"hunks": [
|
|
424
|
+
{
|
|
425
|
+
"file": "src/routes/admin.js",
|
|
426
|
+
"status": "modified",
|
|
427
|
+
"line": 2,
|
|
428
|
+
"context": "",
|
|
429
|
+
"added": 0,
|
|
430
|
+
"removed": 1,
|
|
431
|
+
"score": 50,
|
|
432
|
+
"level": "high",
|
|
433
|
+
"findings": [
|
|
434
|
+
{ "id": "auth-check-removed", "weight": 50, "reason": "Removes an authentication or permission check" }
|
|
435
|
+
]
|
|
436
|
+
}
|
|
437
|
+
]
|
|
438
|
+
}
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
`status` is `modified`, `added`, `deleted`, or `renamed`. `line` is the first changed line in the new file. `context` is the function name git prints in the hunk header, when there is one. With `--ai`, reviewed hunks also carry `"ai": { "verdict": "real" | "false-positive" | "unsure", "note": "..." }`.
|
|
442
|
+
|
|
443
|
+
## ❓ FAQ
|
|
444
|
+
|
|
445
|
+
<details>
|
|
446
|
+
<summary><b>Is this a security scanner?</b></summary>
|
|
447
|
+
|
|
448
|
+
No. It's a **triage** tool built on fast regex heuristics. It will miss things and flag some false positives. Use it to decide what to read first, and keep using real tools (Semgrep, CodeQL, Snyk, secret scanners) for security.
|
|
449
|
+
</details>
|
|
450
|
+
|
|
451
|
+
<details>
|
|
452
|
+
<summary><b>Does it send my code anywhere?</b></summary>
|
|
453
|
+
|
|
454
|
+
Not by default. It runs locally and the scoring uses no AI model. There are two opt-in network calls: `--check-packages` sends package names (never code) to npm and PyPI, and `--ai` sends the changed lines of up to 15 flagged hunks to the Anthropic API. The Claude Code hook and MCP tool never use `--ai`.
|
|
455
|
+
</details>
|
|
456
|
+
|
|
457
|
+
<details>
|
|
458
|
+
<summary><b>Which languages does it support?</b></summary>
|
|
459
|
+
|
|
460
|
+
Rules are text-based, so any language works. Patterns are tuned for JavaScript/TypeScript, Python, Go, Java/Kotlin, Ruby, PHP, and SQL.
|
|
461
|
+
</details>
|
|
462
|
+
|
|
463
|
+
<details>
|
|
464
|
+
<summary><b>Why is a hunk scored 0 even though it's important?</b></summary>
|
|
465
|
+
|
|
466
|
+
No rule matched it. riskdiff only knows the patterns in the tables above, so "no findings" never means "safe". If a pattern keeps biting you, open an issue or a PR with a rule and a test.
|
|
467
|
+
</details>
|
|
468
|
+
|
|
469
|
+
<details>
|
|
470
|
+
<summary><b>Can I add my own rules or change weights?</b></summary>
|
|
471
|
+
|
|
472
|
+
Yes. Use `rules` and `customRules` in [`.riskdiff.json`](#%EF%B8%8F-configuration). Built-in rules live in [`src/rules.js`](src/rules.js) if you want to contribute one.
|
|
473
|
+
</details>
|
|
474
|
+
|
|
475
|
+
## 🛠️ Development
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
git clone https://github.com/zeitgeistz/riskdiff.git
|
|
479
|
+
cd riskdiff
|
|
480
|
+
npm test # node --test, no install needed
|
|
481
|
+
node bin/riskdiff.js --help
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
```text
|
|
485
|
+
bin/riskdiff.js CLI: argument parsing, output, exit codes
|
|
486
|
+
src/analyze.js The pipeline: config → git diff → parse → score
|
|
487
|
+
src/git.js Reading diffs, untracked files, and new file contents from git
|
|
488
|
+
src/diff.js Unified diff parser → files and hunks
|
|
489
|
+
src/source.js Comment stripping and riskdiff-ignore directives
|
|
490
|
+
src/deps.js Finds the dependencies a manifest hunk adds
|
|
491
|
+
src/packages.js Look-alike, duplicate, and registry checks for new dependencies
|
|
492
|
+
src/popular.js Popular package names and libraries that do the same job
|
|
493
|
+
src/rules.js Built-in risk rules and weights
|
|
494
|
+
src/config.js .riskdiff.json loading, validation, globs
|
|
495
|
+
src/score.js Scores and sorts hunks, maps scores to levels
|
|
496
|
+
src/report.js Text, Markdown, JSON, and SARIF output
|
|
497
|
+
src/hook.js Claude Code PostToolUse hook
|
|
498
|
+
src/mcp.js MCP server (stdio JSON-RPC)
|
|
499
|
+
src/ai.js Optional --ai second opinion (Anthropic API, plain fetch)
|
|
500
|
+
schema/ JSON schema for .riskdiff.json
|
|
501
|
+
.claude-plugin/ Plugin and marketplace manifests
|
|
502
|
+
hooks/ Plugin hook config
|
|
503
|
+
skills/ Claude Code skill
|
|
504
|
+
test/ Tests (node:test)
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
### Adding a rule
|
|
508
|
+
|
|
509
|
+
1. Add an object to `rules` in `src/rules.js` with `id`, `weight`, `reason`, and one of `path`, `added`, `removed`, or `match`.
|
|
510
|
+
2. Add a test in `test/riskdiff.test.js` that proves it fires, plus one that proves it doesn't fire on a similar safe line.
|
|
511
|
+
3. Add it to the tables in this README.
|
|
512
|
+
|
|
513
|
+
## 🗺️ Roadmap
|
|
514
|
+
|
|
515
|
+
- [x] **Package check:** missing, brand-new, look-alike, and duplicate dependencies (v1.2)
|
|
516
|
+
- [x] Config file for custom rules, weights, and ignored paths (v1.1)
|
|
517
|
+
- [x] Include untracked files (v1.1)
|
|
518
|
+
- [x] Ignore comments, and `riskdiff-ignore` directives (v1.1)
|
|
519
|
+
- [x] GitHub Action with PR comments, job summary, and a gate (v1.3)
|
|
520
|
+
- [x] SARIF output for code scanning (v1.3)
|
|
521
|
+
- [x] Claude Code plugin: hook, MCP server, skill (v2.0)
|
|
522
|
+
- [x] Optional AI second opinion with `--ai` (v2.0)
|
|
523
|
+
- [ ] Published to npm as `riskdiff-cli` (the release workflow is ready; it publishes once an `NPM_TOKEN` secret is added)
|
|
524
|
+
|
|
525
|
+
## 📄 License
|
|
526
|
+
|
|
527
|
+
[MIT](LICENSE)
|