pi-netguard 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# pi-netguard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small pi extension that asks before **recognized network-capable shell commands** run. Designed to add friction and visibility to unexpected downloads, uploads and other outbound activity, including the visible `curl` upload described in [Cohere's report](https://cohere.com/blog/concerning-behaviour-popular-open-weight-ai-model).
+
+**This is a command approval guard, not a firewall or network monitor.** It inspects text before execution; it cannot observe actual connections or guarantee that traffic stays on your machine. No proxy, daemon, packet capture, elevated permissions or runtime dependencies.
+
+## Install
+
+```sh
+pi install npm:pi-netguard
+```
+
+Try it for one session without adding it to your settings:
+
+```sh
+pi -e npm:pi-netguard
+```
+
+From a checkout, use `pi -e ./src/index.ts` or `pi install /absolute/path/to/netguard`. On Windows, use a quoted absolute path, for example `pi install "C:\P2027\pi-plugins\netguard"`. Restart pi or run `/reload` after installation. Installing only to a project makes protection dependent on loading that project's resources; a personal installation is preferable for a guard.
+
+Developed and tested with `@earendil-works/pi-coding-agent` 1.4.0 (Node 22.18+). This is the current pi package name; compatibility with older `@mariozechner` releases is unverified. See pi's [extension](https://pi.dev/docs/latest/extensions) and [package](https://pi.dev/docs/latest/packages) documentation.
+
+## Approval choices
+
+Before a detected `bash` or `powershell` tool call executes, the dialog shows the reasons and the complete command, then offers:
+
+- **Block** (first/default option). Escape or dismissal also blocks.
+- **Allow once**. Only this invocation is approved.
+- **Allow this exact command for this session**. The same command text, shell tool and working directory can run again without another prompt. Changing any of those requires fresh approval. This does not grant trust to a host, domain or executable in general.
+
+Approval permits the **whole shell command**, including chained commands and subprocesses. Identical text can behave differently if files, environment variables, DNS, Git remotes or other external state change. When the agent writes or edits a script, session approvals for commands that run it are revoked. Other changes are not tracked, so prefer **Allow once** for commands that depend on mutable inputs.
+
+Session approvals stay in memory. New, resumed or forked sessions, reloads and shutdown clear them. Use `/netguard reset` to revoke them immediately; `/netguard` reports the approval count. Resetting does not stop commands that are already running.
+
+In print/JSON mode, or without an approval UI, detected calls are blocked. RPC clients must support pi's selection dialog. A dialog error, cancellation or aborted operation blocks the call. Calls that are not detected continue normally. Netguard emits local approval/block notifications and a status indicator; it does not send telemetry or create its own audit log.
+
+## What triggers a prompt
+
+The detector conservatively scans the entire command, including visible pipelines, nested shell strings and inline code. Common Bash/PowerShell line continuations are joined for detection. Terminal controls and invisible formatting characters are escaped in the dialog.
+
+| Visible pattern | Examples |
+| --- | --- |
+| URLs | HTTP(S), FTP, SSH, Git, WebSocket, S3, GCS, SMB and rsync URLs, including cloud metadata URLs |
+| Transfer and network utilities | `curl`, `wget`, `ssh`, `scp`, `rsync`, `nc`, `socat`, `ping`, `nmap` |
+| DNS utilities | `dig`, `nslookup`, `host`, `Resolve-DnsName` |
+| PowerShell and Windows | `Invoke-WebRequest`, `irm`, `Start-BitsTransfer`, remoting (`Enter-PSSession`, `-ComputerName`), `\\server\share` paths, `certutil -urlcache`, `bitsadmin` |
+| Cloud, cluster and code-hosting CLIs | `aws`, `az`, `gcloud`, `gsutil`, `azcopy`, `rclone`, `kubectl`, `helm`, `gh`, `glab`, `hf` |
+| Git network operations | `clone`, `fetch`, `pull`, `push`, `ls-remote`, `submodule`, `remote update`, `send-email`, `lfs` |
+| Package operations | Install, download, publish and registry subcommands of language and OS package managers (`npm`, `pip`, `uv`, `cargo`, `brew`, `apt`, `winget`, …); `npx`, `uvx`, `pipx`, `bunx` |
+| Containers and model registries | `docker`/`podman` `pull`, `push`, `login`, `run`, `build`, `compose up`; `ollama pull` |
+| Networking code | Common Python libraries, JS `fetch`, HTTP clients and socket APIs, .NET network classes, `/dev/tcp`, `/dev/udp` |
+| Scripts written this session | Running a script (`python upload.py`, `./send.sh`) that the agent created or edited with networking code in this session |
+
+These are text heuristics rather than a shell parser. Distinctive tool names match anywhere, so `echo curl` triggers. Names that are also common words (`host`, `http`, `az`, `gh`, `ping`) only match where a command starts, and Git and package verbs only match as the subcommand, so commit messages, paths and search terms such as `git commit -m "fix push"` or `rg host src` do not prompt. Downloads and GET requests require approval too, since URLs, DNS lookups and headers can carry data. No destination is implicitly trusted, including localhost.
+
+Script tracking only covers scripts written through pi's `write` and `edit` tools in the current session, and only when the command names the script. Mentioning a script without running it (`git add upload.py`) does not prompt. Bare URLs in a script are ignored because they are common in configuration files.
+
+## Scope and limitations
+
+- **Hidden network activity is missed.** Scripts that existed before the session or were created by other means, scripts imported by another script, `./binary`, shell aliases/functions, `make`, `npm test`, Git hooks and dependency lifecycle scripts can connect without visible matching text. An approved installer may execute arbitrary scripts and access other destinations.
+- **Obfuscation bypasses detection.** Encoded code, constructed executable names, runtime imports, renamed utilities and unrecognized clients can evade the rules. Do not use this against a deliberately evasive agent as your only control.
+- **Other tools and extensions are outside scope.** Custom/MCP tools, extension-owned network calls, pi's model-provider requests and user-entered `!` shell commands are not guarded. `write` and `edit` are not blocked; they are only inspected so that running the resulting script prompts. Tool code calling the host's guarded `bash`/`powershell` path is covered; direct process execution is not.
+- **The extension shares pi's permissions.** An agent able to edit this extension or change its loading configuration can tamper with it. Install from a location the agent cannot write when practical. Other extensions can modify tool arguments after this guard approves them; only load trusted extensions.
+- **No connection or payload inspection.** The guard does not resolve destinations, intercept redirects, inspect encrypted traffic, scan files for secrets, or stop background processes. A session approval authorizes matching command text, not a fixed network request.
+
+For enforced egress control, pair this with an OS/container network policy or a mandatory proxy. That is a separate layer with platform-specific setup. This first version focuses on one task: put a user decision in front of recognizable network-capable commands.
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+npm run check
+```
+
+Tests exercise detection, approval scope, cancellation, session reset, concurrent calls and failure behavior without making network requests or running the example commands. The package includes TypeScript source that pi loads directly; there is no build step.
+
+The development host currently pins an older `undici`; the root override selects a patched release for local development. It does not update a user's separately installed pi host.

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "pi-netguard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Ask before recognized network-capable shell commands in pi.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thomas9120/netguard.git"
+  },
+  "homepage": "https://github.com/thomas9120/netguard#readme",
+  "bugs": {
+    "url": "https://github.com/thomas9120/netguard/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "network",
+    "security"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "overrides": {
+    "@earendil-works/pi-coding-agent": {
+      "undici": "8.12.3"
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/detect.ts

@@ -0,0 +1,96 @@
+// These are deliberately conservative text heuristics, not a shell parser.
+// Scan the entire command to include pipelines, nested shells and inline scripts.
+
+// Where a command name can start: line and pipeline starts, subshells, a shell's
+// script argument (`bash -c '...'`) and common wrappers (`sudo`, `xargs`, `find -exec`).
+const START = String.raw`(?:^|[\r\n;&|({\x60]|\$\(|\b(?:ba|z|da|k)?sh\s+(?:[-/]\S+\s+)*|\b(?:cmd|pwsh|powershell)(?:\.exe)?\s+(?:[-/]\S+\s+)*|(?<![\w-])(?:sudo|env|exec|xargs|time|timeout|nohup|nice|watch|command|then|do|else|-exec)(?:\s+(?:-\S*|\d\S*|[a-z_]\w*=\S*))*\s)\s*['"]?(?:[^\s'";&|()]*[\\/])?`;
+// Options between a tool and its subcommand, such as `npm --prefix dir install`.
+// Each token must have exactly one parse, or long commands backtrack exponentially.
+const OPTIONS = String.raw`(?:\s+--?\w[\w-]*(?:[=\s][^\s;&|-]\S*)?)*`;
+
+// Distinctive names match anywhere they appear as a word, including paths to the executable.
+const word = (names: string) => new RegExp(String.raw`(?<![\w.-])(?:${names})(?![\w-])`, "i");
+// Names that are also common words (`host`, `http`, `az`) match only in command position.
+const command = (names: string) => new RegExp(String.raw`${START}(?:${names})(?:\.exe)?(?=$|[\s;&|)'"])`, "i");
+const subcommand = (tools: string, verbs: string) =>
+  new RegExp(String.raw`(?<![\w.-])(?:${tools})(?:\.(?:exe|cmd))?['"]?${OPTIONS}\s+(?:${verbs})(?![\w-])`, "i");
+
+const PACKAGE_VERBS = "install|add|update|upgrade|sync|lock|download|fetch|publish|push|restore|audit|outdated|search|info|login|require|create-project|create|cache|self\\s+update|python\\s+install|tool\\s+(?:install|run|update|upgrade|restore)";
+const CODE_LIBRARIES = "requests|urllib\\d?|httpx|aiohttp|socket|smtplib|ftplib|telnetlib|paramiko|http\\.client|axios|undici|reqwest";
+const JS_NETWORK_MODULES = "https?|http2|net|tls|dgram|ws|node-fetch";
+
+const URL_REASON = "URL in command";
+const rules: ReadonlyArray<readonly [string, ...RegExp[]]> = [
+  [URL_REASON,/\b(?:https?|ftps?|sftp|ssh|git|wss?|gopher|s3|gs|smb|rsync|scp):\/\//i],
+  ["network or file-transfer utility",
+    word("curl|wget2?|xh|aria2c|ssh|ssh-copy-id|scp|sftp|rsync|ncat|netcat|socat|telnet|lftp|tftp|ping6|traceroute|tracepath|nmap|mosh"),
+    command("http|https|nc|ftp|ping")],
+  ["DNS lookup utility", word("nslookup|Resolve-DnsName"), command("dig|host")],
+  ["PowerShell or Windows network command",
+    word("Invoke-WebRequest|Invoke-RestMethod|iwr|irm|Start-BitsTransfer|Test-NetConnection|Test-Connection|Send-MailMessage|Enter-PSSession|New-PSSession|New-CimSession|bitsadmin"),
+    /(?<![\w-])-(?:ComputerName|ToSession|FromSession)(?![\w-])/i,
+    /\bcertutil\b[^\r\n]*\s[-/](?:urlcache|verifyctl)\b/i],
+  ["Windows network share path", /(?<![^\s'"=(,;|&<>])\\\\(?!wsl(?:\.localhost|\$)\\)\w[\w.-]*\\[\w$]/i],
+  ["cloud, cluster or code-hosting CLI",
+    word("gcloud|gsutil|rclone|ossutil(?:64)?|aliyun|coscli|azcopy|s3cmd|kubectl|huggingface-cli|glab"),
+    command("aws|az|gh|hf|helm")],
+  ["Git network operation",
+    /(?<![\w.-])git(?:\.exe)?['"]?(?:\s+(?:-[Cc]\s+[^\s-]\S*|--?\w[\w-]*(?:=\S+)?))*\s+(?:clone|fetch|pull|push|ls-remote|submodule|remote\s+update|send-email|request-pull|svn|p4|lfs|archive\b[^\r\n;&|]*--remote)(?![\w-])/i],
+  ["package download or publishing",
+    subcommand("npm|pnpm|yarn|bun", `${PACKAGE_VERBS}|i|ci|up|view|dlx|x|exec|init\\s+(?!-)\\S+`),
+    subcommand("pip3?|uv|poetry|pdm|pipenv|cargo|gem|bundle|composer|dotnet|nuget|deno|conda|mamba|micromamba|brew|apt|apt-get|dnf|yum|zypper|apk|winget|choco|scoop|snap|flatpak", PACKAGE_VERBS),
+    word("npx|pnpx|bunx|uvx|pipx"),
+    /(?<![\w.-])yarn(?=\s*(?:$|[;&|)]))/i,
+    /(?<![\w.-])pacman\s+-S/i,
+    /\bgo\s+(?:get|install|mod\s+(?:download|tidy))\b/i],
+  ["container or model registry operation",
+    subcommand("docker-compose|podman-compose|docker|podman|nerdctl|ollama",
+      `pull|push|login|run|build|create|search|up|compose${OPTIONS}\\s+(?:up|pull|push|build|run|create)|buildx\\s+build|image\\s+(?:pull|push)|manifest\\s+push`)],
+  ["shell network device", /\/dev\/(?:tcp|udp)\//i],
+  ["networking code or API",
+    new RegExp(String.raw`\b(?:import|from)\s+['"]?(?:node:)?(?:${CODE_LIBRARIES}|${JS_NETWORK_MODULES})\b`, "i"),
+    new RegExp(String.raw`\b(?:require|import)\s*\(\s*['"](?:node:)?(?:${CODE_LIBRARIES}|${JS_NETWORK_MODULES})['"]`, "i"),
+    new RegExp(String.raw`\b(?:${CODE_LIBRARIES})(?:\s*(?:\.|::)\s*\w+)+\s*\(`, "i"),
+    /\b(?:fetch|axios|XMLHttpRequest|WebSocket)\s*\(|\b(?:https?|http2|net|tls|dgram)\s*\.\s*(?:request|get|connect|createConnection|createSocket)\s*\(/i,
+    /\bNet\.(?:\w+\.)*(?:TcpClient|UdpClient|WebClient|HttpClient|WebRequest|HttpWebRequest|Dns|Sockets)\b|\bnew\s+(?:TcpClient|UdpClient|WebClient|HttpClient)\s*\(/i,
+    /\bhttp\.server\b|\bnet\/http\b|\bopenssl\s+s_client\b/i],
+];
+
+// Join common Bash and PowerShell line continuations before matching.
+const joinContinuations = (command: string) => command.replace(/(?:\\|`)\r?\n/g, "");
+
+export function detectNetwork(command: string): string[] {
+  const text = joinContinuations(command);
+  return rules.filter(([, ...patterns]) => patterns.some((pattern) => pattern.test(text))).map(([reason]) => reason);
+}
+
+// Scripts the agent writes are only visible to later shell commands by name, so remember
+// which ones contain network-capable code. Bare URLs are common in configs and docs; skip them.
+const SCRIPT_FILE = /^(?:[^.]+|.+\.(?:py|pyw|js|mjs|cjs|ts|mts|cts|sh|bash|zsh|ps1|psm1|rb|pl|php|lua|r|bat|cmd))$/i;
+
+export function scriptName(path: string): string | undefined {
+  const name = path.split(/[\\/]/).pop();
+  return name && SCRIPT_FILE.test(name) ? name : undefined;
+}
+
+export function detectNetworkInScript(content: string): string[] {
+  return detectNetwork(content).filter((reason) => reason !== URL_REASON);
+}
+
+// Interpreters that take a script path among their arguments. The scan is bounded to keep
+// long commands linear.
+const RUNNERS = String.raw`(?<![\w.-])(?:python[\d.]*|py|node|deno|bun|tsx|ts-node|bash|sh|zsh|pwsh|powershell|ruby|perl|php|lua|Rscript|source|\.|uv\s+run|go\s+run)(?:\.exe)?\s[^\r\n;&|]{0,512}?`;
+const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// Whether a command runs the named script through an interpreter or as a path (`./upload.sh`),
+// as opposed to merely mentioning it (`git add upload.sh`).
+export function runsScript(command: string, name: string): boolean {
+  return new RegExp(String.raw`(?:${RUNNERS}|${START})(?<![\w.-])${escapeRegExp(name)}(?![\w.-])`, "i").test(joinContinuations(command));
+}
+
+// Make terminal controls and bidi overrides visible instead of rendering them.
+export function displayCommand(command: string): string {
+  return command.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, (character) =>
+    `\\u{${character.codePointAt(0)!.toString(16)}}`,
+  );
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+import type { ExtensionAPI, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+import { detectNetwork, detectNetworkInScript, displayCommand, runsScript, scriptName } from "./detect.ts";
+
+const BLOCK = "Block";
+const ONCE = "Allow once";
+const SESSION = "Allow this exact command for this session";
+
+export default function netguard(pi: ExtensionAPI): void {
+  // Session approvals, keyed by tool, working directory and command text.
+  const approved = new Map<string, string>();
+  // Names of scripts written this session that contain network-capable code.
+  const networkScripts = new Set<string>();
+  let generation = 0;
+  let queue = Promise.resolve();
+
+  function reset(): void {
+    approved.clear();
+    generation++;
+  }
+
+  function trackScript(path: unknown, content: string, replacesFile: boolean): void {
+    const name = typeof path === "string" ? scriptName(path) : undefined;
+    if (!name) return;
+    // A changed script can do something new, so approvals that run it no longer apply.
+    for (const [key, command] of approved) if (runsScript(command, name)) approved.delete(key);
+    if (detectNetworkInScript(content).length > 0) networkScripts.add(name);
+    else if (replacesFile) networkScripts.delete(name);
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    reset();
+    networkScripts.clear();
+    if (ctx.hasUI) ctx.ui.setStatus("netguard", "netguard: approval required");
+  });
+  pi.on("session_shutdown", () => {
+    reset();
+    networkScripts.clear();
+  });
+
+  pi.registerCommand("netguard", {
+    description: "Show network guard status; /netguard reset revokes session approvals",
+    handler: async (args, ctx) => {
+      if (args.trim() === "reset") reset();
+      ctx.ui.notify(`Netguard active: ${approved.size} exact command(s) approved for this session. Use /netguard reset to revoke.`, "info");
+    },
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "write" && typeof event.input.content === "string") {
+      trackScript(event.input.path, event.input.content, true);
+      return;
+    }
+    if (event.toolName === "edit" && Array.isArray(event.input.edits)) {
+      const added = event.input.edits.map((edit: { newText?: unknown }) => String(edit?.newText ?? "")).join("\n");
+      trackScript(event.input.path, added, false);
+      return;
+    }
+    if (event.toolName !== "bash" && event.toolName !== "powershell") return;
+    const command = event.input.command;
+    if (typeof command !== "string") {
+      return { block: true, reason: "Netguard: shell command could not be inspected." };
+    }
+    const reasons = detectNetwork(command);
+    for (const name of networkScripts) {
+      if (runsScript(command, name)) reasons.push(`runs ${name}, written this session with network-capable code`);
+    }
+    if (reasons.length === 0) return;
+
+    const cwd = ctx.cwd;
+    const key = JSON.stringify([event.toolName, cwd, command]);
+    const started = generation;
+    // Serialize our dialogs even when the host dispatches tool calls concurrently.
+    const decision = queue.then(async (): Promise<ToolCallEventResult | undefined> => {
+      const block = (reason: string): ToolCallEventResult => ({ block: true, reason: `Netguard: ${reason}` });
+      if (started !== generation || ctx.signal?.aborted) return block("approval was cancelled.");
+      if (event.input.command !== command || ctx.cwd !== cwd) return block("command or working directory changed; retry for review.");
+      if (!ctx.hasUI) return block("recognized network-capable command requires interactive approval.");
+      if (approved.has(key)) return;
+
+      let choice: string | undefined;
+      try {
+        choice = await ctx.ui.select(
+          `Netguard: network approval required (${event.toolName})\n` +
+          `${reasons.join("; ")}\n\n${displayCommand(command)}\n\n` +
+          "Approval permits the whole command, including subprocesses. Session approval matches this command and working directory; files and environment may change.",
+          [BLOCK, ONCE, SESSION],
+          { signal: ctx.signal },
+        );
+      } catch {
+        return block("approval UI failed; command blocked.");
+      }
+
+      if (started !== generation || ctx.signal?.aborted) return block("approval was cancelled.");
+      if (event.input.command !== command || ctx.cwd !== cwd) return block("command or working directory changed during approval; retry for review.");
+      if (choice !== ONCE && choice !== SESSION) {
+        ctx.ui.notify("Netguard blocked a network-capable command.", "warning");
+        return block("network-capable command was not approved. Ask the user before retrying.");
+      }
+      if (choice === SESSION) approved.set(key, command);
+      ctx.ui.notify(choice === SESSION ? "Netguard approved this exact command for this session." : "Netguard approved this command once.", "info");
+    });
+    // A failed request must not poison subsequent requests in the queue.
+    queue = decision.then(() => undefined, () => undefined);
+    return decision;
+  });
+}