@burtson-labs/bandit-stealth-cli 1.7.368 → 1.7.370

package/README.md

@@ -74,7 +74,7 @@ That's it. No API keys. No cloud services. The agent reads your code, searches,
 - **Project memory** — drop a `BANDIT.md` or `CLAUDE.md` at your workspace root and it's auto-loaded into the system prompt
 - **File + image mentions** — `@path` auto-inlines files; images are either sent multimodally or OCR'd locally (Apple Vision / tesseract)
 - **Clipboard paste** — `Ctrl+V` in the REPL pastes an image straight from your clipboard
-- **Hooks** — `PreToolUse` / `PostToolUse` / `Stop` shell hooks via `.bandit/settings.json`
+- **Hooks + security guard** — `PreToolUse` / `PostToolUse` / `Stop` shell hooks (global `~/.bandit/settings.json` or per-workspace), plus an opt-in built-in guard that blocks catastrophic commands. See [Settings file](#settings-file--hooks-permissions-security-guard)
 - **12 themes** — Stealth Light/Dark, Midnight, Onyx, Charcoal, Dracula, Nord, Tokyo Night, Solarized Dark/Light, Catppuccin Mocha, Sepia. `/theme` to pick
 - **Cross-platform** — macOS, Linux, Windows; Windows `.cmd`/`.bat` shims (npm/npx/pnpm/tsc) resolved correctly
 - **Update-aware** — fire-and-forget npm-registry check at boot; `update vX.Y.Z available` shows in the status bar when a newer CLI is published
@@ -263,8 +263,99 @@ Workspace config overrides user config. Secrets belong in the user-level file, n
 | `OLLAMA_URL` | `http://localhost:11434` | Ollama endpoint |
 | `BANDIT_MAX_ITERATIONS` | `20` | Tool-use loop cap |
 | `BANDIT_AUTO_APPROVE` | `0` | `1`/`true` to skip write-approval prompts |
+| `BANDIT_TELEMETRY` | `0` | `1`/`true` to enable OTLP telemetry (opt-in) |
+| `BANDIT_OTLP_ENDPOINT` | `https://otlp.burtson.ai` | OTLP/HTTP collector base URL |
+| `BANDIT_OTLP_TOKEN` | — | Bearer token for the collector (defaults to your Bandit token) |
+| `BANDIT_OTLP_MODE` | `metrics+traces` | `metrics-only` to drop span payloads |
 | `NO_COLOR` | — | Disable ANSI colors |
 
+### Settings file — hooks, permissions, security guard
+
+Separate from `config.json`, a **settings** file controls what the agent is allowed to do. It's read from two places and **merged** — the global file applies to every repo, the workspace file adds project-specific rules on top:
+
+- `~/.bandit/settings.json` — global (all workspaces)
+- `<workspace>/.bandit/settings.json` (and `.bandit/settings.local.json`) — per-project
+
+```jsonc
+{
+  // Built-in pre-tool security guard. OPT-IN, off by default. Blocks the
+  // handful of tool calls that are almost never legitimate, BEFORE they run —
+  // a safety net against the model footgunning (e.g. a hallucinated rm -rf /).
+  "security": {
+    "guard": {
+      "enabled": true,
+      "blockCommands": ["npm\\s+publish"],   // optional: extra regex patterns to block
+      "protectPaths": ["/data/prod"]          // optional: extra write-protected path prefixes
+    }
+  },
+
+  // Your own shell hooks around the tool loop. A non-zero exit from a
+  // PreToolUse hook BLOCKS the tool call. Placeholders: {{name}}, {{primary}},
+  // {{duration}} (PostToolUse only).
+  "hooks": {
+    "PreToolUse":  [{ "match": "write_file", "command": "./scripts/guard.sh {{name}}" }],
+    "PostToolUse": [{ "match": ".*",         "command": "echo {{name}} took {{duration}}ms" }],
+    "Stop":        [{ "command": "./scripts/notify-done.sh" }]
+  },
+
+  // Per-tool permission policy (deny > allow > ask > built-in defaults).
+  "permissions": { "allow": ["run_command:git *"], "deny": [], "ask": ["run_command"] }
+}
+```
+
+**What the guard blocks when enabled** (high-confidence patterns only, so false positives stay rare):
+catastrophic `rm -rf /` · `~` · `/*` · a remote script piped to a shell (`curl … | sh`) · raw disk writes (`dd of=/dev/sda`, `mkfs`) · fork bombs · recursive `chmod`/`chown` on `/` · writes or redirects into system/credential paths (`/etc`, `~/.ssh`, `~/.aws`, …) · reading a credential file **and** sending it over the network in one command.
+
+The guard is **defense-in-depth against the model**, not a sandbox and not protection against a malicious user (who controls this file). It runs **before** your hooks and the approval gate, and behaves identically in the CLI and the IDE extension.
+
+#### Hooks — any scripted step, not just guardrails
+
+Hooks run **your own commands** at three points in the loop. Only `PreToolUse` is a gate; the rest are fire-and-forget side effects — so reach for them for version bumps, formatters, notifications, CI triggers, anything scriptable.
+
+| Event | Fires | Blocks the tool? |
+|---|---|---|
+| `PreToolUse` | before a tool runs | **Yes** — a non-zero exit aborts the call (this is the guardrail path) |
+| `PostToolUse` | after a tool finishes | No — runs for its side effect |
+| `Stop` | when the turn ends | No |
+
+Each rule is `{ "match": "<regex on tool name — omit to match all>", "command": "<shell>", "timeout": 10000 }`. Placeholders are substituted into `command` (shell-escaped): **`{{name}}`** (tool name), **`{{primary}}`** (first arg — path / cmd / pattern / url), **`{{duration}}`** (ms, `PostToolUse` only).
+
+```jsonc
+"hooks": {
+  // guardrail: refuse edits to a generated file
+  "PreToolUse":  [{ "match": "write_file|apply_edit", "command": "grep -q '@generated' {{primary}} && exit 1 || exit 0" }],
+  // housekeeping: format after every edit; bump the build number after any tool
+  "PostToolUse": [
+    { "match": "write_file|apply_edit", "command": "prettier --write {{primary}} || true" },
+    { "match": ".*",                    "command": "./scripts/bump-build-number.sh {{name}}" }
+  ],
+  // notify when a turn ends
+  "Stop": [{ "command": "terminal-notifier -message 'Bandit finished' || true" }]
+}
+```
+
+### Telemetry (opt-in)
+
+Off by default. When enabled, Bandit emits **OpenTelemetry** over OTLP/HTTP: one **trace per turn** (LLM + tool calls as spans, errors marked) plus **usage metrics** (tokens, time-to-first-token, turn duration). The wire format is standard OTLP, so **you point it at your own collector** — Grafana/Tempo, an OpenTelemetry Collector, App Insights, Datadog, anything that speaks OTLP/HTTP.
+
+> **Where does it go?** You decide. Set `endpoint` to your collector. The example below uses `otlp.burtson.ai` — that's **Burtson's** hosted collector and only accepts Bandit Cloud accounts; if you're not a Bandit Cloud user, point `endpoint` at your own and set your own `headers`.
+
+```jsonc
+// ~/.bandit/config.json
+{
+  "telemetry": {
+    "enabled": true,
+    "endpoint": "https://otel.your-company.com",   // YOUR OTLP collector (otlp.burtson.ai = Bandit Cloud only)
+    "mode": "metrics+traces",                        // or "metrics-only" for stricter privacy
+    "headers": { "Authorization": "Bearer ..." }     // your collector's auth (defaults to your Bandit token)
+  }
+}
+```
+
+The default `endpoint` is `https://otlp.burtson.ai` only because the default audience is Bandit Cloud; **set your own** otherwise.
+
+**Privacy:** prompt and completion **text is never sent** — only metadata (model, tool name, durations, token counts), and that metadata is run through secret redaction first. `metrics-only` drops traces entirely. Nothing is sent unless you set `enabled: true` (or `BANDIT_TELEMETRY=1`).
+
 ### Remote GPU
 
 Running a bigger model on a remote Ollama instance? Point `OLLAMA_URL` at the remote endpoint and set `BANDIT_MODEL` to the bigger model. Requests route to the remote node; everything else stays local.
@@ -314,7 +405,9 @@ Tear the pod down when you're done. ~$2/hr for an H100 SXM × 15-20 min agent se
 - **Local-first by default** — with `provider=ollama`, nothing leaves your machine.
 - **Approval gate** — all file writes show a unified diff before touching disk (unless `BANDIT_AUTO_APPROVE=1`).
 - **Command allowlist** — `run_command` only executes from an internal allowlist (git, gh, kubectl, helm, brew, standard *nix tools). Arbitrary shell is refused.
-- **Secret hygiene** — API keys are redacted in `/config` output and never logged.
+- **Pre-tool security guard** (opt-in) — enable `security.guard` in your [settings file](#settings-file--hooks-permissions-security-guard) to block catastrophic commands (`rm -rf /`, `curl … | sh`, disk wipes, credential exfil, writes to `/etc` or `~/.ssh`) before they run. Defense-in-depth against the model, applied in both CLI and IDE.
+- **Custom hooks** — your own `PreToolUse` shell scripts can veto any tool call; configure globally (`~/.bandit/settings.json`) or per-project.
+- **Secret hygiene** — API keys are redacted in `/config` output and never logged. The optional [telemetry](#telemetry-opt-in) exporter never sends prompt/response text and redacts metadata.
 - **Local sessions** — stored as JSONL under `~/.bandit/sessions/`. Inspect at any time.
 
 ---