@node9/proxy 2.17.0 → 2.18.0

package/README.md

@@ -11,6 +11,53 @@
   <a href="https://github.com/node9-ai/node9-proxy/blob/main/.github/workflows/agent-security.yml"><img src="https://img.shields.io/badge/node9-self--scanned-a855f7?style=flat&labelColor=%231A1A2E&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNCAxNCI+PHBhdGggZmlsbD0iI0Y1RTlGRiIgZmlsbC1ydWxlPSJldmVub2RkIiBjbGlwLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik03IDAuNCAxLjYgMi41djQuMmMwIDMuMSAyLjMgNS42IDUuNCA2LjkgMy4xLTEuMyA1LjQtMy44IDUuNC02LjlWMi41TDcgMC40Wm0wIDEuNSAzLjkgMS41djMuM2MwIDIuMy0xLjYgNC4yLTMuOSA1LjMtMi4zLTEuMS0zLjktMy0zLjktNS4zVjMuNEw3IDEuOVptMCAyLjJhMS45IDEuOSAwIDAgMC0xIDMuNXYxLjZoMlY3LjZhMS45IDEuOSAwIDAgMC0xLTMuNVoiLz48L3N2Zz4K" alt="node9 self-scanned" /></a>
 </p>
 
+**Credential jail** · **secrets and PII** · **destructive git, SQL and shell held for review** ·
+**MCP tool pinning** · **network egress allowlist** · **loop breaker** · **one record across twelve agents**
+
+Works with **Claude Code · Codex CLI · Antigravity (agy) · GitHub Copilot CLI · Gemini CLI · Cursor · Windsurf · VSCode · Claude Desktop · Opencode · Pi · Hermes Agent · any MCP server**.
+
+## What it looks like
+
+Your agent on the left, node9 on the right. Every tool call the agent makes is
+checked before it runs: allowed and recorded, held for your approval, or blocked.
+The agent here was launched with `--dangerously-skip-permissions`, and node9 still
+decides.
+
+<!-- VIDEO: drag monitor-loop.mp4 into a GitHub comment to get its user-attachments
+     URL, then replace this block. GitHub plays mp4 from that host; npm will not
+     render it, which is why the scan screenshot below stays. -->
+
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/4661da97-c174-4bae-ae54-4c52a1d69213" width="760" alt="node9 monitor: live tool calls, decisions, shields and score" />
+</p>
+
+## Install
+
+```bash
+brew tap node9-ai/node9 && brew install node9   # macOS / Linux
+npm install -g node9-ai                         # any platform
+```
+
+Then, in any project:
+
+```bash
+node9 init       # finds your agents and MCP servers and puts node9 in front of every tool call
+node9 posture    # scores this machine 0-100: what a compromised agent could read, reach and run
+node9 login      # optional: adds this machine to a shared dashboard
+```
+
+Requires Node.js 22+.
+
+**`init` is the whole product.** It writes the hooks, turns on the credential jail
+and the always-on rules, and starts enforcing immediately. Nothing leaves the
+machine and no account is needed.
+
+**`login` adds nothing to enforcement.** It connects the machine to a workspace so
+a team can see one record across everyone's laptops and CI, set policy centrally,
+and approve held actions from a dashboard or Slack. Skip it and node9 works exactly
+the same, alone, offline. `node9 logout` disconnects again and local enforcement
+keeps running.
+
 ## The problem
 
 In August 2025, compromised releases of the
@@ -54,341 +101,43 @@ that file. `node9 egress protect` gates destinations as well, and it covers shel
 
 ## Verify it yourself
 
-```bash
-npx node9-ai scan                                       # every past agent session on this machine, ~10s, nothing uploads
-npx node9-ai scan-repo node9-ai/agent-security-demo    # a public repo with a real, hijackable agent workflow
-npx node9-ai posture                                    # this machine's exposure in 60s, nothing uploads
-gh attestation verify cli.js --repo node9-ai/node9-proxy  # every release artifact is signed
-```
-
----
-
-Three jobs, one tool: **discover** what your agents have already done, **protect** against risky actions in real time, and **review** what happened over any time window.
-
-Works with **Claude Code · Codex CLI · Antigravity (agy) · GitHub Copilot CLI · Gemini CLI · Cursor · Windsurf · VSCode · Claude Desktop · Opencode · Pi · Hermes Agent · any MCP server**.
-
-## What node9 does
-
-- 🔍 **Discover**: scan every past AI session for credential leaks, agent loops, blocked operations, and every secret on disk an agent could reach right now
-- 🛡 **Protect**: review or block risky commands before they run, such as `rm -rf`, `git push --force`, `DROP TABLE`, credential reads, `curl | bash`, and AWS/GitHub/Stripe key leaks
-- 📊 **Review**: a period-windowed report (today / week / month / 90 days) of cost per agent, top tools, shields fired, and blast radius
-
-## Retrospective scan
-
-This is my own machine, 90 days while building node9. Score 25/100, 5 credential files an AI agent could reach right now.
+Nothing below needs an account, and nothing uploads.
 
 ```bash
-npx node9-ai scan   # before installation, runs in ~10s, nothing uploads
-node9 scan          # after installation, same output
+npx node9-ai scan                                        # every past agent session on this machine
+npx node9-ai scan-repo node9-ai/agent-security-demo      # a public repo with a real, hijackable agent workflow
+gh attestation verify cli.js --repo node9-ai/node9-proxy # every release artifact is signed
 ```
 
 <p align="center">
   <img src="https://github.com/user-attachments/assets/7c5b30f1-1ca1-40b4-bfd5-d6671002e98e" width="720" alt="node9 scan scorecard" />
 </p>
 
-## Security posture scorecard
-
-`node9 posture` grades how exposed this machine is to a compromised agent across isolation, egress, secrets on disk, supply chain, and privilege, and hands you the exact command to fix each finding.
-
-```bash
-node9 posture          # scorecard with the #1 risk and a fix for every finding
-node9 posture --ship   # send a redacted snapshot to your node9 dashboard (fleet view)
-```
-
-Findings are grouped by **who can fix them**: 🔒 the ones node9 reduces (just run the command) and 🧱 the ones only you can. Each carries a plain-language what / why / who and a real remediation. For example, the "agent runs unsandboxed on the host" finding points straight at `node9 sandbox run` (below).
-
-```text
-🛡️  Node9 Posture — agent on this host        Score: 100/100  (Good)
-  2 advisories below don't affect the score — OS-level exposure, yours to weigh.
-
-  🟢 node9 is already protecting you
-  ✅ Secrets        node9 DLP is blocking this
-  ✅ Egress         node9 egress is approval-gating this
-  ✅ Approval gate  node9 is blocking this
-  ✅ Privilege      node9 is approval-gating this
-
-  🔒 node9 reduces these — run the command, the rest is yours
-  ⚠️  Isolation     Running directly on the host — no container
-                   The agent runs loose on your whole machine, not in a sandbox.
-                   → node9 sandbox run <agent>   — jail it: kernel egress + scoped mounts + node9 inside
-                   → node9 shield enable project-jail   — or shrink the blast radius, keep host access
-  ⚠️  Network exposure  4 services on 0.0.0.0 (node :3000/:4000, PostgreSQL :5432, Redis :6379)
-                   Reachable from your whole network, not just this laptop.
-                   → node9 shield enable postgres|redis   — node9 blocks DROP TABLE / FLUSHALL
-                   → bind to 127.0.0.1 / firewall the port   (your part)
-
-  ✅ Supply chain   no issues found
-  ✅ Coverage       no issues found
-
-  Track this across your fleet & keep it green → node9.ai
-```
-
-## Scan a repo: agent-CI security
-
-`node9 scan-repo` checks any repo (or a local folder) for ways an AI agent wired into GitHub Actions could be **hijacked by an outsider**: injectable workflows, agent-reachable secrets, unpinned MCP servers, over-broad agent config, and poisoned instruction files. Static and parse-only: it reads only committed config, never executes repo code. No install or token needed for public repos.
-
-```bash
-npx node9-ai scan-repo <owner/repo>   # any public repo, no install
-node9 scan-repo .                      # a local checkout, no network
-node9 scan-repo <owner/repo> --json    # machine-readable
-```
-
-```text
-🛡️  node9 scan-repo · node9-ai/agent-security-demo · ⚠️ agent-security risk found
-   inspected 2 config file(s), 2 finding(s)
-
-🔴 CRITICAL  Injectable agent workflow — untrusted input reaches a tool-using agent with secrets
-   .github/workflows/vulnerable-example.yml · CI-2
-     • runs with base-repo secrets (pull_request_target)
-     • checks out the untrusted PR head into the workspace root
-     • allowed_non_write_users: "*" — any user can trigger the agent
-     • no effective actor gate
-
-🔴 CRITICAL  Exfiltratable secrets reachable by an injectable agent
-   .github/workflows/vulnerable-example.yml · CI-4
-     • agent has arbitrary shell (bare Bash) → can read env and exfiltrate
-```
-
-What it checks:
-
-| Check    | Flags                                                                            |
-| -------- | -------------------------------------------------------------------------------- |
-| **CI-1** | committed agent config that pre-authorizes broad tools or runs remote hooks      |
-| **CI-2** | injectable agent workflows: an outsider can trigger the agent and hijack it      |
-| **CI-3** | unpinned / `@latest` MCP servers or inline credentials (supply chain)            |
-| **CI-4** | secrets an injected agent could exfiltrate                                       |
-| **CI-6** | poisoned or dangerous instructions in `CLAUDE.md` / `AGENTS.md` / `.cursorrules` |
-
-**Gate every PR.** The same engine runs as a GitHub Action, so a hijackable config can't get merged:
-
-```yaml
-# .github/workflows/agent-security.yml
-- uses: node9-ai/node9-proxy@v2
-  with:
-    fail-on: high # or 'never' to just comment
-    fail-on-scope: introduced # only what THIS PR added; 'all' (default) judges the whole repo
-```
-
-`fail-on-scope: introduced` is what makes the gate adoptable on a repository that already
-has findings: the PR comment leads with what the change introduced, pre-existing findings
-stay listed but do not block, and a base commit that cannot be read falls back to judging
-everything rather than passing.
-
-Marketplace: **[node9 Agent Security](https://github.com/marketplace/actions/node9-agent-security)**
-
-Running it? Add the **[`scanned by node9` badge](https://node9.ai/docs/badges)** to your README.
-
-## Live monitoring
-
-<p align="center">
-  <img src="https://github.com/user-attachments/assets/4661da97-c174-4bae-ae54-4c52a1d69213" width="720" alt="node9 monitor dashboard" />
-</p>
-
-`node9 monitor` opens an interactive terminal dashboard with two views:
-
-- **`[1]` Realtime**: live activity, approvals, security alerts, current risk score
-- **`[2]` Report**: period-windowed summary of cost, top tools, shields fired, blast radius
-
-## Report
-
-Press `[2]` in monitor for a period-windowed summary. Toggle the window with `[T]oday` · `[W]eek` · `[M]onth` · `[N]inety`. Same panels as the scan above, driven by your post-install audit log.
-
-<p align="center">
-  <img src="https://github.com/user-attachments/assets/66c02a72-e477-443d-807f-d65a21d096cd" width="720" alt="node9 monitor [2] Report" />
-</p>
-
-```bash
-node9 monitor              # press [2] for Report view
-node9 report --period 7d   # CLI form, no TUI
-```
-
-## Install
-
-```bash
-# macOS / Linux
-brew tap node9-ai/node9 && brew install node9
-
-# or via npm (any platform)
-npm install -g node9-ai
-```
-
-```bash
-node9 init       # auto-wires all detected agents + MCP servers
-node9 login      # connect this machine to your workspace (approve it in the browser)
-node9 doctor     # verify everything is wired and reporting
-```
-
-Requires Node.js 22+.
-
-`init` on its own gives you full local enforcement: rules, shields, DLP and
-approvals all work offline, on this machine.
-
-`login` is what puts the machine on your dashboard. It prints a code, opens
-the browser, and you approve the machine there; if you don't have an account
-yet, signing up mid-flow returns you to the same approval with the code
-intact. Until you run it, everything is enforced locally but nothing reaches
-Mission Control, so the dashboard stays empty.
-
-`node9 logout` disconnects a machine again. It revokes that machine's key;
-local enforcement keeps running.
-
-## Shields and apps
-
-A **shield** is a curated rule pack for a service an agent touches: Postgres, MongoDB, Redis,
-AWS, Kubernetes, Docker, GitHub, the shell, the filesystem, and the credential jail. Three of
-them, `project-jail`, `bash-safe` and `filesystem`, are on after `node9 init`. The rest you
-enable per service. Each shield mixes hard blocks with actions that come to you for review, and
-the docs say which is which, rule by rule.
-
-Any **MCP app** your agents use, Gmail, Slack, your database, is governed tool by tool from the
-Apps page in the dashboard: which tools an agent may call, which need review, which are off.
-
-```bash
-node9 shield list                 # every shield and its status
-node9 shield enable postgres      # or enable it fleet-wide from the dashboard
-```
-
-The full list, with what each shield blocks and what it sends to review:
-**[node9.ai/docs/shields](https://node9.ai/docs/shields)**.
-
-## Always on, no config needed
-
-- **Git**: catches `git push --force`, `git reset --hard`, `git clean -fd`
-- **SQL**: catches `DELETE` / `UPDATE` without `WHERE`, `DROP TABLE`, `TRUNCATE`
-- **Shell**: catches `curl | bash`, unauthorized `sudo`
-- **DLP**: flags AWS keys, GitHub tokens, Stripe keys, PEM private keys in any tool argument, file contents, or shell config (`~/.zshrc`, `~/.bashrc`)
-- **Response DLP**: a background scanner reads Claude's conversation history and alerts you if Claude _wrote_ a secret in its response text
-- **Skills pinning**: SHA-256 verification of installed Claude skills / plugins between sessions
-
-## Review prompts: approve inline, in your agent
-
-When node9 flags an action for **review** (e.g. `git push --force`, a `DROP TABLE`), the approve/deny prompt renders **inline in the agent conversation**: no frozen session, no separate terminal, no hook-timeout race. node9 still runs the full evaluator and makes the decision; only the prompt _surface_ moves to the agent.
-
-- **On by default** for **Claude Code** and **GitHub Copilot CLI**, the agents whose hook contract honors a native `ask`. Every other agent (Codex, Gemini, Antigravity, Hermes, Cursor, OpenCode, Pi) uses node9's own approver.
-- **Control it** with `reviewChannel` in `~/.node9/config.json` (or `--no-ask` on the hook):
-
-```jsonc
-{
-  "settings": {
-    "reviewChannel": "ask", // "ask" = inline agent prompt (default) | "approver" = node9's own approver
-  },
-}
-```
-
-- **Team setups:** when a cloud/team approver is configured (`approvers.cloud: true`), reviews route to that approver instead. node9 won't let an inline self-approval bypass routed/second-party approval.
-
-## Sandbox: run an agent in a jail
-
-When watching isn't enough, **`node9 sandbox`** runs the agent inside a disposable container with a **kernel-enforced egress allowlist** and **scoped mounts**, while node9's hooks govern and audit every tool call _inside_ the box. The hard version of protection: the agent can only touch the folder you mount and reach the hosts you allow; everything else is dropped at the kernel.
-
-```bash
-cd ~/my-project
-node9 sandbox new        # write node9.sandbox.yaml: what to mount + which hosts to allow
-node9 sandbox run        # build + boot the jailed agent (your project at /workspace)
-node9 sandbox tail       # watch the agent's actions live, from the host
-```
-
-- **Disposable**: the container is destroyed on exit; your project edits land on your real disk, nothing else survives.
-- **Same policy**: your existing shields / egress rules / approvals apply inside the box, streamed to the same audit log and dashboard.
-- **Closes the posture loop**: running it flips the Isolation / Egress findings green.
-
-Honest scope (Phase 1): single container, **Claude first** (Codex next); the agent still holds its _own_ credentials in the box (the kernel egress allowlist confines them to the allowed hosts). _"The agent never holds a secret"_ is the credential-broker phase on the roadmap. Requires Docker.
-
-## MCP gateway
-
-Wrap any MCP server transparently. The agent sees the same server. node9 intercepts every tool call.
-
-```json
-{
-  "mcpServers": {
-    "postgres": {
-      "command": "node9",
-      "args": ["mcp", "--upstream", "npx -y @modelcontextprotocol/server-postgres postgresql://..."]
-    }
-  }
-}
-```
-
-Or just run `node9 init`, which wraps your existing MCP servers automatically.
-
-<details>
-<summary><strong>🔐 MCP tool pinning: rug-pull defense</strong></summary>
-
-MCP servers can change their tool definitions between sessions. A compromised or malicious server could silently add, remove, or modify tools after you first trusted it, a **rug pull** attack.
-
-node9 pins tool definitions on first use:
-
-1. **First connection**: the gateway records a SHA-256 hash of every tool's name, description, and schema
-2. **Subsequent connections**: the hash is compared; if tools changed, the session is **quarantined** and every tool call is blocked until a human reviews and approves the change
-3. **Corrupt pin state**: fails closed (blocks), never silently re-trusts
-
-```bash
-node9 mcp pin list                # show all pinned servers and hashes
-node9 mcp pin update <serverKey>  # remove pin, re-pin on next connection
-node9 mcp pin reset               # clear all pins
-```
-
-</details>
-
-## Other commands
-
-Beyond the three flow commands above (`scan` / `monitor` / `report`):
-
-| Command          | What it shows                                             | When to use                            |
-| ---------------- | --------------------------------------------------------- | -------------------------------------- |
-| `node9 blast`    | What an AI agent can reach right now: files, creds, env   | First thing to run on any machine      |
-| `node9 tail`     | Live stream of every tool call (text-only, no TUI)        | Piping into other tools, CI, logs      |
-| `node9 sessions` | Session history with prompt, tool trace, and cost         | Reviewing a handoff or past work       |
-| `node9 dlp`      | Credential-leak findings in Claude response text          | Any time a DLP desktop alert fires     |
-| `node9 mask`     | Redact plaintext secrets from local session history files | After a DLP finding, cleans local disk |
-
-Plus a **live HUD** in your Claude Code statusline:
-
-```
-🛡 node9 | standard | [bash-safe] | ✅ 12 allowed  🛑 2 blocked  🚨 0 dlp | ~$0.43
-📊 claude-opus-4-7 | ctx [████████░░░] 54% | 5h [██░░░░░░░░] 12% | 7d [█░░░░░░░] 7%
-🗂 2 CLAUDE.md | 8 rules | 3 MCPs | 4 hooks
-```
-
-## Reading the data: what the numbers mean
-
-node9 surfaces the signal. Here are the patterns worth knowing:
-
-| Signal                                         | Likely meaning                                                                                    |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `Would have blocked` ≥ 5 in a week             | Agent is attempting high-impact ops; shields are worth reviewing                                  |
-| Single `review-git-push` rule >50% of findings | Your own rule is firing as intended: not a risk, just supervision                                 |
-| DLP finding in `user-prompt` tool              | You pasted a secret into your own prompt. Rotate the key                                          |
-| Agent Loop ×50+ on same file                   | Agent stuck in an edit/test/fix cycle. Check context or slow down                                 |
-| MCP tool pin mismatch                          | Server changed its tools. Review before re-trusting                                               |
-| Large MCP response warning                     | That server is inflating your context window for every subsequent turn                            |
-| `Response DLP` alert                           | Claude wrote a secret in its response text. Not blocked, rotate immediately                       |
-| DLP finding in `tool-result`                   | Claude read a file containing a secret (`.env`, credentials). Rotate the key and run `node9 mask` |
-| DLP finding in `[Shell]`                       | Plaintext secret in `~/.zshrc` or `~/.bashrc`. Every AI session can see it                        |
-
-One-off signals are normal; persistent patterns are what you act on.
-
-## Python SDK: govern any Python agent
-
-```python
-from node9 import configure, protect
-
-configure(agent_name="my-agent", policy="require_approval")
-
-@protect("bash")
-def run_command(cmd: str) -> str:
-    ...
-```
-
-**[Python SDK →](https://github.com/node9-ai/node9-python)** · **[GitHub Action →](https://github.com/marketplace/actions/node9-agent-security)**
-
-## Under the hood
-
-- **Scan** reads raw agent history from `~/.claude/projects/`, `~/.gemini/tmp/`, `~/.gemini/antigravity-*/brain/`, `~/.copilot/session-state/`, `~/.codex/sessions/`. No API calls, fully offline
-- **Runtime** intercepts tool calls via pre-execution hooks (Claude Code, Codex, Antigravity, GitHub Copilot CLI, Gemini CLI, Opencode, Pi) or via the MCP gateway (Cursor, Windsurf, VSCode, Claude Desktop). All decisions land in `~/.node9/audit.log` atomically.
-- **MCP gateway** is a stdio proxy; intercepts `tools/list` + `tools/call` JSON-RPC, forwards the rest
-- **Policy engine** uses [mvdan-sh](https://github.com/mvdan/sh) for bash AST analysis, which defeats obfuscation via backslash escaping, variable substitution, eval of remote download
-- **Sandbox** generates a Dockerfile + entrypoint that seal an `ipset`/`iptables` deny-by-default egress allowlist, then drop to a non-root agent with node9's daemon + hooks running inside; only the agent's credential file is mounted, never your whole `~/.claude`
+## What it governs
+
+Each line is one capability, with the page that documents it. The docs are the
+reference; this file is the map.
+
+|                             |                                                                                                                                                |                                                  |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| **Credential jail**         | `~/.ssh`, `~/.aws`, `.env` and private keys are blocked from every tool, not just the shell                                                    | [docs](https://node9.ai/docs/shields)            |
+| **Always-on rules**         | destructive git, SQL without a `WHERE`, `curl \| bash` and unauthorised `sudo`, with no config                                                 | [docs](https://node9.ai/docs/smart-rules)        |
+| **Secrets and PII**         | AWS keys, GitHub and Stripe tokens, PEM keys and card or SSN shapes, in any tool argument, plus a background scan of what the agent wrote back | [docs](https://node9.ai/docs/dlp)                |
+| **Per-service shields**     | curated rule packs for Postgres, MongoDB, Redis, AWS, Kubernetes, Docker, GitHub and the filesystem                                            | [docs](https://node9.ai/docs/shields)            |
+| **Inline review**           | a held action asks you inside the agent conversation, or through a team approver                                                               | [docs](https://node9.ai/docs/cloud-policy)       |
+| **Egress allowlist**        | gate where a shell command may send data, off by default                                                                                       | [docs](https://node9.ai/docs/egress)             |
+| **MCP gateway**             | wrap any MCP server, authorise each tool, and pin tool definitions so a server cannot change them behind your back                             | [docs](https://node9.ai/docs/mcp-gateway)        |
+| **Sandbox**                 | run an agent in a container with a kernel egress allowlist and scoped mounts                                                                   | [docs](https://node9.ai/docs/sandbox)            |
+| **Posture score**           | how exposed this machine is, with the command that fixes each finding                                                                          | [docs](https://node9.ai/docs/posture)            |
+| **Repo scanning**           | find workflows where an outsider could hijack an agent that holds your secrets, in CI or from the CLI                                          | [docs](https://node9.ai/docs/repo-scanning)      |
+| **Session history**         | read what every agent already did on this machine, before node9 was installed                                                                  | [docs](https://node9.ai/docs/sessions)           |
+| **Live monitor and report** | a terminal dashboard, and a windowed summary of cost, tools, blocks and blast radius                                                           | [docs](https://node9.ai/docs/report)             |
+| **Skills pinning**          | SHA-256 verification of installed Claude skills and plugins between sessions                                                                   | [docs](https://node9.ai/docs/skill-pinning)      |
+| **Canary credentials**      | planted fake keys that prove an exfiltration attempt happened                                                                                  | [docs](https://node9.ai/docs/canary-credentials) |
+| **Python SDK**              | govern any Python agent, not only the CLIs                                                                                                     | [docs](https://node9.ai/docs/python-sdk)         |
+
+Full CLI and config reference: **[node9.ai/docs](https://node9.ai/docs)**.
+How the layers fit together: **[how it works](https://node9.ai/docs/how-it-works)**.
 
 ## Learn
 
@@ -405,10 +154,6 @@ Background reading, written to stand on its own. Each page says what node9 does
 - **[node9 against the alternatives](https://node9.ai/compare)**: a matrix, including the rows where node9 scores worse
 - **[Per-agent coverage](https://node9.ai/agents)**: what is governed on each of the twelve supported agents
 
-## Full docs
-
-Config reference, smart rules, stateful rules, trusted hosts, approval modes, CLI reference, at **[node9.ai/docs](https://node9.ai/docs)**.
-
 ## Related projects
 
 - **[node9-python](https://github.com/node9-ai/node9-python)**: Python SDK

package/dist/cli.js

@@ -2251,15 +2251,44 @@ function classifySsrf(host) {
     return null;
   }
 }
+function ssrfExemptMatches(entries, normalized) {
+  if (!entries?.length || !normalized) return false;
+  const target = bitsOf(normalized);
+  for (const raw of entries) {
+    const entry = raw.trim().toLowerCase();
+    if (!entry) continue;
+    const slash = entry.indexOf("/");
+    if (slash === -1) {
+      if ((normalizeIpLiteral(entry) ?? entry) === normalized) return true;
+      continue;
+    }
+    if (!target) continue;
+    const base = bitsOf(normalizeIpLiteral(entry.slice(0, slash)) ?? "");
+    const prefixText = entry.slice(slash + 1);
+    const prefix = /^\d+$/.test(prefixText) ? Number(prefixText) : NaN;
+    if (!base || !Number.isInteger(prefix) || prefix < 0 || // A v4 range never matches a v6 address, and the reverse: the widths
+    // differ, so `0.0.0.0/0` does not release `::1`.
+    base.length !== target.length || prefix > base.length) {
+      continue;
+    }
+    if (base.slice(0, prefix) === target.slice(0, prefix)) return true;
+  }
+  return false;
+}
+function bitsOf(normalized) {
+  const o = v4Octets(normalized);
+  if (o) {
+    return o.every((n) => Number.isInteger(n) && n >= 0 && n <= 255) ? o.map((n) => n.toString(2).padStart(8, "0")).join("") : null;
+  }
+  const g = expandIpv6(normalized);
+  return g ? g.map((n) => n.toString(2).padStart(16, "0")).join("") : null;
+}
 function ssrfFloor(tokens, opts = {}) {
-  const exempt2 = new Set(
-    (opts.ssrfAllow ?? []).map((e) => normalizeIpLiteral(e) ?? e.trim().toLowerCase())
-  );
   for (const { token, binary } of tokens) {
     const m = classifySsrf(token);
     if (!m) continue;
     if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-    if (m.overridable && m.normalized && exempt2.has(m.normalized)) continue;
+    if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
     return { ...m, host: token, binary, reason: ssrfReason(m, token) };
   }
   return null;
@@ -2568,7 +2597,6 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
   try {
     const paths = DESTINATION_ARGS.get(bareToolName(toolName));
     if (!paths) return null;
-    const exempt2 = new Set((opts.ssrfAllow ?? []).map((a) => classifySsrf(a)?.normalized ?? a));
     for (const path78 of paths) {
       for (const value of valuesAt(args, path78)) {
         const host = hostOf(value);
@@ -2576,7 +2604,7 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
         const m = classifySsrf(host);
         if (!m) continue;
         if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-        if (m.overridable && m.normalized && exempt2.has(m.normalized)) continue;
+        if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
         return { ...m, argPath: path78, host, reason: ssrfReason(m, host) };
       }
     }
@@ -6799,10 +6827,12 @@ var init_api_url = __esm({
 function sanitizeSsrfAllow(entries, source) {
   const kept = [];
   for (const entry of entries) {
-    const m = classifySsrf(entry);
+    const base = entry.includes("/") ? entry.slice(0, entry.indexOf("/")).trim() : entry;
+    const m = classifySsrf(base);
     if (m && !m.overridable) {
+      const what = entry.includes("/") ? "covers only protected addresses" : "is a protected address";
       process.emitWarning(
-        `[node9] ${source} ssrfAllow entry "${entry}" is a protected address (${m.tier}) and cannot be exempted; ignoring it.`
+        `[node9] ${source} ssrfAllow entry "${entry}" ${what} (${m.tier}) and cannot be exempted; ignoring it.`
       );
       continue;
     }
@@ -20044,19 +20074,19 @@ function evaluateEgressConfig(egress) {
 function checkEgressFloor(egress) {
   const detail = [
     "the cloud instance-metadata endpoint",
-    "link-local, multicast, unspecified and CGNAT (100.64/10) addresses",
-    egress.ssrfStrict ? "the strict tier is on: loopback and the private ranges are blocked too" : `the strict tier is off: loopback and the private ranges stay reachable (${egress.policySource === "workspace" ? "turn it on in the dashboard, Enforcement \u2192 Network" : "`node9 egress strict on`"})`
+    "link-local and multicast addresses",
+    egress.ssrfStrict ? "the strict tier is on: loopback, the private ranges and CGNAT are blocked too" : `the strict tier is off: loopback, the private ranges and CGNAT (100.64/10) stay reachable (${egress.policySource === "workspace" ? "turn it on in the dashboard, Enforcement \u2192 Network" : "`node9 egress strict on`"})`
   ];
   if (egress.ssrfAllow.length) {
     detail.push(`you exempted: ${egress.ssrfAllow.join(", ")}`);
   }
-  detail.push("not covered: WebFetch and MCP fetch tools reach a URL without this gate");
+  detail.push("not covered: an interpreter one-liner (node -e, python3 -c) hides its destination");
   return [
     {
       category: "Egress",
       severity: "advisory",
-      title: "The cloud metadata endpoint is blocked in shell commands",
-      what: "node9 blocks it before any egress policy is consulted, and no setting releases it. It sees shell commands (curl, wget, ssh); a tool that fetches a URL itself does not pass this gate.",
+      title: "The cloud metadata endpoint is blocked",
+      what: "node9 blocks it before any egress policy is consulted, and no setting releases it. It sees shell commands (curl, wget, ssh) and tools that declare a URL (WebFetch, an MCP fetch tool, browser navigate); an interpreter one-liner does not reach it.",
       why: "One request to that address returns this machine's cloud credentials, to anyone who can make the agent send it.",
       who: "An agent talked into fetching that address hands over the keys and cannot, here.",
       owner: "node9",
@@ -57103,10 +57133,11 @@ function addEgressHost(list, host) {
   writeEgressRawConfig(config);
 }
 function addSsrfExemption(address) {
-  const m = classifySsrf(address);
+  const slash = address.indexOf("/");
+  const m = classifySsrf(slash === -1 ? address : address.slice(0, slash));
   if (m && !m.overridable) {
     throw new Error(
-      `${address} is a protected address (${m.tier}) and cannot be exempted by anyone. This is the one part of the floor no setting releases.`
+      `${address} ${slash === -1 ? "is a protected address" : "covers only protected addresses"} (${m.tier}) and cannot be exempted by anyone. This is the one part of the floor no setting releases.`
     );
   }
   const config = readEgressRawConfig();
@@ -57378,7 +57409,7 @@ var TOOLS = [
   },
   {
     name: "node9_egress_status",
-    description: "Show egress (outbound network) control: whether it is enabled, the mode (off / review / block), and your allow + deny host lists. Common dev/LLM hosts (github, npm, pypi, anthropic, \u2026) are always allowed by a built-in list. Also reports the SSRF floor: the addresses blocked in SHELL COMMANDS before any policy is consulted (cloud metadata, link-local, multicast, CGNAT), which tools bypass it, whether the strict tier (loopback + private ranges) is on, and the exemptions in force. Read-only.",
+    description: "Show egress (outbound network) control: whether it is enabled, the mode (off / review / block), and your allow + deny host lists. Common dev/LLM hosts (github, npm, pypi, anthropic, \u2026) are always allowed by a built-in list. Also reports the SSRF floor: the addresses blocked before any policy is consulted (cloud metadata, link-local, multicast), the carriers it covers, whether the strict tier (loopback, private ranges, CGNAT) is on, and the exemptions in force. Read-only.",
     inputSchema: { type: "object", properties: {}, required: [] }
   },
   {
@@ -57538,11 +57569,12 @@ function handleEgressStatus() {
     // The SSRF floor. Without these lines an agent reading this answer
     // concludes that internal addresses are reachable, because nothing said
     // otherwise. The LIMITS are here for the same reason and matter more on
-    // this surface than on any other: an agent treats this as ground truth,
-    // and the first version told it the floor was absolute. It is not. It sees
-    // shell commands only, and `node9 pause` suspends it.
-    "Protected addresses, IN SHELL COMMANDS ONLY: cloud metadata, link-local, multicast and CGNAT (100.64/10) are blocked before any of the above is consulted. No setting releases them, though `node9 pause` suspends all enforcement.",
-    "NOT covered by that: a tool that fetches a URL itself (WebFetch, an MCP fetch tool) does not pass this gate at all.",
+    // this surface than on any other: an agent treats this as ground truth.
+    // The first version said the floor was absolute; the correction said it
+    // was shell-only; both were wrong by the time they were read. What it
+    // actually covers is measured in egress.integration.test.ts.
+    "Protected addresses: cloud metadata, link-local and multicast are blocked before any of the above is consulted, in shell commands AND in tools that declare a URL (WebFetch, an MCP fetch tool, browser navigate). No setting releases them, though `node9 pause` suspends all enforcement.",
+    "NOT covered by that: an interpreter one-liner (node -e, python3 -c) carries its destination inside a program and does not reach this gate. CGNAT (100.64/10) is NOT in the always-blocked set \u2014 it is reachable until the strict tier is on, and an exemption can release it.",
     `Internal addresses: ${e.ssrfStrict ? "on" : "off"} \u2014 loopback and the private ranges are ${e.ssrfStrict ? "blocked too" : "reachable"}.`,
     `Floor exemptions: ${e.ssrfAllow?.length ? e.ssrfAllow.join(", ") : "(none)"}`
   ];
@@ -60301,26 +60333,76 @@ function exempt(address) {
   if (!cliGuardPolicyWrite(`egress exempt ${address}`)) return false;
   return guard(() => addSsrfExemption(address));
 }
+var INTERNAL_FIELDS = {
+  allowed: { ssrfStrict: false, allowPrivate: true },
+  listed: { ssrfStrict: false, allowPrivate: false },
+  blocked: { ssrfStrict: true, allowPrivate: false }
+};
+var INTERNAL_SAID = {
+  allowed: "reachable without listing them",
+  listed: "reachable only if they are on your allowlist",
+  blocked: "blocked"
+};
+function readInternalState(e) {
+  if (e.ssrfStrict === true) return "blocked";
+  return e.allowPrivate === false ? "listed" : "allowed";
+}
+function setInternal(value) {
+  const state = value.trim().toLowerCase();
+  if (!(state in INTERNAL_FIELDS)) {
+    console.error(
+      import_chalk34.default.red(`
+  \u2717 Expected "allowed", "listed" or "blocked", got "${value}".`) + import_chalk34.default.gray(
+        "\n    allowed  loopback, 10/172.16/192.168 and CGNAT are reachable (default)\n    listed   they are reachable only if you allowlist them\n    blocked  they are blocked at the floor\n"
+      )
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!mutate(`egress internal ${state}`, INTERNAL_FIELDS[state])) return;
+  _resetConfigCache();
+  const effective = readInternalState(getConfig().policy.egress);
+  if (effective !== state) {
+    console.log(
+      import_chalk34.default.yellow(
+        `
+  \u26A0 Saved, but not in effect: your workspace sets internal addresses to ${effective.toUpperCase()} and that governs this machine.
+    Change it in the dashboard, Enforcement \u2192 Network.
+`
+      )
+    );
+    return;
+  }
+  const line = `
+  \u2713 Internal addresses: ${state} \u2014 loopback, the private ranges and CGNAT are ${INTERNAL_SAID[state]}.
+`;
+  console.log(state === "allowed" ? import_chalk34.default.yellow(line) : import_chalk34.default.green(line));
+}
 function showFloor(e, ssrfStrictSource) {
-  console.log(import_chalk34.default.gray("\n  Protected addresses") + import_chalk34.default.gray(" \u2014 in shell commands only"));
+  console.log(
+    import_chalk34.default.gray("\n  Protected addresses") + import_chalk34.default.gray(" \u2014 in shell commands and declared URLs")
+  );
   console.log(
     import_chalk34.default.gray(
-      "    always blocked: cloud metadata, link-local, multicast, CGNAT (100.64/10)\n    no setting releases these, though `node9 pause` suspends all enforcement"
+      "    always blocked: cloud metadata, link-local, multicast\n    no setting releases these, though `node9 pause` suspends all enforcement"
     )
   );
-  const strict = e.ssrfStrict === true;
+  const state = readInternalState(e);
   const by = ssrfStrictSource === "workspace" ? "workspace (app.node9.ai)" : ssrfStrictSource === "local" ? "this machine (config.json)" : "the shipped default";
+  const STATE_LABEL = {
+    allowed: "allowed",
+    listed: "allowlist only",
+    blocked: "blocked"
+  };
   console.log(
-    `    Internal addresses:  ${strict ? import_chalk34.default.green("on") : import_chalk34.default.yellow("off")}` + import_chalk34.default.gray(
-      strict ? "  loopback and 10/172.16/192.168 are blocked too" : "  loopback and 10/172.16/192.168 are reachable"
-    )
+    `    Internal addresses:  ${state === "blocked" ? import_chalk34.default.green(STATE_LABEL[state]) : import_chalk34.default.yellow(STATE_LABEL[state])}` + import_chalk34.default.gray(`  loopback, 10/172.16/192.168 and CGNAT are ${INTERNAL_SAID[state]}`)
   );
   console.log(import_chalk34.default.gray(`    set by: ${by}`));
   const exemptions = e.ssrfAllow ?? [];
   console.log(import_chalk34.default.gray(`    Exemptions: ${exemptions.length ? exemptions.join(", ") : "none"}`));
   console.log(
     import_chalk34.default.gray(
-      "    Not covered: an agent tool that fetches a URL itself (WebFetch, an MCP\n    fetch tool) does not pass this gate."
+      "    Covered: shell commands, and tools that declare a URL (WebFetch, an MCP\n    fetch tool, browser navigate).\n    Not covered: an interpreter one-liner (node -e, python3 -c) hides its\n    destination inside a program and does not reach this gate.\n    CGNAT (100.64/10) is NOT in the always-blocked set: it is reachable\n    until Internal addresses is on, and an exemption can release it."
     )
   );
 }
@@ -60385,7 +60467,10 @@ function registerEgressCommand(program2) {
       import_chalk34.default.yellow("\n\u2713 Egress control is off \u2014 the agent can reach any host again.\n")
     );
   });
-  egress.command("strict <on|off>").description("Also block loopback and private ranges (the strict SSRF tier)").action((value) => {
+  egress.command("internal <allowed|listed|blocked>").description(
+    "How loopback, private ranges and CGNAT are treated: allowed (default), listed (must be on the allowlist), or blocked"
+  ).action((value) => setInternal(value));
+  egress.command("strict <on|off>").description("Deprecated alias for `egress internal blocked|allowed`").action((value) => {
     const v = value.trim().toLowerCase();
     if (v !== "on" && v !== "off") {
       console.error(import_chalk34.default.red(`
@@ -60394,38 +60479,40 @@ function registerEgressCommand(program2) {
       process.exitCode = 1;
       return;
     }
-    if (!mutate(`egress strict ${v}`, { ssrfStrict: v === "on" })) return;
-    _resetConfigCache();
-    const effective = getConfig().policy.egress.ssrfStrict === true;
-    if (effective !== (v === "on")) {
-      console.log(
-        import_chalk34.default.yellow(
-          `
-  \u26A0 Saved, but not in effect: your workspace sets the strict tier ${effective ? "ON" : "OFF"} and that governs this machine.
-    Change it in the dashboard, Enforcement \u2192 Network.
-`
+    const state = v === "on" ? "blocked" : getConfig().policy.egress.allowPrivate === false ? "listed" : "allowed";
+    console.log(import_chalk34.default.gray(`
+  (\`egress strict ${v}\` is now \`egress internal ${state}\`)`));
+    setInternal(state);
+  });
+  egress.command("exempt <address>").description("Let an address or a CIDR range through the floor (e.g. 100.64.0.0/10)").action((address) => {
+    const a = normalizeEgressHost(address);
+    const slash = a.indexOf("/");
+    const base = slash === -1 ? a : a.slice(0, slash);
+    const prefixText = slash === -1 ? null : a.slice(slash + 1);
+    if (!normalizeIpLiteral(base) || prefixText !== null && !/^\d{1,3}$/.test(prefixText)) {
+      console.error(
+        import_chalk34.default.red(`
+  \u2717 "${address}" is not an address or a range.`) + import_chalk34.default.gray(
+          "\n    Exemptions are matched as an address (10.0.0.5) or a CIDR\n    range (100.64.0.0/10), never a name.\n"
         )
       );
+      process.exitCode = 1;
       return;
     }
-    console.log(
-      v === "on" ? import_chalk34.default.green("\n  \u2713 Strict tier on \u2014 loopback and private ranges are blocked.\n") : import_chalk34.default.yellow("\n  \u2713 Strict tier off \u2014 loopback and private ranges are reachable.\n")
-    );
-  });
-  egress.command("exempt <address>").description("Let ONE address through the floor (exact address, not a range)").action((address) => {
-    const a = normalizeEgressHost(address);
-    if (!normalizeIpLiteral(a)) {
+    const m = classifySsrf(base);
+    if (m && !m.overridable) {
       console.error(
         import_chalk34.default.red(`
-  \u2717 "${address}" is not an address.`) + import_chalk34.default.gray(
-          "\n    Exemptions are matched as one exact address, not a name or a range.\n"
+  \u2717 ${a} cannot be exempted.`) + import_chalk34.default.gray(
+          `
+    ${slash === -1 ? "That address is" : "That range covers only"} protected addresses (${m.tier}), which no setting releases.
+`
         )
       );
       process.exitCode = 1;
       return;
     }
     if (!exempt(a)) return;
-    const m = classifySsrf(a);
     console.log(import_chalk34.default.green(`
   \u2713 ${a} is exempt from the floor.`));
     if (!m)

package/dist/cli.mjs

@@ -2262,15 +2262,44 @@ function classifySsrf(host) {
     return null;
   }
 }
+function ssrfExemptMatches(entries, normalized) {
+  if (!entries?.length || !normalized) return false;
+  const target = bitsOf(normalized);
+  for (const raw of entries) {
+    const entry = raw.trim().toLowerCase();
+    if (!entry) continue;
+    const slash = entry.indexOf("/");
+    if (slash === -1) {
+      if ((normalizeIpLiteral(entry) ?? entry) === normalized) return true;
+      continue;
+    }
+    if (!target) continue;
+    const base = bitsOf(normalizeIpLiteral(entry.slice(0, slash)) ?? "");
+    const prefixText = entry.slice(slash + 1);
+    const prefix = /^\d+$/.test(prefixText) ? Number(prefixText) : NaN;
+    if (!base || !Number.isInteger(prefix) || prefix < 0 || // A v4 range never matches a v6 address, and the reverse: the widths
+    // differ, so `0.0.0.0/0` does not release `::1`.
+    base.length !== target.length || prefix > base.length) {
+      continue;
+    }
+    if (base.slice(0, prefix) === target.slice(0, prefix)) return true;
+  }
+  return false;
+}
+function bitsOf(normalized) {
+  const o = v4Octets(normalized);
+  if (o) {
+    return o.every((n) => Number.isInteger(n) && n >= 0 && n <= 255) ? o.map((n) => n.toString(2).padStart(8, "0")).join("") : null;
+  }
+  const g = expandIpv6(normalized);
+  return g ? g.map((n) => n.toString(2).padStart(16, "0")).join("") : null;
+}
 function ssrfFloor(tokens, opts = {}) {
-  const exempt2 = new Set(
-    (opts.ssrfAllow ?? []).map((e) => normalizeIpLiteral(e) ?? e.trim().toLowerCase())
-  );
   for (const { token, binary } of tokens) {
     const m = classifySsrf(token);
     if (!m) continue;
     if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-    if (m.overridable && m.normalized && exempt2.has(m.normalized)) continue;
+    if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
     return { ...m, host: token, binary, reason: ssrfReason(m, token) };
   }
   return null;
@@ -2579,7 +2608,6 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
   try {
     const paths = DESTINATION_ARGS.get(bareToolName(toolName));
     if (!paths) return null;
-    const exempt2 = new Set((opts.ssrfAllow ?? []).map((a) => classifySsrf(a)?.normalized ?? a));
     for (const path78 of paths) {
       for (const value of valuesAt(args, path78)) {
         const host = hostOf(value);
@@ -2587,7 +2615,7 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
         const m = classifySsrf(host);
         if (!m) continue;
         if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-        if (m.overridable && m.normalized && exempt2.has(m.normalized)) continue;
+        if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
         return { ...m, argPath: path78, host, reason: ssrfReason(m, host) };
       }
     }
@@ -6806,10 +6834,12 @@ import os4 from "os";
 function sanitizeSsrfAllow(entries, source) {
   const kept = [];
   for (const entry of entries) {
-    const m = classifySsrf(entry);
+    const base = entry.includes("/") ? entry.slice(0, entry.indexOf("/")).trim() : entry;
+    const m = classifySsrf(base);
     if (m && !m.overridable) {
+      const what = entry.includes("/") ? "covers only protected addresses" : "is a protected address";
       process.emitWarning(
-        `[node9] ${source} ssrfAllow entry "${entry}" is a protected address (${m.tier}) and cannot be exempted; ignoring it.`
+        `[node9] ${source} ssrfAllow entry "${entry}" ${what} (${m.tier}) and cannot be exempted; ignoring it.`
       );
       continue;
     }
@@ -20042,19 +20072,19 @@ function evaluateEgressConfig(egress) {
 function checkEgressFloor(egress) {
   const detail = [
     "the cloud instance-metadata endpoint",
-    "link-local, multicast, unspecified and CGNAT (100.64/10) addresses",
-    egress.ssrfStrict ? "the strict tier is on: loopback and the private ranges are blocked too" : `the strict tier is off: loopback and the private ranges stay reachable (${egress.policySource === "workspace" ? "turn it on in the dashboard, Enforcement \u2192 Network" : "`node9 egress strict on`"})`
+    "link-local and multicast addresses",
+    egress.ssrfStrict ? "the strict tier is on: loopback, the private ranges and CGNAT are blocked too" : `the strict tier is off: loopback, the private ranges and CGNAT (100.64/10) stay reachable (${egress.policySource === "workspace" ? "turn it on in the dashboard, Enforcement \u2192 Network" : "`node9 egress strict on`"})`
   ];
   if (egress.ssrfAllow.length) {
     detail.push(`you exempted: ${egress.ssrfAllow.join(", ")}`);
   }
-  detail.push("not covered: WebFetch and MCP fetch tools reach a URL without this gate");
+  detail.push("not covered: an interpreter one-liner (node -e, python3 -c) hides its destination");
   return [
     {
       category: "Egress",
       severity: "advisory",
-      title: "The cloud metadata endpoint is blocked in shell commands",
-      what: "node9 blocks it before any egress policy is consulted, and no setting releases it. It sees shell commands (curl, wget, ssh); a tool that fetches a URL itself does not pass this gate.",
+      title: "The cloud metadata endpoint is blocked",
+      what: "node9 blocks it before any egress policy is consulted, and no setting releases it. It sees shell commands (curl, wget, ssh) and tools that declare a URL (WebFetch, an MCP fetch tool, browser navigate); an interpreter one-liner does not reach it.",
       why: "One request to that address returns this machine's cloud credentials, to anyone who can make the agent send it.",
       who: "An agent talked into fetching that address hands over the keys and cannot, here.",
       owner: "node9",
@@ -57093,10 +57123,11 @@ function addEgressHost(list, host) {
   writeEgressRawConfig(config);
 }
 function addSsrfExemption(address) {
-  const m = classifySsrf(address);
+  const slash = address.indexOf("/");
+  const m = classifySsrf(slash === -1 ? address : address.slice(0, slash));
   if (m && !m.overridable) {
     throw new Error(
-      `${address} is a protected address (${m.tier}) and cannot be exempted by anyone. This is the one part of the floor no setting releases.`
+      `${address} ${slash === -1 ? "is a protected address" : "covers only protected addresses"} (${m.tier}) and cannot be exempted by anyone. This is the one part of the floor no setting releases.`
     );
   }
   const config = readEgressRawConfig();
@@ -57368,7 +57399,7 @@ var TOOLS = [
   },
   {
     name: "node9_egress_status",
-    description: "Show egress (outbound network) control: whether it is enabled, the mode (off / review / block), and your allow + deny host lists. Common dev/LLM hosts (github, npm, pypi, anthropic, \u2026) are always allowed by a built-in list. Also reports the SSRF floor: the addresses blocked in SHELL COMMANDS before any policy is consulted (cloud metadata, link-local, multicast, CGNAT), which tools bypass it, whether the strict tier (loopback + private ranges) is on, and the exemptions in force. Read-only.",
+    description: "Show egress (outbound network) control: whether it is enabled, the mode (off / review / block), and your allow + deny host lists. Common dev/LLM hosts (github, npm, pypi, anthropic, \u2026) are always allowed by a built-in list. Also reports the SSRF floor: the addresses blocked before any policy is consulted (cloud metadata, link-local, multicast), the carriers it covers, whether the strict tier (loopback, private ranges, CGNAT) is on, and the exemptions in force. Read-only.",
     inputSchema: { type: "object", properties: {}, required: [] }
   },
   {
@@ -57528,11 +57559,12 @@ function handleEgressStatus() {
     // The SSRF floor. Without these lines an agent reading this answer
     // concludes that internal addresses are reachable, because nothing said
     // otherwise. The LIMITS are here for the same reason and matter more on
-    // this surface than on any other: an agent treats this as ground truth,
-    // and the first version told it the floor was absolute. It is not. It sees
-    // shell commands only, and `node9 pause` suspends it.
-    "Protected addresses, IN SHELL COMMANDS ONLY: cloud metadata, link-local, multicast and CGNAT (100.64/10) are blocked before any of the above is consulted. No setting releases them, though `node9 pause` suspends all enforcement.",
-    "NOT covered by that: a tool that fetches a URL itself (WebFetch, an MCP fetch tool) does not pass this gate at all.",
+    // this surface than on any other: an agent treats this as ground truth.
+    // The first version said the floor was absolute; the correction said it
+    // was shell-only; both were wrong by the time they were read. What it
+    // actually covers is measured in egress.integration.test.ts.
+    "Protected addresses: cloud metadata, link-local and multicast are blocked before any of the above is consulted, in shell commands AND in tools that declare a URL (WebFetch, an MCP fetch tool, browser navigate). No setting releases them, though `node9 pause` suspends all enforcement.",
+    "NOT covered by that: an interpreter one-liner (node -e, python3 -c) carries its destination inside a program and does not reach this gate. CGNAT (100.64/10) is NOT in the always-blocked set \u2014 it is reachable until the strict tier is on, and an exemption can release it.",
     `Internal addresses: ${e.ssrfStrict ? "on" : "off"} \u2014 loopback and the private ranges are ${e.ssrfStrict ? "blocked too" : "reachable"}.`,
     `Floor exemptions: ${e.ssrfAllow?.length ? e.ssrfAllow.join(", ") : "(none)"}`
   ];
@@ -60291,26 +60323,76 @@ function exempt(address) {
   if (!cliGuardPolicyWrite(`egress exempt ${address}`)) return false;
   return guard(() => addSsrfExemption(address));
 }
+var INTERNAL_FIELDS = {
+  allowed: { ssrfStrict: false, allowPrivate: true },
+  listed: { ssrfStrict: false, allowPrivate: false },
+  blocked: { ssrfStrict: true, allowPrivate: false }
+};
+var INTERNAL_SAID = {
+  allowed: "reachable without listing them",
+  listed: "reachable only if they are on your allowlist",
+  blocked: "blocked"
+};
+function readInternalState(e) {
+  if (e.ssrfStrict === true) return "blocked";
+  return e.allowPrivate === false ? "listed" : "allowed";
+}
+function setInternal(value) {
+  const state = value.trim().toLowerCase();
+  if (!(state in INTERNAL_FIELDS)) {
+    console.error(
+      chalk34.red(`
+  \u2717 Expected "allowed", "listed" or "blocked", got "${value}".`) + chalk34.gray(
+        "\n    allowed  loopback, 10/172.16/192.168 and CGNAT are reachable (default)\n    listed   they are reachable only if you allowlist them\n    blocked  they are blocked at the floor\n"
+      )
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!mutate(`egress internal ${state}`, INTERNAL_FIELDS[state])) return;
+  _resetConfigCache();
+  const effective = readInternalState(getConfig().policy.egress);
+  if (effective !== state) {
+    console.log(
+      chalk34.yellow(
+        `
+  \u26A0 Saved, but not in effect: your workspace sets internal addresses to ${effective.toUpperCase()} and that governs this machine.
+    Change it in the dashboard, Enforcement \u2192 Network.
+`
+      )
+    );
+    return;
+  }
+  const line = `
+  \u2713 Internal addresses: ${state} \u2014 loopback, the private ranges and CGNAT are ${INTERNAL_SAID[state]}.
+`;
+  console.log(state === "allowed" ? chalk34.yellow(line) : chalk34.green(line));
+}
 function showFloor(e, ssrfStrictSource) {
-  console.log(chalk34.gray("\n  Protected addresses") + chalk34.gray(" \u2014 in shell commands only"));
+  console.log(
+    chalk34.gray("\n  Protected addresses") + chalk34.gray(" \u2014 in shell commands and declared URLs")
+  );
   console.log(
     chalk34.gray(
-      "    always blocked: cloud metadata, link-local, multicast, CGNAT (100.64/10)\n    no setting releases these, though `node9 pause` suspends all enforcement"
+      "    always blocked: cloud metadata, link-local, multicast\n    no setting releases these, though `node9 pause` suspends all enforcement"
     )
   );
-  const strict = e.ssrfStrict === true;
+  const state = readInternalState(e);
   const by = ssrfStrictSource === "workspace" ? "workspace (app.node9.ai)" : ssrfStrictSource === "local" ? "this machine (config.json)" : "the shipped default";
+  const STATE_LABEL = {
+    allowed: "allowed",
+    listed: "allowlist only",
+    blocked: "blocked"
+  };
   console.log(
-    `    Internal addresses:  ${strict ? chalk34.green("on") : chalk34.yellow("off")}` + chalk34.gray(
-      strict ? "  loopback and 10/172.16/192.168 are blocked too" : "  loopback and 10/172.16/192.168 are reachable"
-    )
+    `    Internal addresses:  ${state === "blocked" ? chalk34.green(STATE_LABEL[state]) : chalk34.yellow(STATE_LABEL[state])}` + chalk34.gray(`  loopback, 10/172.16/192.168 and CGNAT are ${INTERNAL_SAID[state]}`)
   );
   console.log(chalk34.gray(`    set by: ${by}`));
   const exemptions = e.ssrfAllow ?? [];
   console.log(chalk34.gray(`    Exemptions: ${exemptions.length ? exemptions.join(", ") : "none"}`));
   console.log(
     chalk34.gray(
-      "    Not covered: an agent tool that fetches a URL itself (WebFetch, an MCP\n    fetch tool) does not pass this gate."
+      "    Covered: shell commands, and tools that declare a URL (WebFetch, an MCP\n    fetch tool, browser navigate).\n    Not covered: an interpreter one-liner (node -e, python3 -c) hides its\n    destination inside a program and does not reach this gate.\n    CGNAT (100.64/10) is NOT in the always-blocked set: it is reachable\n    until Internal addresses is on, and an exemption can release it."
     )
   );
 }
@@ -60375,7 +60457,10 @@ function registerEgressCommand(program2) {
       chalk34.yellow("\n\u2713 Egress control is off \u2014 the agent can reach any host again.\n")
     );
   });
-  egress.command("strict <on|off>").description("Also block loopback and private ranges (the strict SSRF tier)").action((value) => {
+  egress.command("internal <allowed|listed|blocked>").description(
+    "How loopback, private ranges and CGNAT are treated: allowed (default), listed (must be on the allowlist), or blocked"
+  ).action((value) => setInternal(value));
+  egress.command("strict <on|off>").description("Deprecated alias for `egress internal blocked|allowed`").action((value) => {
     const v = value.trim().toLowerCase();
     if (v !== "on" && v !== "off") {
       console.error(chalk34.red(`
@@ -60384,38 +60469,40 @@ function registerEgressCommand(program2) {
       process.exitCode = 1;
       return;
     }
-    if (!mutate(`egress strict ${v}`, { ssrfStrict: v === "on" })) return;
-    _resetConfigCache();
-    const effective = getConfig().policy.egress.ssrfStrict === true;
-    if (effective !== (v === "on")) {
-      console.log(
-        chalk34.yellow(
-          `
-  \u26A0 Saved, but not in effect: your workspace sets the strict tier ${effective ? "ON" : "OFF"} and that governs this machine.
-    Change it in the dashboard, Enforcement \u2192 Network.
-`
+    const state = v === "on" ? "blocked" : getConfig().policy.egress.allowPrivate === false ? "listed" : "allowed";
+    console.log(chalk34.gray(`
+  (\`egress strict ${v}\` is now \`egress internal ${state}\`)`));
+    setInternal(state);
+  });
+  egress.command("exempt <address>").description("Let an address or a CIDR range through the floor (e.g. 100.64.0.0/10)").action((address) => {
+    const a = normalizeEgressHost(address);
+    const slash = a.indexOf("/");
+    const base = slash === -1 ? a : a.slice(0, slash);
+    const prefixText = slash === -1 ? null : a.slice(slash + 1);
+    if (!normalizeIpLiteral(base) || prefixText !== null && !/^\d{1,3}$/.test(prefixText)) {
+      console.error(
+        chalk34.red(`
+  \u2717 "${address}" is not an address or a range.`) + chalk34.gray(
+          "\n    Exemptions are matched as an address (10.0.0.5) or a CIDR\n    range (100.64.0.0/10), never a name.\n"
         )
       );
+      process.exitCode = 1;
       return;
     }
-    console.log(
-      v === "on" ? chalk34.green("\n  \u2713 Strict tier on \u2014 loopback and private ranges are blocked.\n") : chalk34.yellow("\n  \u2713 Strict tier off \u2014 loopback and private ranges are reachable.\n")
-    );
-  });
-  egress.command("exempt <address>").description("Let ONE address through the floor (exact address, not a range)").action((address) => {
-    const a = normalizeEgressHost(address);
-    if (!normalizeIpLiteral(a)) {
+    const m = classifySsrf(base);
+    if (m && !m.overridable) {
       console.error(
         chalk34.red(`
-  \u2717 "${address}" is not an address.`) + chalk34.gray(
-          "\n    Exemptions are matched as one exact address, not a name or a range.\n"
+  \u2717 ${a} cannot be exempted.`) + chalk34.gray(
+          `
+    ${slash === -1 ? "That address is" : "That range covers only"} protected addresses (${m.tier}), which no setting releases.
+`
         )
       );
       process.exitCode = 1;
       return;
     }
     if (!exempt(a)) return;
-    const m = classifySsrf(a);
     console.log(chalk34.green(`
   \u2713 ${a} is exempt from the floor.`));
     if (!m)

package/dist/dashboard.mjs

@@ -4717,10 +4717,12 @@ import os7 from "os";
 function sanitizeSsrfAllow(entries, source) {
   const kept = [];
   for (const entry of entries) {
-    const m = classifySsrf(entry);
+    const base = entry.includes("/") ? entry.slice(0, entry.indexOf("/")).trim() : entry;
+    const m = classifySsrf(base);
     if (m && !m.overridable) {
+      const what = entry.includes("/") ? "covers only protected addresses" : "is a protected address";
       process.emitWarning(
-        `[node9] ${source} ssrfAllow entry "${entry}" is a protected address (${m.tier}) and cannot be exempted; ignoring it.`
+        `[node9] ${source} ssrfAllow entry "${entry}" ${what} (${m.tier}) and cannot be exempted; ignoring it.`
       );
       continue;
     }

package/dist/index.js

@@ -3630,6 +3630,38 @@ function classifySsrf(host) {
     return null;
   }
 }
+function ssrfExemptMatches(entries, normalized) {
+  if (!entries?.length || !normalized) return false;
+  const target = bitsOf(normalized);
+  for (const raw of entries) {
+    const entry = raw.trim().toLowerCase();
+    if (!entry) continue;
+    const slash = entry.indexOf("/");
+    if (slash === -1) {
+      if ((normalizeIpLiteral(entry) ?? entry) === normalized) return true;
+      continue;
+    }
+    if (!target) continue;
+    const base = bitsOf(normalizeIpLiteral(entry.slice(0, slash)) ?? "");
+    const prefixText = entry.slice(slash + 1);
+    const prefix = /^\d+$/.test(prefixText) ? Number(prefixText) : NaN;
+    if (!base || !Number.isInteger(prefix) || prefix < 0 || // A v4 range never matches a v6 address, and the reverse: the widths
+    // differ, so `0.0.0.0/0` does not release `::1`.
+    base.length !== target.length || prefix > base.length) {
+      continue;
+    }
+    if (base.slice(0, prefix) === target.slice(0, prefix)) return true;
+  }
+  return false;
+}
+function bitsOf(normalized) {
+  const o = v4Octets(normalized);
+  if (o) {
+    return o.every((n) => Number.isInteger(n) && n >= 0 && n <= 255) ? o.map((n) => n.toString(2).padStart(8, "0")).join("") : null;
+  }
+  const g = expandIpv6(normalized);
+  return g ? g.map((n) => n.toString(2).padStart(16, "0")).join("") : null;
+}
 var TIER_REASON = {
   metadata: "a cloud instance-metadata endpoint, the classic credential-theft target",
   "link-local": "a link-local address",
@@ -3639,14 +3671,11 @@ var TIER_REASON = {
   private: "a loopback or private address"
 };
 function ssrfFloor(tokens, opts = {}) {
-  const exempt = new Set(
-    (opts.ssrfAllow ?? []).map((e) => normalizeIpLiteral(e) ?? e.trim().toLowerCase())
-  );
   for (const { token, binary } of tokens) {
     const m = classifySsrf(token);
     if (!m) continue;
     if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-    if (m.overridable && m.normalized && exempt.has(m.normalized)) continue;
+    if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
     return { ...m, host: token, binary, reason: ssrfReason(m, token) };
   }
   return null;
@@ -4109,7 +4138,6 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
   try {
     const paths = DESTINATION_ARGS.get(bareToolName(toolName));
     if (!paths) return null;
-    const exempt = new Set((opts.ssrfAllow ?? []).map((a) => classifySsrf(a)?.normalized ?? a));
     for (const path16 of paths) {
       for (const value of valuesAt(args, path16)) {
         const host = hostOf(value);
@@ -4117,7 +4145,7 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
         const m = classifySsrf(host);
         if (!m) continue;
         if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-        if (m.overridable && m.normalized && exempt.has(m.normalized)) continue;
+        if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
         return { ...m, argPath: path16, host, reason: ssrfReason(m, host) };
       }
     }
@@ -5950,10 +5978,12 @@ function safeApiUrl(raw, onReject) {
 function sanitizeSsrfAllow(entries, source) {
   const kept = [];
   for (const entry of entries) {
-    const m = classifySsrf(entry);
+    const base = entry.includes("/") ? entry.slice(0, entry.indexOf("/")).trim() : entry;
+    const m = classifySsrf(base);
     if (m && !m.overridable) {
+      const what = entry.includes("/") ? "covers only protected addresses" : "is a protected address";
       process.emitWarning(
-        `[node9] ${source} ssrfAllow entry "${entry}" is a protected address (${m.tier}) and cannot be exempted; ignoring it.`
+        `[node9] ${source} ssrfAllow entry "${entry}" ${what} (${m.tier}) and cannot be exempted; ignoring it.`
       );
       continue;
     }

package/dist/index.mjs

@@ -3600,6 +3600,38 @@ function classifySsrf(host) {
     return null;
   }
 }
+function ssrfExemptMatches(entries, normalized) {
+  if (!entries?.length || !normalized) return false;
+  const target = bitsOf(normalized);
+  for (const raw of entries) {
+    const entry = raw.trim().toLowerCase();
+    if (!entry) continue;
+    const slash = entry.indexOf("/");
+    if (slash === -1) {
+      if ((normalizeIpLiteral(entry) ?? entry) === normalized) return true;
+      continue;
+    }
+    if (!target) continue;
+    const base = bitsOf(normalizeIpLiteral(entry.slice(0, slash)) ?? "");
+    const prefixText = entry.slice(slash + 1);
+    const prefix = /^\d+$/.test(prefixText) ? Number(prefixText) : NaN;
+    if (!base || !Number.isInteger(prefix) || prefix < 0 || // A v4 range never matches a v6 address, and the reverse: the widths
+    // differ, so `0.0.0.0/0` does not release `::1`.
+    base.length !== target.length || prefix > base.length) {
+      continue;
+    }
+    if (base.slice(0, prefix) === target.slice(0, prefix)) return true;
+  }
+  return false;
+}
+function bitsOf(normalized) {
+  const o = v4Octets(normalized);
+  if (o) {
+    return o.every((n) => Number.isInteger(n) && n >= 0 && n <= 255) ? o.map((n) => n.toString(2).padStart(8, "0")).join("") : null;
+  }
+  const g = expandIpv6(normalized);
+  return g ? g.map((n) => n.toString(2).padStart(16, "0")).join("") : null;
+}
 var TIER_REASON = {
   metadata: "a cloud instance-metadata endpoint, the classic credential-theft target",
   "link-local": "a link-local address",
@@ -3609,14 +3641,11 @@ var TIER_REASON = {
   private: "a loopback or private address"
 };
 function ssrfFloor(tokens, opts = {}) {
-  const exempt = new Set(
-    (opts.ssrfAllow ?? []).map((e) => normalizeIpLiteral(e) ?? e.trim().toLowerCase())
-  );
   for (const { token, binary } of tokens) {
     const m = classifySsrf(token);
     if (!m) continue;
     if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-    if (m.overridable && m.normalized && exempt.has(m.normalized)) continue;
+    if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
     return { ...m, host: token, binary, reason: ssrfReason(m, token) };
   }
   return null;
@@ -4079,7 +4108,6 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
   try {
     const paths = DESTINATION_ARGS.get(bareToolName(toolName));
     if (!paths) return null;
-    const exempt = new Set((opts.ssrfAllow ?? []).map((a) => classifySsrf(a)?.normalized ?? a));
     for (const path16 of paths) {
       for (const value of valuesAt(args, path16)) {
         const host = hostOf(value);
@@ -4087,7 +4115,7 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
         const m = classifySsrf(host);
         if (!m) continue;
         if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-        if (m.overridable && m.normalized && exempt.has(m.normalized)) continue;
+        if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
         return { ...m, argPath: path16, host, reason: ssrfReason(m, host) };
       }
     }
@@ -5920,10 +5948,12 @@ function safeApiUrl(raw, onReject) {
 function sanitizeSsrfAllow(entries, source) {
   const kept = [];
   for (const entry of entries) {
-    const m = classifySsrf(entry);
+    const base = entry.includes("/") ? entry.slice(0, entry.indexOf("/")).trim() : entry;
+    const m = classifySsrf(base);
     if (m && !m.overridable) {
+      const what = entry.includes("/") ? "covers only protected addresses" : "is a protected address";
       process.emitWarning(
-        `[node9] ${source} ssrfAllow entry "${entry}" is a protected address (${m.tier}) and cannot be exempted; ignoring it.`
+        `[node9] ${source} ssrfAllow entry "${entry}" ${what} (${m.tier}) and cannot be exempted; ignoring it.`
       );
       continue;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node9/proxy",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "IAM for your AI agents. Set what Claude Code, Codex, Gemini, Cursor and any MCP server are allowed to do, review risky actions before they run, and keep every action on the record.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",