--- slug: "ramtinj95-pi-infra-command-guard" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/ramtinJ95/pi-infra-command-guard@main/README.md" repo: "https://github.com/ramtinJ95/pi-infra-command-guard" source_file: "README.md" branch: "main" --- # infra-command-guard Global pi extension that wraps the built-in `bash` tool and intercepts direct and GPT-5.6 Code Mode `exec_command` calls, asking for approval before higher-risk infrastructure, cloud, and destructive local-file commands. ## Install ```bash pi install npm:@ramtinj95/pi-infra-command-guard ``` Then run `/reload` or restart Pi. Pi packages execute with full system access; review this extension before installation. ## Goals - Keep normal `bash` behavior and rendering for allowed commands - Guard the `exec_command` developer tool used by API-style Pi sessions - Guard nested `tools.exec_command(...)` calls after Code Mode resolves their runtime arguments - Fail closed at the outer Code Mode `exec` call if its nested provider cannot be guarded - Add a fast in-process guard before execution - Fail closed outside TUI mode - Stay separate from Claude hooks - Allow `kubectl port-forward`, including common wrapped/backgrounded forms - Mirror the Claude hook flow: block first, have the model call an approval tool with a plain-language explanation, then allow one exact execution-context retry only if approved ## What it auto-allows ### kubectl Low-risk diagnostics and read-style commands, including: - `get` - `describe` - `logs` / `log` - `top` - `explain` - `api-resources` - `api-versions` - `version` - `wait` - `diff` - `port-forward` - wrapped/backgrounded `kubectl port-forward` commands when the command's kubectl usage is limited to port-forward - `auth can-i` - `auth whoami` - `rollout status` - `rollout history` ### terraform Low-risk planning and inspection commands, including: - `fmt` - `validate` - `version` - `graph` - `providers` - `init` - `plan` - `show` - `state list` - `state show` - `workspace list` - `workspace show` - `workspace select` ### helm Explicitly low-risk operations including: - `version`, `env`, and `help` - `list`, `status`, and `history` - `search`, `show`, `template`, `lint`, and `verify` - `repo list`, `plugin list`, and `dependency list` `helm get` remains guarded because stored release values and manifests can expose secrets. Commands using `--post-renderer` remain guarded because they execute an external program. ### argocd Explicitly low-risk operations including: - `version`, `help`, and `completion` - `app list`, `get`, `history`, `logs`, `resources`, and `wait` - `app actions list` - `cluster list|get` - `repo list|get` - `proj list|get` - `account list|get|can-i` - `cert list` and `gpg list` `argocd app diff` and `app manifests` remain guarded because rendered output can expose secret material. ### AWS CLI Read-style service operations such as `describe-*`, `get-*`, `list-*`, `head-*`, `search-*`, `scan`, `query`, and waiters are allowed. Explicit diagnostics and content reads include CloudWatch Logs filtering/tailing, S3 Select, RDS log download, Route 53 DNS tests, and CloudFormation cost estimation. Sensitive exceptions remain guarded, including Secrets Manager reads, SSM parameter-value retrieval, credential/token retrieval, and STS operations other than `get-caller-identity`. Unknown operations fail closed. ### Azure CLI Stable commands with explicit read-style actions such as `list`, `show`, `get-*`, `exists`, `query`, diagnostics/tests, log tailing, patch assessment, `status`, `validate`, `wait`, and deployment `what-if` are allowed. Secret, credential, key-value, connection-string, and app-setting reads remain guarded. Mutating or unknown actions fail closed. ### Google Cloud CLI Stable commands with explicit read-style actions such as `list`, `describe`, `get-*`, `read`, `search-*`, logs, storage `cat`/`du`/`hash`, IAM policy troubleshooting, `status`, and operation waits are allowed. Authentication-token output, credential retrieval, and Secret Manager reads remain guarded. `alpha`, `beta`, `--flags-file`, mutating, and unknown commands fail closed. ### Local file tools Ordinary `find` searches and `rsync` transfers without deletion flags are allowed. `rsync --dry-run` and `rsync -n` remain allowed even when showing what a deletion-enabled transfer would do. Executable-bearing rsync options remain guarded when they contain shell behavior or delegate to another guarded tool. Help/version-only invocations of `unlink`, `rmdir`, `shred`, and `truncate` are also allowed. ## What requires approval - Mutating infra commands such as `kubectl delete`, `terraform apply`, `helm upgrade`, `argocd app sync`, `aws ec2 terminate-instances`, `az vm delete`, and `gcloud compute instances delete` - `rm` commands - Wrapped or path-qualified `rm` commands such as `sudo rm`, `env rm`, and `/bin/rm` - `unlink`, `rmdir`, `shred`, and `truncate` mutations - `find -delete` - `rsync --delete`, its timing/exclusion variants, `--delete-missing-args`, and `--remove-source-files` unless dry-run mode is active - Executables resolved through shell variables, such as `$TOOL ...` - Assignment-based indirection such as `K=kubectl; $K ...` - Commands the guard cannot classify safely - Indirect shell-runner patterns such as `bash -lc "kubectl ..."` or `xargs kubectl ...`, except for commands whose kubectl usage is limited to `port-forward` - Some sensitive read paths, e.g. Kubernetes secrets, cloud secret values, credentials, tokens, keys, and connection strings ## Approval flow 1. The wrapped `bash` tool or direct/nested `exec_command` preflight blocks the command and returns a pending approval request identifier to the model. 2. The model must call `approve_infra_command` with: - the pending approval request identifier - the exact blocked command - the guard reason - a structured summary of what the command does - important flags/options and what they change - the concrete blast radius 3. Pi opens a scrollable overlay with one consistent layout: command, guard reason, summary, flags/options, blast radius, then `Cancel` / `Approve and run`. 4. If approved, the extension records a one-time approval for that exact execution context. 5. The model retries the exact same shell call; the guard consumes the approval and runs it. Approvals expire after ten minutes. If the command, working directory, requested shell, TTY mode, login mode, or tool path changes, the retry is blocked again. The request identifier is required. Missing, expired, or mismatched request identifiers are rejected; the blocked command must be rerun to create a fresh request. ## Code Mode integration The current integration wraps Code Mode's in-process nested `exec_command` provider. The wrapper resolves dynamic JavaScript before applying the guard, so commands assembled at runtime are covered without parsing the outer JavaScript source. This adapter uses `pi-codex-conversion` internals until that package exposes a supported nested-tool preflight API. The guard installs the wrapper at session/turn startup and verifies it again before every outer `exec` or `wait`. If an update changes those internals, the outer Code Mode call is blocked with a compatibility error instead of silently running unguarded. The current package is validated with Pi 0.81.1 and `@howaboua/pi-codex-conversion` 2.2.16. Normal Pi `bash` guarding does not require Code Mode. Because the Code Mode adapter intentionally fails closed around private internals, test the guard after upgrading either package. ## Configuration Configure the extension in `~/.pi/agent/infra-command-guard.json`. When `PI_CODING_AGENT_DIR` overrides Pi's configuration directory, put `infra-command-guard.json` there instead. The extension reads the file for every shell command and approval request, so edits apply immediately without `/reload`. ### Guard toggles Every guard is enabled by default. Add only the overrides you need: ```json { "$schema": "https://raw.githubusercontent.com/ramtinJ95/pi-infra-command-guard/main/infra-command-guard.schema.json", "guards": { "terraform": false, "az": false, "rm": false } } ``` Available keys are `kubectl`, `terraform`, `helm`, `argocd`, `aws`, `az`, `gcloud`, `rm`, `unlink`, `rmdir`, `shred`, `truncate`, `find`, and `rsync`. A disabled guard bypasses policy checks for direct, path-qualified, and recognized wrapper invocations such as `sudo` and `env`. Enabled guards in the same command remain enforced. Dynamic executable expressions such as `$TOOL apply` still require approval while any guard is enabled because the target cannot be identified safely. Opaque shell-runner commands also remain conservative when they mention an enabled guard name. Changing guard settings invalidates pending requests and unused one-time approvals. Run the command again under the new configuration if approval is still required. Existing configuration files without `guards` retain the current behavior with every guard enabled. Invalid configuration fails safe: every command guard remains enabled and Pi displays a warning. ### Command overrides Enabled guards can customize individual commands: ```json { "commands": { "terraform": { "allow": ["output"], "requireApproval": ["plan -destroy"] }, "kubectl": { "allow": ["delete pod dev-*"], "requireApproval": ["logs"] } } } ``` - `allow` bypasses the built-in policy for a matching command. This can permit mutations, sensitive output, and any unmatched trailing command flags, so keep rules narrow. An allow rule must contain at least one literal character; use the CLI's master toggle instead of an all-wildcard rule. - `requireApproval` forces approval even when the built-in policy would allow the command. - `requireApproval` wins if both lists match. - `guards.: false` is the master switch and ignores all command overrides for that CLI. Rules omit the executable and match case-sensitive normalized argument prefixes. Executable paths and recognized wrappers such as `sudo` and `env` are ignored. Known non-command global CLI options are removed wherever they occur before matching, while command-specific flags, arguments, and command-like `--help`/`--version` options retain their order. `*` matches characters within one token and never crosses whitespace. For example, `delete pod dev-*` matches `sudo kubectl --context production delete pod dev-api --wait=false`, but not `kubectl delete pod production-api`. Because rules are prefixes, every trailing argument is also covered by the match; use `requireApproval` for narrower exceptions that must remain guarded. Overrides apply only after the shell invocation has been parsed safely. They do not bypass dynamic executable, opaque shell-runner, unsupported shell syntax, interactive-session, rsync executable-option, `kubectl --raw`, `gcloud --flags-file`, or Helm post-renderer restrictions. Changing command rules also invalidates pending requests and unused approvals. Invalid rules are ignored together with the rest of the invalid configuration, leaving every guard enabled under its built-in policy. ### Approval notifications and sound The package is silent by default and ships no audio files. Configure attention mechanisms in `~/.pi/agent/infra-command-guard.json`: ```json { "$schema": "https://raw.githubusercontent.com/ramtinJ95/pi-infra-command-guard/main/infra-command-guard.schema.json", "guards": { "terraform": false, "az": false }, "notifications": { "enabled": true, "backend": "auto" }, "integrations": { "herdr": { "enabled": true } }, "sound": { "enabled": false, "path": null } } ``` ### Notification backends - `auto` (recommended): use native notifications on macOS and Windows; on Linux, prefer a recognized terminal notifier and fall back to `notify-send` - `terminal`: require Kitty OSC 99 or Ghostty OSC 9; unknown terminals produce a visible Pi warning - `native`: use Notification Center through `osascript` on macOS, `notify-send` on Linux, or a notification balloon on Windows Kitty notifications explicitly request silent delivery so custom sound remains separately controlled. Other terminal emulators and desktop notification services can still apply user-level notification policies. Terminal protocols cannot confirm that the OS displayed a notification after accepting the control sequence. Use `/infra-guard-notify-test` after configuring the extension. If terminal delivery is blocked by terminal or OS permissions, select `native` instead. ### Herdr integration Herdr panes terminate application escape sequences inside Herdr's emulated terminal; raw Kitty or Ghostty notification sequences do not reach the outer terminal. When `integrations.herdr.enabled` is `true` (the default) and `HERDR_ENV=1`, `auto` uses native OS delivery instead of emitting unusable terminal sequences. Explicit `terminal` uses Herdr's notification broker: ```toml [ui.toast] delivery = "terminal" ``` That setting belongs in Herdr's configuration. Herdr can also be configured for `system`, `herdr`, or `off`; infra-command-guard does not override it. Explicit `terminal` reports failure if Herdr does not show the request. Herdr currently reuses one Kitty notification identifier, so later terminal notifications can update an existing notification without showing a fresh banner. Use `auto` or `native` when reliable attention matters. Set `integrations.herdr.enabled` to `false` to disable all Herdr-specific routing. ### Custom sound To play a user-supplied sound independently of the notification backend: ```json { "notifications": { "enabled": true, "backend": "auto" }, "integrations": { "herdr": { "enabled": true } }, "sound": { "enabled": true, "path": "sounds/infra-approval.wav" } } ``` `~` is expanded. Relative paths resolve from the directory containing `infra-command-guard.json`. The extension uses `afplay` on macOS, tries `paplay` then `aplay` on Linux, and supports WAV through PowerShell on Windows. Invalid JSON, unknown fields, malformed command rules, non-boolean guard values, unsupported backend values, and enabled sound without a path produce a Pi warning. Invalid configuration keeps every command guard enabled under its built-in policy and disables attention mechanisms for that request. Notification and sound failures never authorize or execute the blocked command. Version 0.2.0 replaces the 0.1.x `PI_INFRA_COMMAND_GUARD_SOUND_PATH` and `PI_INFRA_COMMAND_GUARD_NATIVE_NOTIFICATION` environment variables with this JSON file. ## Notes - This guards the LLM `bash` tool override, not user `!command` shell usage. - Interactive shell/interpreter sessions requested with `tty=true` are denied rather than approvable because later `write_stdin` input cannot be classified reliably. Run complete non-interactive commands instead. - Code Mode TOML custom tools execute their configured programs directly and are trusted capabilities outside this `exec_command` guard. - This is an in-process policy guard, not an OS sandbox. It cannot know that an inherited alias, shell function, opaque script, or custom executable eventually invokes guarded tooling when the command contains no guarded name or dynamic executable position. Kubernetes RBAC, scoped Terraform credentials, and filesystem permissions remain the hard security boundary. - Interactive approval uses a custom scrollable overlay instead of pi's default confirm popup. - `↑` / `↓` scroll - `PgUp` / `PgDn` or `Ctrl+u` / `Ctrl+d` page - `g` / `G` jump to top/bottom - `j` / `k` move between `Cancel` and `Approve and run` - The model supplies structured fields rather than a markdown blob, so the UI avoids repeating command/reason/blast-radius text. - Because it overrides the built-in `bash` tool, pi may show the standard override warning in interactive mode. - No notification setting is required; notifications and sound are opt-in. ## Reload Run: ```bash /reload ``` or restart pi. ## Tests From the repository root: ```bash npm install npm test npm run test:package npm run benchmark:policy ``` The cloud policy corpus covers hundreds of documented read, mutation, sensitive-read, authentication, and local-configuration decisions. Each decision is exercised through path-qualified executables, wrappers, global-option placements, shell composition, pipelines, and simple executable obfuscation.