node9-ai 1.19.3 โ†’ 1.20.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 (2) hide show
  1. package/README.md +53 -98
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,11 +1,5 @@
1
- <p align="center">
2
- <img src="https://github.com/user-attachments/assets/bc165779-4200-438d-967a-20d42bbfe69e" width="720" alt="Node9 scan scorecard" />
3
- </p>
4
-
5
1
  <h1 align="center">๐Ÿ›ก๏ธ Node9</h1>
6
-
7
2
  <p align="center"><strong>What did your AI agent actually do? Find out, and stop the dangerous stuff.</strong></p>
8
-
9
3
  <p align="center">
10
4
  <a href="https://www.npmjs.com/package/node9-ai"><img src="https://img.shields.io/npm/v/node9-ai.svg" alt="npm version" /></a>
11
5
  <a href="https://www.npmjs.com/package/node9-ai"><img src="https://img.shields.io/npm/dm/node9-ai.svg" alt="monthly downloads" /></a>
@@ -14,12 +8,36 @@
14
8
  <a href="https://huggingface.co/spaces/Node9ai/node9-security-demo"><img src="https://huggingface.co/datasets/huggingface/badges/resolve/main/open-in-hf-spaces-sm.svg" alt="Try on HF Spaces" /></a>
15
9
  </p>
16
10
 
17
- ---
11
+ Node9 sits between your AI agent and the tools it can use โ€” recording every action, blocking the dangerous ones, and showing you what happened both live and in retrospect.
12
+
13
+ Works with **Claude Code ยท Codex CLI ยท Gemini CLI ยท Cursor ยท Windsurf ยท any MCP server**.
14
+
15
+ ## What Node9 does
16
+
17
+ - ๐Ÿ›‘ **Block** dangerous AI actions before they run โ€” `rm -rf`, `git push --force`, `DROP TABLE`, credential reads, `curl | bash`
18
+ - ๐Ÿ” **Scan** what your AI has already been doing โ€” loops, leaked secrets, blocked operations across every session
19
+ - ๐Ÿ”‘ **Catch credential leaks** โ€” AWS keys, GitHub tokens, JWTs, GCP API keys, PEM private keys flagged in tool args, file contents, and shell config
20
+ - ๐Ÿ”ญ **Map your blast radius** โ€” every SSH key, AWS credential, and `.env` file an AI agent on this machine could reach right now
21
+
22
+ ## Live monitoring
23
+
24
+ <p align="center">
25
+ <img src="https://github.com/user-attachments/assets/25c601db-221d-4553-8b8c-34af85ab30c8" width="720" alt="Node9 monitor dashboard" />
26
+ </p>
27
+
28
+ `node9 monitor` opens an interactive terminal dashboard with two views:
18
29
 
19
- ## What `node9 scan` shows on a real machine
30
+ - **`[1]` Realtime** โ€” live activity, approvals, security alerts, current risk score
31
+ - **`[2]` Report** โ€” period-windowed summary: cost, top tools, shields fired, blast radius
32
+
33
+ ## Retrospective scan
20
34
 
21
35
  This is my own machine โ€” 30 days while building Node9. Score 25/100, 5 credential files an AI agent could reach right now.
22
36
 
37
+ <p align="center">
38
+ <img src="https://github.com/user-attachments/assets/bc165779-4200-438d-967a-20d42bbfe69e" width="720" alt="Node9 scan scorecard" />
39
+ </p>
40
+
23
41
  ```
24
42
  ๐Ÿ›ก Node9 Scan ยท 21 sessions ยท 8,114 tool calls ยท Apr 6 โ€“ May 1, 2026
25
43
 
@@ -36,39 +54,7 @@ $3,789 AI spend ยท 62 risky operations
36
54
  โ†’ npx node9-ai scan run this on your machine
37
55
  ```
38
56
 
39
- Run it on yours โ€” `npx node9-ai scan` finishes in ~10 seconds and runs entirely local. Nothing uploads. The full breakdown with every tool call, file path, and timestamp is `node9 scan` (default mode). For a browser dashboard view, run `node9 daemon start --openui`.
40
-
41
- <p align="center">
42
- <img src="https://github.com/user-attachments/assets/825f99d8-b487-4746-9cef-a02a9ca76c1f" width="90%" alt="Node9 browser History Audit dashboard" />
43
- </p>
44
-
45
- ---
46
-
47
- ## What Node9 does
48
-
49
- - ๐Ÿ›‘ **Block** dangerous AI actions before they run โ€” `rm -rf`, `git push --force`, `DROP TABLE`, credential reads, `curl | bash`
50
- - ๐Ÿ” **Scan** what your AI agent has already been doing โ€” loops, leaked secrets, blocked operations across every session
51
- - ๐Ÿ”‘ **Catch credential leaks** โ€” AWS keys, GitHub tokens, JWTs, GCP API keys, PEM private keys flagged in tool arguments, file contents Claude reads back, and shell config files
52
- - ๐Ÿ”ญ **Map your blast radius** โ€” every SSH key, AWS credential, and `.env` file an AI agent on this machine could reach right now
53
-
54
- Works with **Claude Code ยท Cursor ยท Codex ยท Gemini CLI ยท any MCP server**.
55
-
56
- ---
57
-
58
- ## How is this different from gitleaks / Snyk / TruffleHog?
59
-
60
- Those scan **repositories** for credentials. Node9 scans **AI agent session history** โ€” what your AI ran, what it read, what credentials passed through tool calls. Different surface area.
61
-
62
- Node9 catches things gitleaks can't:
63
-
64
- - Credentials the AI read but never committed
65
- - Agent edit loops that burn tokens on retries
66
- - Dangerous shell commands the AI ran without confirmation
67
- - Blast radius โ€” which credential files an AI agent on this machine could reach right now
68
-
69
- Run gitleaks for committed code. Run Node9 for AI session history.
70
-
71
- ---
57
+ Run it on yours โ€” `npx node9-ai scan` finishes in ~10 seconds and runs entirely local. Nothing uploads.
72
58
 
73
59
  ## Install
74
60
 
@@ -85,11 +71,9 @@ node9 init # auto-wires Claude Code, Gemini CLI, Cursor, Codex, MCP server
85
71
  node9 doctor # verify everything is wired correctly
86
72
  ```
87
73
 
88
- That's it โ€” future agent sessions are protected.
89
-
90
- ---
74
+ Requires Node.js 18+.
91
75
 
92
- ## Shields โ€” expert policy in one command
76
+ ## Shields โ€” curated rule packs
93
77
 
94
78
  Each shield is a curated rule set for a service or domain. Enable only what you need.
95
79
 
@@ -111,21 +95,17 @@ Each shield is a curated rule set for a service or domain. Enable only what you
111
95
  node9 shield list # show all shields + status
112
96
  ```
113
97
 
114
- ---
115
-
116
98
  ## Always on โ€” no config needed
117
99
 
118
100
  - **Git** โ€” blocks `git push --force`, `git reset --hard`, `git clean -fd`
119
101
  - **SQL** โ€” blocks `DELETE` / `UPDATE` without `WHERE`, `DROP TABLE`, `TRUNCATE`
120
102
  - **Shell** โ€” blocks `curl | bash`, unauthorized `sudo`
121
- - **DLP** โ€” blocks AWS keys, GitHub tokens, Stripe keys, PEM private keys in any tool argument, file Claude reads, or shell config (`~/.zshrc`, `~/.bashrc`)
122
- - **Response DLP** โ€” background scanner reads Claude's conversation history and alerts you if Claude _wrote_ a secret in its response text (not just executed one). Gemini / Codex coverage coming.
103
+ - **DLP** โ€” blocks AWS keys, GitHub tokens, Stripe keys, PEM private keys in any tool argument, file contents, or shell config (`~/.zshrc`, `~/.bashrc`)
104
+ - **Response DLP** โ€” background scanner reads Claude's conversation history and alerts you if Claude _wrote_ a secret in its response text
123
105
  - **Auto-undo** โ€” git snapshot before every AI file edit โ†’ `node9 undo` to revert
124
106
  - **Skills pinning** โ€” SHA-256 verification of installed Claude skills / plugins between sessions
125
107
 
126
- ---
127
-
128
- ## MCP gateway โ€” protect any MCP server
108
+ ## MCP gateway
129
109
 
130
110
  Wrap any MCP server transparently. The agent sees the same server โ€” Node9 intercepts every tool call.
131
111
 
@@ -159,64 +139,45 @@ node9 mcp pin update <serverKey> # remove pin, re-pin on next connection
159
139
  node9 mcp pin reset # clear all pins
160
140
  ```
161
141
 
162
- Automatic, no configuration. The gateway pins on first `tools/list` and enforces on every subsequent session.
163
-
164
- </details>
165
-
166
- <details>
167
- <summary><strong>โšก Large MCP response detection</strong></summary>
168
-
169
- When an MCP server returns a 500KB+ response, it sits in the context window for every subsequent LLM turn โ€” often silently doubling per-turn cost. Node9 warns you in real time with a toast and records the event in the dashboard so you can spot the offender.
170
-
171
142
  </details>
172
143
 
173
- ---
174
-
175
144
  ## Observability โ€” five views
176
145
 
177
- Every tool call is recorded โ€” command, arguments, decision, cost. See what your agent did, five ways:
178
-
179
146
  | Command | What it shows | When to use |
180
147
  | ---------------- | --------------------------------------------------------- | ----------------------------------------- |
181
148
  | `node9 blast` | What an AI agent can reach right now โ€” files, creds, env | First thing to run on any machine |
182
149
  | `node9 scan` | Retrospective audit of existing agent history | Before installing, or to review past risk |
183
- | `node9 mask` | Redact plaintext secrets from local session history files | After a DLP finding โ€” cleans local disk |
184
150
  | `node9 tail` | Live stream of every tool call | Watching an agent work in real time |
185
151
  | `node9 report` | Per-period summary: allowed/blocked/DLP/cost + top tools | Reviewing what happened after a session |
186
152
  | `node9 sessions` | Session history with prompt, tool trace, cost, snapshot | Reviewing a handoff or past work |
187
153
  | `node9 dlp` | Credential-leak findings in Claude response text | Any time a DLP desktop alert fires |
154
+ | `node9 mask` | Redact plaintext secrets from local session history files | After a DLP finding โ€” cleans local disk |
188
155
 
189
156
  Plus a **live HUD** in your Claude Code statusline:
190
157
 
191
158
  ```
192
159
  ๐Ÿ›ก node9 | standard | [bash-safe] | โœ… 12 allowed ๐Ÿ›‘ 2 blocked ๐Ÿšจ 0 dlp | ~$0.43
193
- ๐Ÿ“Š claude-opus-4-6 | ctx [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘] 54% | 5h [โ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘] 12% | 7d [โ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘] 7%
160
+ ๐Ÿ“Š claude-opus-4-7 | ctx [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘] 54% | 5h [โ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘] 12% | 7d [โ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘] 7%
194
161
  ๐Ÿ—‚ 2 CLAUDE.md | 8 rules | 3 MCPs | 4 hooks
195
162
  ```
196
163
 
197
- And a **browser dashboard** that auto-opens after `node9 scan` โ€” History Audit modal with full drill-down, per-agent breakdown, loop-cost estimate, and live status strip.
198
-
199
- ---
200
-
201
164
  ## Reading the data โ€” what the numbers mean
202
165
 
203
166
  Node9 surfaces the signal. Here are the patterns worth knowing:
204
167
 
205
- | Signal | Likely meaning |
206
- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
207
- | `Would have blocked` โ‰ฅ 5 in a week | Agent is attempting destructive ops; shields need review |
208
- | Single `review-git-push` rule accounts for >50% of findings | Your own rule is firing as intended โ€” not a risk, just supervision |
209
- | DLP finding in `user-prompt` tool | You pasted a secret into your own prompt โ€” rotate the key |
210
- | Agent Loop ร—50+ on same file | Agent stuck in edit/test/fix cycle โ€” check context or slow down |
211
- | MCP tool pin mismatch | Server changed its tools โ€” review before re-trusting |
212
- | Large MCP response warning | That server is inflating your context window for every subsequent turn |
213
- | `Response DLP` alert | Claude wrote a secret in its response text โ€” not blocked, rotate immediately |
214
- | DLP finding in `tool-result` | Claude read a file containing a secret (`.env`, credentials) โ€” rotate the key and run `node9 mask` |
215
- | DLP finding in `[Shell]` | Plaintext secret in `~/.zshrc` or `~/.bashrc` โ€” every AI session can see it |
216
-
217
- These are starting points, not verdicts. One-off signals are normal; persistent patterns are what you act on.
168
+ | Signal | Likely meaning |
169
+ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
170
+ | `Would have blocked` โ‰ฅ 5 in a week | Agent is attempting destructive ops; shields need review |
171
+ | Single `review-git-push` rule >50% of findings | Your own rule is firing as intended โ€” not a risk, just supervision |
172
+ | DLP finding in `user-prompt` tool | You pasted a secret into your own prompt โ€” rotate the key |
173
+ | Agent Loop ร—50+ on same file | Agent stuck in edit/test/fix cycle โ€” check context or slow down |
174
+ | MCP tool pin mismatch | Server changed its tools โ€” review before re-trusting |
175
+ | Large MCP response warning | That server is inflating your context window for every subsequent turn |
176
+ | `Response DLP` alert | Claude wrote a secret in its response text โ€” not blocked, rotate immediately |
177
+ | DLP finding in `tool-result` | Claude read a file containing a secret (`.env`, credentials) โ€” rotate the key and run `node9 mask` |
178
+ | DLP finding in `[Shell]` | Plaintext secret in `~/.zshrc` or `~/.bashrc` โ€” every AI session can see it |
218
179
 
219
- ---
180
+ One-off signals are normal; persistent patterns are what you act on.
220
181
 
221
182
  ## Python SDK โ€” govern any Python agent
222
183
 
@@ -232,8 +193,6 @@ def run_command(cmd: str) -> str:
232
193
 
233
194
  **[Python SDK โ†’](https://github.com/node9-ai/node9-python)** ยท **[CI code review agent example โ†’](https://github.com/node9-ai/node9-pr-agent)**
234
195
 
235
- ---
236
-
237
196
  ## Under the hood
238
197
 
239
198
  - **Scan** reads raw agent history from `~/.claude/projects/`, `~/.gemini/tmp/`, `~/.codex/sessions/` โ€” no API calls, fully offline
@@ -242,26 +201,22 @@ def run_command(cmd: str) -> str:
242
201
  - **Policy engine** uses [mvdan-sh](https://github.com/mvdan/sh) for bash AST analysis โ€” defeats obfuscation via backslash escaping, variable substitution, eval of remote download
243
202
  - **Shadow repo** for auto-undo lives at `~/.node9/snapshots/<hash16>/` โ€” never touches your `.git`
244
203
 
245
- ---
246
-
247
- ## ๐Ÿ“– Full docs
204
+ ## Full docs
248
205
 
249
- Everything else โ€” config reference, smart rules, stateful rules, trusted hosts, approval modes, Slack integration, CLI reference โ€” is at **[node9.ai/docs](https://node9.ai/docs)**.
250
-
251
- ---
206
+ Config reference, smart rules, stateful rules, trusted hosts, approval modes, CLI reference โ€” at **[node9.ai/docs](https://node9.ai/docs)**.
252
207
 
253
208
  ## Related projects
254
209
 
255
- - **[node9-python](https://github.com/node9-ai/node9-python)** โ€” Python SDK for governed agents
256
- - **[node9-pr-agent](https://github.com/node9-ai/node9-pr-agent)** โ€” GitHub Action that reviews PRs through Node9 (reference implementation of a governed agent)
257
-
258
- ---
210
+ - **[node9-python](https://github.com/node9-ai/node9-python)** โ€” Python SDK
211
+ - **[node9-pr-agent](https://github.com/node9-ai/node9-pr-agent)** โ€” GitHub Action that reviews PRs through Node9
259
212
 
260
213
  ## Enterprise
261
214
 
262
215
  **Node9 Pro** adds governance locking, SAML/SSO, central audit export, and VPC deployment. See [node9.ai](https://node9.ai).
263
216
 
264
- ---
217
+ ## License
218
+
219
+ Apache-2.0
265
220
 
266
221
  <p align="center">
267
222
  <sub>Built with โ˜• and healthy paranoia.</sub>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node9-ai",
3
- "version": "1.19.3",
3
+ "version": "1.20.0",
4
4
  "description": "Security layer for AI coding agents โ€” intercepts dangerous tool calls before they execute",
5
5
  "keywords": [
6
6
  "ai",
@@ -25,7 +25,7 @@
25
25
  "node9-ai": "bin/node9.js"
26
26
  },
27
27
  "dependencies": {
28
- "@node9/proxy": "1.19.3"
28
+ "@node9/proxy": "1.20.0"
29
29
  },
30
30
  "type": "module",
31
31
  "engines": {