@node9/proxy 1.0.13 → 1.0.15

package/README.md

@@ -29,7 +29,7 @@ While others try to _guess_ if a prompt is malicious (Semantic Security), Node9
 
 ---
 
-## ⚡ Key Architectural Upgrades
+## ⚡ Key Features
 
 ### 🏁 The Multi-Channel Race Engine
 
@@ -40,9 +40,39 @@ Node9 initiates a **Concurrent Race** across all enabled channels. The first cha
 - **Cloud (Slack):** Remote asynchronous approval for team governance.
 - **Terminal:** Classic `[Y/n]` prompt for manual proxy usage and SSH sessions.
 
+### 🛰️ Flight Recorder — See Everything, Instantly
+
+Node9 records every tool call your AI agent makes in real-time — no polling, no log files, no refresh. Two ways to watch:
+
+**Browser Dashboard** (`node9 daemon start` → `localhost:7391`)
+
+A live 3-column dashboard. The left column streams every tool call as it happens, updating in-place from `● PENDING` to `✓ ALLOW` or `✗ BLOCK`. The center handles pending approvals. The right sidebar controls shields and persistent decisions — all without ever causing a browser scrollbar.
+
+**Terminal** (`node9 tail`)
+
+A split-pane friendly stream for terminal-first developers and SSH sessions:
+
+```bash
+node9 tail                # live events only
+node9 tail --history      # replay recent history then go live
+node9 tail | grep DLP     # filter to DLP blocks only
+```
+
+```
+🛰️  Node9 tail  → localhost:7391
+Showing live events. Press Ctrl+C to exit.
+
+21:06:58 📖 Read            {"file_path":"src/core.ts"}            ✓ ALLOW
+21:06:59 🔍 Grep            {"pattern":"authorizeHeadless"}        ✓ ALLOW
+21:07:01 💻 Bash            {"command":"npm run build"}            ✓ ALLOW
+21:07:04 💻 Bash            {"command":"curl … Bearer sk-ant-…"}   ✗ BLOCK 🛡️ DLP
+```
+
+`node9 tail` auto-starts the daemon if it isn't running — no setup step needed.
+
 ### 🧠 AI Negotiation Loop
 
-Node9 doesn't just "cut the wire." When a command is blocked, it injects a **Structured Negotiation Prompt** back into the AI’s context window. This teaches the AI why it was stopped and instructs it to pivot to a safer alternative or apologize to the human.
+Node9 doesn't just "cut the wire." When a command is blocked, it injects a **Structured Negotiation Prompt** back into the AI's context window. This teaches the AI why it was stopped and instructs it to pivot to a safer alternative.
 
 ### ⏪ Shadow Git Snapshots (Auto-Undo)
 
@@ -56,41 +86,11 @@ node9 undo
 node9 undo --steps 3
 ```
 
-Example output:
-
-```
-⏪  Node9 Undo
-    Tool:  str_replace_based_edit_tool → src/app.ts
-    When:  2m ago
-    Dir:   /home/user/my-project
-
---- src/app.ts (snapshot)
-+++ src/app.ts (current)
-@@ -1,4 +1,6 @@
--const x = 1;
-+const x = 99;
-+const y = "hello";
-
-Revert to this snapshot? [y/N]
-```
-
-Node9 keeps the last 10 snapshots. Snapshots are only taken for file-writing tools (`write_file`, `edit_file`, `str_replace_based_edit_tool`, `create_file`) — not for read-only or shell commands.
-
-### 🌊 The Resolution Waterfall
-
-Security posture is resolved using a strict 5-tier waterfall:
-
-1.  **Env Vars:** Session-level overrides (e.g., `NODE9_PAUSED=1`).
-2.  **Cloud (SaaS):** Global organization "Locks" that cannot be bypassed locally.
-3.  **Project Config:** Repository-specific rules (`node9.config.json`).
-4.  **Global Config:** Personal UI preferences (`~/.node9/config.json`).
-5.  **Defaults:** The built-in safety net.
-
 ---
 
 ## 🎮 Try it Live
 
-No install needed — test Node9's AST parser against real commands in the browser:
+No install needed — test Node9's policy engine against real commands in the browser:
 
 [![Open in HF Spaces](https://huggingface.co/datasets/huggingface/badges/resolve/main/open-in-hf-spaces-sm.svg)](https://huggingface.co/spaces/Node9ai/node9-security-demo)
 
@@ -106,19 +106,91 @@ brew install node9
 # Or via npm
 npm install -g @node9/proxy
 
-# 1. Setup protection for your favorite agent
+# 1. Wire Node9 to your agent
 node9 setup           # interactive menu — picks the right agent for you
 node9 addto claude    # or wire directly
 node9 addto gemini
 
-# 2. Initialize your local safety net
-node9 init
+# 2. Enable shields for the services you use
+node9 shield enable postgres
+node9 shield enable aws
 
 # 3. Verify everything is wired correctly
 node9 doctor
+```
+
+---
+
+## 🛡️ How Protection Works
+
+Node9 has two layers of protection. You get Layer 1 automatically. Layer 2 is one command per service.
+
+### Layer 1 — Core Protection (Always On)
+
+Built into the binary. Zero configuration required. Protects the tools every developer uses.
 
-# 4. Check your status
-node9 status
+| What it protects  | Example blocked action                                  |
+| :---------------- | :------------------------------------------------------ |
+| **Git**           | `git push --force`, `git reset --hard`, `git clean -fd` |
+| **Shell**         | `curl ... \| bash`, `sudo` commands                     |
+| **SQL**           | `DELETE` / `UPDATE` without a `WHERE` clause            |
+| **Filesystem**    | `rm -rf` targeting home directory                       |
+| **Secrets (DLP)** | AWS keys, GitHub tokens, Stripe keys, PEM private keys  |
+
+### 🔍 DLP — Content Scanner (Always On)
+
+Node9 scans **every tool call argument** for secrets before the command reaches your agent. If a credential is detected, Node9 hard-blocks the action, redacts the secret in the audit log, and injects a negotiation prompt telling the AI what went wrong.
+
+**Built-in patterns:**
+
+| Pattern           | Severity | Prefix format               |
+| :---------------- | :------- | :-------------------------- |
+| AWS Access Key ID | `block`  | `AKIA` + 16 chars           |
+| GitHub Token      | `block`  | `ghp_`, `gho_`, `ghs_`      |
+| Slack Bot Token   | `block`  | `xoxb-`                     |
+| OpenAI API Key    | `block`  | `sk-` + 20+ chars           |
+| Stripe Secret Key | `block`  | `sk_live_` / `sk_test_`     |
+| PEM Private Key   | `block`  | `-----BEGIN PRIVATE KEY---` |
+| Bearer Token      | `review` | `Authorization: Bearer ...` |
+
+`block` = hard deny, no approval prompt. `review` = routed through the normal race engine for human approval.
+
+Secrets are **never logged in full** — the audit trail stores only a redacted sample (`AKIA****MPLE`).
+
+**Config knobs** (in `node9.config.json` or `~/.node9/config.json`):
+
+```json
+{
+  "policy": {
+    "dlp": {
+      "enabled": true,
+      "scanIgnoredTools": true
+    }
+  }
+}
+```
+
+| Key                    | Default | Description                                                        |
+| :--------------------- | :------ | :----------------------------------------------------------------- |
+| `dlp.enabled`          | `true`  | Master switch — disable to turn off all DLP scanning               |
+| `dlp.scanIgnoredTools` | `true`  | Also scan tools in `ignoredTools` (e.g. `web_search`, `read_file`) |
+
+### Layer 2 — Shields (Opt-in, Per Service)
+
+Shields add protection for specific infrastructure and services — only relevant if you actually use them.
+
+| Shield       | What it protects                                                              |
+| :----------- | :---------------------------------------------------------------------------- |
+| `postgres`   | Blocks `DROP TABLE`, `TRUNCATE`, `DROP COLUMN`; reviews `GRANT`/`REVOKE`      |
+| `github`     | Blocks `gh repo delete`; reviews remote branch deletion                       |
+| `aws`        | Blocks S3 bucket deletion, EC2 termination; reviews IAM changes, RDS deletion |
+| `filesystem` | Reviews `chmod 777`, writes to `/etc/`                                        |
+
+```bash
+node9 shield enable postgres    # protect your database
+node9 shield enable aws         # protect your cloud infrastructure
+node9 shield list               # see all available shields
+node9 shield status             # see what's currently active
 ```
 
 ---
@@ -133,78 +205,55 @@ node9 status
 
 ---
 
-## ⚙️ Configuration (`node9.config.json`)
+## 🔗 Configuration Precedence
+
+Node9 merges configuration from multiple sources in priority order. Higher tiers win:
+
+| Tier | Source                    | Notes                                                     |
+| :--- | :------------------------ | :-------------------------------------------------------- |
+| 1    | **Environment variables** | `NODE9_MODE=strict` overrides everything                  |
+| 2    | **Cloud / Org policy**    | Set in the Node9 dashboard — cannot be overridden locally |
+| 3    | **Project config**        | `node9.config.json` in the working directory              |
+| 4    | **Global config**         | `~/.node9/config.json`                                    |
+| 5    | **Built-in defaults**     | Always active, no config needed                           |
+
+**Settings** (mode, approvers, timeouts) follow the table above — higher tier wins. A project config overrides a global config.
+
+**Smart rules** work differently. All layers are concatenated into a single ordered list and evaluated first-match-wins:
+
+```
+built-in defaults → global config → project config → shields → advisory defaults
+```
+
+Because built-in `block` rules sit at the front of this list, they always fire before any user-defined `allow` rule. **A project or global config cannot bypass Layer 1 protection.** Within the user layers, a project `block` rule fires before a shield `block` rule — so project policy can tighten or selectively override a shield.
+
+---
+
+## ⚙️ Custom Rules (Advanced)
 
-Rules are **merged additive**—you cannot "un-danger" a word locally if it was defined as dangerous by a higher authority (like the Cloud).
+Most users never need this. If you need protection beyond Layer 1 and the available shields, add **Smart Rules** to `node9.config.json` in your project root or `~/.node9/config.json` globally.
+
+Smart Rules match on **raw tool arguments** using structured conditions:
 
 ```json
 {
-  "settings": {
-    "mode": "standard",
-    "enableUndo": true,
-    "approvalTimeoutMs": 30000,
-    "approvers": {
-      "native": true,
-      "browser": true,
-      "cloud": true,
-      "terminal": true
-    }
-  },
   "policy": {
-    "sandboxPaths": ["/tmp/**", "**/test-results/**"],
-    "dangerousWords": ["drop", "destroy", "purge", "push --force"],
-    "ignoredTools": ["list_*", "get_*", "read_*"],
-    "toolInspection": {
-      "bash": "command",
-      "postgres:query": "sql"
-    },
-    "rules": [
-      { "action": "rm", "allowPaths": ["**/node_modules/**", "dist/**"] },
-      { "action": "push", "blockPaths": ["**"] }
-    ],
     "smartRules": [
       {
-        "name": "no-delete-without-where",
-        "tool": "*",
+        "name": "block-prod-deploy",
+        "tool": "bash",
         "conditions": [
-          { "field": "sql", "op": "matches", "value": "^(DELETE|UPDATE)\\s", "flags": "i" },
-          { "field": "sql", "op": "notMatches", "value": "\\bWHERE\\b", "flags": "i" }
+          { "field": "command", "op": "matches", "value": "kubectl.*--namespace=production" }
         ],
-        "verdict": "review",
-        "reason": "DELETE/UPDATE without WHERE — would affect every row"
+        "verdict": "block",
+        "reason": "Deploying to production requires a manual release process"
       }
     ]
   }
 }
 ```
 
-### ⚙️ `settings` options
-
-| Key                  | Default      | Description                                                  |
-| :------------------- | :----------- | :----------------------------------------------------------- |
-| `mode`               | `"standard"` | `standard` \| `strict` \| `audit`                            |
-| `enableUndo`         | `true`       | Take git snapshots before every AI file edit                 |
-| `approvalTimeoutMs`  | `0`          | Auto-deny after N ms if no human responds (0 = wait forever) |
-| `approvers.native`   | `true`       | OS-native popup                                              |
-| `approvers.browser`  | `true`       | Browser dashboard (`node9 daemon`)                           |
-| `approvers.cloud`    | `true`       | Slack / SaaS approval                                        |
-| `approvers.terminal` | `true`       | `[Y/n]` prompt in terminal                                   |
-
-### 🧠 Smart Rules
-
-Smart rules match on **raw tool arguments** using structured conditions — more powerful than `dangerousWords` or `rules`, which only see extracted tokens.
-
-```json
-{
-  "name": "curl-pipe-to-shell",
-  "tool": "bash",
-  "conditions": [{ "field": "command", "op": "matches", "value": "curl.+\\|.*(bash|sh)" }],
-  "verdict": "block",
-  "reason": "curl piped to shell — remote code execution risk"
-}
-```
-
-**Fields:**
+**Smart Rule fields:**
 
 | Field           | Description                                                                          |
 | :-------------- | :----------------------------------------------------------------------------------- |
@@ -216,33 +265,50 @@ Smart rules match on **raw tool arguments** using structured conditions — more
 
 **Condition operators:**
 
-| `op`          | Meaning                                                             |
-| :------------ | :------------------------------------------------------------------ |
-| `matches`     | Field value matches regex (`value` = pattern, `flags` = e.g. `"i"`) |
-| `notMatches`  | Field value does not match regex                                    |
-| `contains`    | Field value contains substring                                      |
-| `notContains` | Field value does not contain substring                              |
-| `exists`      | Field is present and non-empty                                      |
-| `notExists`   | Field is absent or empty                                            |
+| `op`             | Meaning                                                                    |
+| :--------------- | :------------------------------------------------------------------------- |
+| `matches`        | Field value matches regex (`value` = pattern, `flags` = e.g. `"i"`)        |
+| `notMatches`     | Field value does not match regex (`value` = pattern, `flags` optional)     |
+| `contains`       | Field value contains substring                                             |
+| `notContains`    | Field value does not contain substring                                     |
+| `exists`         | Field is present and non-empty                                             |
+| `notExists`      | Field is absent or empty                                                   |
+| `matchesGlob`    | Field value matches a glob pattern (`value` = e.g. `"**/node_modules/**"`) |
+| `notMatchesGlob` | Field value does not match a glob pattern                                  |
 
 The `field` key supports dot-notation for nested args: `"params.query.sql"`.
 
-**Built-in default smart rule** (always active, no config needed):
+Use `node9 explain <tool> <args>` to dry-run any tool call and see exactly which rule would trigger.
+
+### Settings
 
 ```json
 {
-  "name": "no-delete-without-where",
-  "tool": "*",
-  "conditions": [
-    { "field": "sql", "op": "matches", "value": "^(DELETE|UPDATE)\\s", "flags": "i" },
-    { "field": "sql", "op": "notMatches", "value": "\\bWHERE\\b", "flags": "i" }
-  ],
-  "verdict": "review",
-  "reason": "DELETE/UPDATE without WHERE clause — would affect every row in the table"
+  "settings": {
+    "mode": "standard",
+    "enableUndo": true,
+    "approvalTimeoutMs": 30000,
+    "approvers": {
+      "native": true,
+      "browser": true,
+      "cloud": true,
+      "terminal": true
+    }
+  }
 }
 ```
 
-Use `node9 explain <tool> <args>` to dry-run any tool call and see exactly which smart rule (or other policy tier) would trigger.
+| Key                  | Default      | Description                                                  |
+| :------------------- | :----------- | :----------------------------------------------------------- |
+| `mode`               | `"standard"` | `standard` \| `strict` \| `audit`                            |
+| `enableUndo`         | `true`       | Take git snapshots before every AI file edit                 |
+| `approvalTimeoutMs`  | `0`          | Auto-deny after N ms if no human responds (0 = wait forever) |
+| `approvers.native`   | `true`       | OS-native popup                                              |
+| `approvers.browser`  | `true`       | Browser dashboard (`node9 daemon`)                           |
+| `approvers.cloud`    | `true`       | Slack / SaaS approval                                        |
+| `approvers.terminal` | `true`       | `[Y/n]` prompt in terminal                                   |
+
+---
 
 ## 🖥️ CLI Reference
 
@@ -253,14 +319,14 @@ Use `node9 explain <tool> <args>` to dry-run any tool call and see exactly which
 | `node9 init`                  | Create default `~/.node9/config.json`                                                 |
 | `node9 status`                | Show current protection status and active rules                                       |
 | `node9 doctor`                | Health check — verifies binaries, config, credentials, and all agent hooks            |
+| `node9 shield <cmd>`          | Manage shields (`enable`, `disable`, `list`, `status`)                                |
+| `node9 tail [--history]`      | Stream live agent activity to the terminal (auto-starts daemon if needed)             |
 | `node9 explain <tool> [args]` | Trace the policy waterfall for a given tool call (dry-run, no approval prompt)        |
 | `node9 undo [--steps N]`      | Revert the last N AI file edits using shadow Git snapshots                            |
 | `node9 check`                 | Called by agent hooks; evaluates a pending tool call and exits 0 (allow) or 1 (block) |
 
 ### `node9 doctor`
 
-Runs a full self-test and exits 1 if any required check fails:
-
 ```
 Node9 Doctor  v1.2.0
 ────────────────────────────────────────
@@ -283,7 +349,7 @@ All checks passed ✅
 
 ### `node9 explain`
 
-Dry-runs the policy engine and prints exactly which rule (or waterfall tier) would block or allow a given tool call — useful for debugging your config:
+Dry-runs the policy engine and prints exactly which rule would fire — useful for debugging:
 
 ```bash
 node9 explain bash '{"command":"rm -rf /tmp/build"}'
@@ -294,9 +360,6 @@ Policy Waterfall for: bash
 ──────────────────────────────────────────────
 Tier 1 · Cloud Org Policy       SKIP  (no org policy loaded)
 Tier 2 · Dangerous Words        BLOCK ← matched "rm -rf"
-Tier 3 · Path Block             –
-Tier 4 · Inline Exec            –
-Tier 5 · Rule Match             –
 ──────────────────────────────────────────────
 Verdict: BLOCK  (dangerous word: rm -rf)
 ```
@@ -324,6 +387,12 @@ A corporate policy has locked this action. You must click the "Approve" button i
 - [x] **Native OS Dialogs** (Sub-second approval via Mac/Win/Linux system windows)
 - [x] **Shadow Git Snapshots** (1-click Undo for AI hallucinations)
 - [x] **Identity-Aware Execution** (Differentiates between Human vs. AI risk levels)
+- [x] **Shield Templates** (`node9 shield enable <service>` — one-click protection for Postgres, GitHub, AWS)
+- [x] **Content Scanner / DLP** (Detect and block secrets like AWS keys and Bearer tokens in-flight)
+- [x] **Flight Recorder** (Real-time activity stream in browser dashboard and `node9 tail` terminal view)
+- [ ] **Universal MCP Gateway** (Standalone security tunnel for LangChain, CrewAI, and any agent without native hooks)
+- [ ] **Cursor & Windsurf Hook** (Native hook support for AI-first IDEs)
+- [ ] **VS Code Extension** (Approval requests in a native sidebar — no more OS popups)
 - [ ] **Execution Sandboxing** (Simulate dangerous commands in a virtual FS before applying)
 - [ ] **Multi-Admin Quorum** (Require 2+ human signatures for high-stakes production actions)
 - [ ] **SOC2 Tamper-proof Audit Trail** (Cryptographically signed, cloud-managed logs)