@burtson-labs/bandit-stealth-cli 1.7.503 → 1.7.504

package/README.md

@@ -354,6 +354,17 @@ Separate from `config.json`, a **settings** file controls what the agent is allo
 - `~/.bandit/settings.json` — global (all workspaces)
 - `<workspace>/.bandit/settings.json` (and `.bandit/settings.local.json`) — per-project
 
+**A folder's `.bandit` settings need your trust.** The files in a checkout were written by whoever wrote the repository. Until you trust the folder they can only narrow Bandit (`deny`/`ask` rules, a narrower `permissions.mode`, `offline`, extra guard rules); their `hooks`, `permissions.allow`, a wider mode and `security.guard.enabled: false` are ignored, and the session says so in one line: `Bandit ignored part of .bandit/settings.json in "acme-app": 3 hooks, permissions.mode. Until you trust this folder, its .bandit settings can only narrow what Bandit does.` To trust it:
+
+```bash
+bandit trust            # shows every hook command, allow rule and mode the folder defines, then asks
+bandit trust --yes      # for a script, after you have read the files
+bandit trust --list     # folders you have trusted
+bandit untrust          # stop trusting this folder
+```
+
+Hooks run as shell commands on your machine, with your privileges, so read the files before trusting. Trust is per folder (a trusted folder covers its subfolders), recorded in `~/.bandit/trusted-workspaces.json` (`{ "trusted": ["/path/to/project"] }`) and shared with the VS Code extension's **Bandit Stealth: Trust this folder's .bandit settings** command — a folder trusted in one is trusted in the other. `BANDIT_TRUST_PROJECT_SETTINGS=1` trusts the current workspace for one process, for CI, where the checkout is the job's own. Your own `~/.bandit/settings.json` always applies, and "always allow" choices you save from a permission prompt keep working in an untrusted folder. `/doctor` shows the folder's trust state.
+
 ```jsonc
 {
   // Built-in pre-tool security guard. ON by default. Blocks the
@@ -514,6 +525,7 @@ bandit-agent --model qwen2.5-coder:32b
 - **Container sandbox (opt-in)** — `bandit --sandbox` or `BANDIT_SANDBOX=1` runs every agent `run_command` / `watch_command` inside a short-lived Docker or Podman container with the same policy as the Stealth IDE: one workspace mount, no network, no Linux capabilities, read-only root, `no-new-privileges`, bounded CPU/memory/pids/output/time, your uid:gid. On a cluster with neither, Apptainer or Singularity run the same image (pulled by digest into a SIF under `$APPTAINER_CACHEDIR/stealth-sandbox` or `~/.bandit/sandbox-apptainer`), as you, with the network namespace checked before every command and the command refused when it cannot be isolated (`sandbox/README.md`, Apptainer). `BANDIT_SANDBOX_RUNTIME=apptainer` (or `docker`, `podman`, `singularity`, comma-separated) picks the runtime. Fail-closed once enabled — no runtime means the command is refused, never quietly run on the host. Image: `ghcr.io/burtson-labs/stealth-sandbox`, chosen from the project's files — the base (node, git, ripgrep, python3, C toolchain) or the dotnet, go, rust or python image built on it; override with `BANDIT_SANDBOX_IMAGE` (a stack name or an image reference). `BANDIT_SANDBOX_INSTALL_NETWORK=1` gives install commands (`npm install`, `pip install`, `dotnet restore`, `go mod download`, …, run on their own) the network; every other command stays offline. Enterprise-managed installs should set `BANDIT_SANDBOX=1` in the environment. Inside the sandbox `run_command` also runs programs the workspace itself provides: a binary the agent just built (`./heat`, `build/heat`), a repo script (`tools/dryrun.sh`), a venv interpreter (`.venv/bin/python`), and a shell given such a script (`bash tools/dryrun.sh`; `bash -c` stays blocked). The allow-list exists to keep the agent from running arbitrary code with your files, keys and network; in the container the workspace mount is the only thing a program can change and there is no network, so a workspace program has the same reach as `make`, `npm test` or `python3 script.py`, which the list already allows. On the host (no `--sandbox`) the allow-list applies as before and the model is told to ask you to run the program. Paths must be relative, contain a `/` and stay inside the workspace (no `..`, `~`, absolute paths or drive letters); the blocked-pattern check runs on every command either way.
 - **Pre-tool security guard** (default-on) — configure `security.guard` in your [settings file](#settings-file--hooks-permissions-security-guard) to extend or explicitly disable blocking of 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.
+- **Workspace trust** — a repository's own `.bandit/settings.json` cannot run hooks, add allow rules or widen the permission mode until you run `bandit trust` in that folder (or set `BANDIT_TRUST_PROJECT_SETTINGS=1` in CI); see [the settings file](#settings-file--hooks-permissions-security-guard). A clone is read-only configuration until you say otherwise.
 - **Secret hygiene** — API keys are redacted in `/config` output and never logged. The optional [telemetry](#telemetry-opt-in) exporter sends no prompt or reply text, and runs the tool arguments it does send through secret redaction.
 - **Local sessions** — stored as JSONL under `~/.bandit/sessions/`. Inspect at any time.
 - **Turn logs** — each turn is logged to `<project>/.bandit/turns/` (your prompt, tool calls and short excerpts of tool output). When Bandit creates `.bandit/`, it writes `.bandit/.gitignore` so these logs, checkpoints and pasted images are not committed. It never overwrites an existing `.bandit/.gitignore`. If your project's `.bandit/` predates this, add `turns/` and `checkpoints/` to it yourself.