Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 ducoterra
|
209f167e43 | ||
|
ducoterra
|
34f94e38be |
@@ -0,0 +1,127 @@
|
|||||||
|
---
|
||||||
|
name: doc-sandbox
|
||||||
|
description: Answers questions about ai-sandbox and ai-sandbox-autophase — what a flag or config key does, why a run refused to start (exit 77/78), how the egress allowlist, the squid gate and the in-container nftables ruleset work together, how the ~/.agents share or the pi config bridge or the base-image digest pinning behaves, what the image contains, how to run a given harness or language, what the sandbox does and does not protect against, and how the phase driver splits sandbox work from host git. Use when the user asks what something in ai-sandbox means, is about to, or just did, run ai-sandbox and wants an explanation, hits a sandbox error, or asks about the tool's design, security model or limitations. Answers from the installed program's own text plus the repo docs and tests, never from memory; runs only side-effect-free preview commands and never a build, container, or network call.
|
||||||
|
---
|
||||||
|
|
||||||
|
# doc-sandbox
|
||||||
|
|
||||||
|
ai-sandbox is one bash script that generates its own Containerfile, container entrypoint, squid
|
||||||
|
config and netfilter rules. That is what makes it answerable: the text of the program *is* the
|
||||||
|
documentation of the installed version, and three of its flags print the artifacts it generates.
|
||||||
|
Read those; do not recall.
|
||||||
|
|
||||||
|
## Ground truth, in this order
|
||||||
|
|
||||||
|
1. **The installed program** — `ai-sandbox --help`, and its source: `readlink -f "$(command -v
|
||||||
|
ai-sandbox)"`. If they disagree, the installed program is what the user will run.
|
||||||
|
2. **The repository**, if present: `README.md` (what and why), `docs/networking.md` (the
|
||||||
|
*measurements* behind the enforcement model), `docs/threat-model.md` (what is **not** protected),
|
||||||
|
`docs/recipes.md` (invocations per harness/ecosystem/pipeline), `AGENTS.md` (design rules).
|
||||||
|
3. **The tests** — the executable spec. `tests/unit/*` needs no containers and states exact shapes;
|
||||||
|
`tests/e2e/*` proves behaviour in a real container (e.g. `11_net.sh` for "can the agent lift the
|
||||||
|
ruleset"). When behaviour is subtle, the test answers better than prose.
|
||||||
|
4. **This skill's fact sheet** — fast, but if it conflicts with the above, the above wins and this
|
||||||
|
file is a bug to fix.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash scripts/locate.sh # where each of those lives on this machine, and the version
|
||||||
|
```
|
||||||
|
|
||||||
|
## Working a question
|
||||||
|
|
||||||
|
1. Classify it: a **flag/key**, a **failure**, a **mechanism** ("how is egress enforced"), a
|
||||||
|
**security boundary** ("can it read my ssh keys"), or a **pipeline** question. Then read
|
||||||
|
`references/source-map.md` — it maps each to the function, doc and test that hold the answer.
|
||||||
|
2. Read that source. Grep, don't skim: `grep -n 'print-policy' bin/ai-sandbox`.
|
||||||
|
3. Check the version you read (`ai-sandbox version`) and say which one you read when it matters —
|
||||||
|
behaviour that changed recently includes the working-directory mirroring, the `settings.json`
|
||||||
|
per-key merge, the `xhigh` thinking policy and the base digest pinning.
|
||||||
|
4. If the question is about *this machine's* behaviour, prefer a preview command over an opinion
|
||||||
|
(§safe commands) and quote its output.
|
||||||
|
5. Answer in the format below. If the source does not contain it, say **it does not exist** and
|
||||||
|
name the closest real thing — a plausible invented flag is the worst failure mode available here.
|
||||||
|
|
||||||
|
## Answer format
|
||||||
|
|
||||||
|
* **The answer, one or two sentences**, in the user's terms.
|
||||||
|
* **The command** to run, copy-pasteable, with real flag spellings.
|
||||||
|
* **Where it comes from**: `bin/ai-sandbox` (`build_argv()`), or `docs/networking.md`, or
|
||||||
|
`tests/e2e/11_net.sh`. So they can check you.
|
||||||
|
* **What it does *not* do**, whenever the question touched security — e.g. "the allowlist limits
|
||||||
|
*where*, not *what*: an allowlisted remote plus a token can ship your code."
|
||||||
|
* A pointer to `docs/threat-model.md` when the honest answer is "this is out of scope" (kernel
|
||||||
|
escapes, anything allowlisted, anything you mounted).
|
||||||
|
|
||||||
|
## Safe to run while answering
|
||||||
|
|
||||||
|
```
|
||||||
|
ai-sandbox --help ai-sandbox version
|
||||||
|
ai-sandbox --dry-run the effective invocation, env values redacted
|
||||||
|
ai-sandbox --print-entrypoint the enforcement script baked into the image
|
||||||
|
ai-sandbox --print-containerfile the generated Containerfile
|
||||||
|
ai-sandbox --print-policy effective policy as key=value -- with one caveat, below
|
||||||
|
```
|
||||||
|
|
||||||
|
These build nothing, start no container, write no session state and reach no registry — that is a
|
||||||
|
deliberate property of the tool (preview modes are what make it scriptable), so use them freely.
|
||||||
|
They read config files, so they show the *effective* policy where you are. Two honest exceptions:
|
||||||
|
`--print-policy` also ensures the home-cache volume exists, so it fails without podman (a deviation
|
||||||
|
from the repo's own "preview must not write state" rule, worth reporting rather than repeating);
|
||||||
|
and with `--no-gate`, resolving domain entries does hit DNS.
|
||||||
|
|
||||||
|
Not for an explanation, unless the user asked about the machine and agrees:
|
||||||
|
|
||||||
|
* `inspect` — prints the same policy but resolves the base digest **now**, so it may contact the
|
||||||
|
registry.
|
||||||
|
* `doctor [--deep]` — host checks; `--deep` runs a real container and probes egress.
|
||||||
|
* `build`, `update`, `gate up`, `clean`, and any real run — these change the machine.
|
||||||
|
* `cat`ing `~/.pi/agent/models.json` to answer a question about the bridge: read the *code*
|
||||||
|
(`pi_config_bridge()`), not the file with a live key in it. Never echo a credential, an
|
||||||
|
`auth.json`, or anything from a `--env-file`.
|
||||||
|
|
||||||
|
## Facts you may state without reading (still: state the version)
|
||||||
|
|
||||||
|
| topic | fact |
|
||||||
|
|---|---|
|
||||||
|
| precedence | built-in default < `~/.config/ai-sandbox/{config,allow}` < `./.ai-sandbox/{config,allow}` < `AISB_*` < CLI. `allow/env/mount/install/label` accumulate; other keys replace |
|
||||||
|
| arg parsing | stops at the first positional or unknown flag; the rest goes **to the harness**. `--` replaces the command. `--strict-args` makes an unknown flag an error |
|
||||||
|
| default net | `allow`, and an empty allowlist in `allow` mode is a hard error, never a silent free-for-all |
|
||||||
|
| enforcement | two stacked controls: an in-container `inet aisb` nft table with `policy drop` on output, installed by the entrypoint as root before it `setpriv`s to uid 1000 with no capabilities, plus a squid gate on the host loopback that filters by domain at CONNECT |
|
||||||
|
| refusals | exit **77** ruleset could not be installed; **78** policy file missing in the container. Both are the sandbox working; `--allow-unenforced` is the named escape hatch |
|
||||||
|
| gate ports | squid relays only **80, 443, 8443**; `--allow domain:8080` is not what it looks like. IP/CIDR entries are direct netfilter rules instead (default ports 80,443) |
|
||||||
|
| host services | `100.64.0.1` (config: `gate_addr`) inside the container *is* the host's loopback; only the gate's port is reachable through it unless you `--allow 100.64.0.1:<port>` |
|
||||||
|
| inbound | there is no publish flag, and in `--net allow` the generated ruleset's input chain is `policy drop` too, so a `-p` pushed through `extra_args` is dropped inside. That last half is a reading of `gen_rules()`, not a measurement — probe it (right-sandbox's `references/port-and-loopback.md`) before promising a preview URL |
|
||||||
|
| filesystem | cwd mounted rw **at its host path** (falls back to `/project` with a message when the host path would bury `/tmp`, `/usr`, `/etc`, `/var`, `/opt`, `/run`, the container home, or `/`); nothing else is mounted except the `.agents` share and the read-only policy mount at `/run/aisb` |
|
||||||
|
| the container user | uid/gid 1000, the image's own `sandbox` account, `$HOME` = its home (`--userns=keep-id`, so files the agent writes are owned by *you* on the host). Skills land at `~/.agents` on both sides and they are different directories |
|
||||||
|
| skills | host `~/.agents` → the container's `~/.agents` (`agents_dest`) **read-only**, no flag makes it writable; `--no-agents` to withhold it, `--agents-dir` for another directory. Its contents are readable by whatever runs in there |
|
||||||
|
| env | nothing inherited but `TERM LANG LC_ALL LC_CTYPE TZ` (plus `HOME`, `AISB`, `AISB_SESSION`); values travel in a `0600` file, never argv; `--env NAME` where NAME is unset **fails the run** |
|
||||||
|
| pi bridge | host `~/.pi/agent/{models,settings}.json` rewritten, not copied: `apiKey` → `"$AI_API_TOKEN"`, `!command` values dropped, `auth.json` never touched; `settings.json` merged per key; `defaultThinkingLevel` is policy (`xhigh`) re-applied every run unless `--thinking host` |
|
||||||
|
| image | one base (`ubuntu:24.04`) pinned to a **registry digest** that is part of the image tag; Node pinned + sha256-verified; `pi` version-pinned; `--install PKG` → a different tag; a build with no digest is labelled `UNPINNED` and `doctor` warns |
|
||||||
|
| limits | `cpus 4`, `memory 4g`, `pids 512`, `tmpfs 1g`; the container home is a named volume (`aisb-home`) that outlives the image, `--ephemeral-home` swaps it for a tmpfs |
|
||||||
|
| state | logs/config/cache under `~/.local/state/ai-sandbox`, `~/.config/ai-sandbox`, `~/.cache/ai-sandbox`; `~/.local/state/ai-sandbox/log` records every run **without secret values** |
|
||||||
|
| autophase | the agent *and* `.agents/validate.sh` run in the sandbox; the commits and every push happen on the host, and the git remote is deliberately unreachable from inside. Host git runs with an empty hooks path and refuses to deliver if a sandboxed unit changed `.git/config` or `.git/hooks/` |
|
||||||
|
|
||||||
|
## When the answer is "no"
|
||||||
|
|
||||||
|
Say it plainly, then give the closest real thing:
|
||||||
|
|
||||||
|
* "publish a port" → no; run the server on the host (the mount is your disk), or one named
|
||||||
|
`--net full` preview run with `AISB_EXTRA_ARGS=-p …` and an explicit warning that that run has no
|
||||||
|
egress policy.
|
||||||
|
* "make the sandbox able to write my skills" → no, by design: a skill is an instruction you follow
|
||||||
|
later on the host. Author it in the project and move it yourself.
|
||||||
|
* "let the pipeline push from inside the sandbox" → no: an agent that can push can ship what you are
|
||||||
|
about to review. `ai-sandbox-autophase` delivers on the host.
|
||||||
|
* "inherit my environment, it's annoying" → no; that ambient environment is exactly the exfil target.
|
||||||
|
Name what you need with `--env`.
|
||||||
|
* "silently fall back to no network policy when the ruleset fails" → no: exit 77.
|
||||||
|
|
||||||
|
If the user wants the missing thing, that is a change to `bin/ai-sandbox` — say which function
|
||||||
|
would carry it (`gen_rules()`, `build_argv()`, `parse_args()`), that it needs an entry in
|
||||||
|
`tests/e2e/`, and that per the repo's own rules it must fail closed and print no values.
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
* `references/source-map.md` — question topic → function / doc / test, plus the FAQ and the
|
||||||
|
vocabulary (`split_target`, `classify_allows`, gate vs `--no-gate` vs `--proxy`, `POL[]`/`P_*`/`OPT_*`).
|
||||||
|
* `scripts/locate.sh` — find the installed script, the version, the repo docs, the state dirs.
|
||||||
@@ -0,0 +1,116 @@
|
|||||||
|
# Source map
|
||||||
|
|
||||||
|
Question topic → the function, doc and test that hold the answer. Line numbers move; **names do
|
||||||
|
not** — grep for these in the installed script (`readlink -f "$(command -v ai-sandbox)"`).
|
||||||
|
|
||||||
|
## Flags, keys, defaults
|
||||||
|
|
||||||
|
| question | read |
|
||||||
|
|---|---|
|
||||||
|
| "what does `--x` do / does it exist" | `usage()` (grouped by NETWORK / FILESYSTEM / ENVIRONMENT / IMAGE / PI CONFIG / LIMITS / RUN / ESCAPE HATCHES / SUBCOMMANDS), `parse_args()`, and `KNOWN_OPTS` + `suggest()` for the accepted set |
|
||||||
|
| "which config keys are legal" | `cfg_read_kv()` — the `case` lists them, the accumulate list is `cfg_accum_keys` (`allow env mount install label`). Anything else warns `unknown key` and is ignored |
|
||||||
|
| "what wins, my flag or the file" | `resolve_opts()` — every line is `${OPT_x:-${AISB_X:-$(cfgv x default)}}`: CLI, then env, then config, then default. `load_config()` shows the file order |
|
||||||
|
| "`AISB_*` variables" | the comment block above `usage()` and `--help`'s ENVIRONMENT section |
|
||||||
|
| "why did arg parsing eat my harness flag" | `parse_args()` stops at the first positional/unknown; `--` sets `COMMAND`; `--strict-args`; `default_command()`/`harness_argv()` decide what actually runs |
|
||||||
|
| subcommand behaviour | `main()` dispatch, then `cmd_build` / `cmd_update` / `cmd_doctor` / `cmd_gate` / `cmd_ps` / `cmd_clean` / `cmd_inspect` |
|
||||||
|
|
||||||
|
## Networking and enforcement
|
||||||
|
|
||||||
|
| question | read | prove with |
|
||||||
|
|---|---|---|
|
||||||
|
| how `--net allow` holds at all | `entrypoint_script()` → `gen_rules()`, plus `build_argv()`'s `--cap-add=NET_ADMIN` + the `setpriv` line | `ai-sandbox --print-entrypoint`; `docs/networking.md` |
|
||||||
|
| can the sandboxed process lift the policy | the capabilities the entrypoint drops before exec (`--inh-caps=-all --bounding-set=-all --no-new-privs`) | `tests/e2e/11_net.sh` (flush attempt, `unshare -n`, raw socket, DNS to 8.8.8.8) |
|
||||||
|
| why an entry did nothing | `split_target()` then `classify_allows()`: domains → the gate (CONNECT-time, subdomain match); IP/CIDR/ipv6 → direct netfilter rules, ports default 80,443 | `ai-sandbox --print-policy` → `gate_domains=`, `direct=`, `direct6=` |
|
||||||
|
| which ports the gate relays | `write_squid_conf()`: `Safe_ports` 80 443 8443, `SSL_ports` 443 8443, `http_access deny all` after the allowlist | `ai-sandbox gate logs` |
|
||||||
|
| gate lifecycle / ports / reuse | `pick_port()`, `gate_up()`, `teardown()`, `cmd_gate()`; `AISB_GATE_KEEP=1`; `gate_port`/`gate_addr` | `ai-sandbox gate status` |
|
||||||
|
| `--no-gate` vs `--proxy` vs the gate | `resolve_proxy_endpoints()` — `--proxy` uses your proxy (default port 3128); `--no-gate` resolves domains once on the host, opens DNS and warns; default is the built-in gate | `--dry-run` (the `HTTP(S)_PROXY` args) |
|
||||||
|
| host-loopback / `100.64.0.1` | `build_argv()`'s `--network=pasta:--map-host-loopback,${gate_addr}` and the `NO_PROXY` defaults | `docs/networking.md`'s measurement table |
|
||||||
|
| "is my machine able to do this" | `cmd_doctor()`, `tests/spike_network.sh` | `ai-sandbox doctor --deep` |
|
||||||
|
|
||||||
|
## Filesystem, mounts, the working directory
|
||||||
|
|
||||||
|
| question | read |
|
||||||
|
|---|---|
|
||||||
|
| why the project is at `/project` | `resolve_workdir()` and `mirror_block_of()` — the deny list is what the image or the sandbox owns, and `/tmp` is a measured case (the tmpfs covers a bind of the same path). `workdir_note=` in `--print-policy` gives the reason |
|
||||||
|
| what is mounted, rw or ro | `build_argv()`: the cwd, `/run/aisb:ro` (session policy), the home volume or tmpfs, the `.agents` share, then user `--mount`s |
|
||||||
|
| `--mount` grammar and defaults | `mount_dest()` — `SRC[:DEST][:ro\|rw]`, default `DEST=/mnt/<basename>`; the option must be `ro` or `rw`; the source must exist |
|
||||||
|
| skills sharing | `agents_src_of()`, `agents_dest_taken()`, the `.agents` block in `build_argv()`. Read-only, no override; a hand-written `--mount` on the same destination wins and the share is skipped with a log line |
|
||||||
|
| file ownership written by the agent | `--userns keep-id:uid=…,gid=…` in `build_argv()` (files land owned by *you*), checked by `doctor` |
|
||||||
|
| SELinux labels | `set_selinux()`, `POL[selinux]`, `AISB_SELINUX` |
|
||||||
|
|
||||||
|
## Environment and secrets
|
||||||
|
|
||||||
|
| question | read |
|
||||||
|
|---|---|
|
||||||
|
| what is inherited | `AISB_IMPLICIT_ENV` (`TERM LANG LC_ALL LC_CTYPE TZ`) and the explicit `HOME`/`AISB`/`AISB_SESSION` in `build_argv()` |
|
||||||
|
| how a value reaches the container | `build_env_file()` — a `0600` file, `NAME`, `NAME=VALUE` and `@file` forms; unset `--env NAME` **dies** on a real run and reports `env_missing=` in preview |
|
||||||
|
| can a secret leak through output | `print_argv()` (redacts the env file), `print_policy()` (names only), `log_session()` (net, counts, rc, command). `tests/unit/04_env.sh`, `tests/e2e/12_sandbox.sh` |
|
||||||
|
| what lands on disk per session | `session_init()` / `teardown()`: `$AISB_STATE_DIR/sessions/<id>` (`chmod 700`), removed unless `--keep` |
|
||||||
|
|
||||||
|
## The pi bridge and thinking policy
|
||||||
|
|
||||||
|
| question | read |
|
||||||
|
|---|---|
|
||||||
|
| what is copied vs rewritten | `pi_config_bridge()` — `apiKey` → `"$VAR"`, `!command` values dropped and reported, host paths dropped and reported, `auth.json` and `models-store.json` never touched |
|
||||||
|
| why `settings.json` behaves oddly | the per-key merge in the entrypoint's seeding block, and `.aisb-settings.json.wrote` — a key you edit in the sandbox stays yours; keys you never touched follow the host |
|
||||||
|
| when the run is refused for a credential | `pi_config_bridge()` + `cmd_doctor()`: unset **or empty** token variable → refused. `--pi-token-env NAME`, `--no-pi-token-env`, `--no-pi-config` |
|
||||||
|
| "the model endpoint is not in the allowlist" warning | `pi_egress_hint()`, `pi_provider_hosts_of()` |
|
||||||
|
| thinking level | `resolve_opts()` (validation of `off…max\|host`) and the seeding block: `AISB_PI_THINKING` is written over the merged settings every run; pi-only; `--no-pi-config` declines the policy too |
|
||||||
|
|
||||||
|
## Image, pinning, supply chain
|
||||||
|
|
||||||
|
| question | read |
|
||||||
|
|---|---|
|
||||||
|
| what is in the image | `containerfile()` (git curl jq build tools python3 Node pi), `gate_containerfile()` (squid from the same base) |
|
||||||
|
| why the tag is what it is | `image_hash()` (the policy, including the base digest, Node and pi versions) and `image_ref()`; `--install` changes it, so variants coexist |
|
||||||
|
| digest pinning and freshness | `base_pin_digest()`, `base_digest_online()`, `base_age_days()`, `base_ref_of()`, `cmd_update()`; `base_ttl_days`, `base_auto_update`, `AISB_BASE_PULL_FALLBACK`, `AISB_SKOPEO`. Preview modes resolve **cache-only** — that is why `--dry-run` never touches the network |
|
||||||
|
| "what version of squid filtered that" | the `aisb.*` image labels and `/etc/aisb/manifest.txt` inside the image (`image_hash()`/`containerfile()` write them) |
|
||||||
|
| rollback | `cmd_update()` keeps the previous image and prints the `podman rmi` for it |
|
||||||
|
| stale home | `ensure_home_volume()`, `cmd_clean()`'s `--volumes[=GLOB]` |
|
||||||
|
|
||||||
|
## The pipeline driver (`bin/ai-sandbox-autophase`)
|
||||||
|
|
||||||
|
| question | read |
|
||||||
|
|---|---|
|
||||||
|
| where does my launcher come from | `ap_resolve_launcher()`, `ap_probe_rc()` (sources an rc file in a throwaway `bash -ic` and returns the *definition*; it never calls it), `ap_rc_list()`, `AISB_AP_RC_FILES` |
|
||||||
|
| how the child command is built | `ap_build_runner()` / `ap_build_run()` — `printf %q` per argument; `--sandbox-args` defaults `--no-tty --no-interactive`; the prompt is one argument that may contain quotes, newlines and `$` |
|
||||||
|
| what it shadows from the phase library | `ap_install_overrides()`: it first requires the library to provide `find_root next_unit phase_entries phase_next_unit unit_phase is_phase_end count_units sweep_finished_phases execute_unit unit_report notify_task commit_phase push_phase` (plus `first_prompt`/`fix_prompt`, kept as `ap_lib_*`), then shadows `pi`, `first_prompt`, `fix_prompt`, `run_validation`, `push_phase` — and nothing else. Order matters: the launcher resolves *before* `pi()` exists, or a launcher named `pi` would resolve to the shim |
|
||||||
|
| why a push was refused | `ap_git_fingerprint()`, `ap_git_guard()`, `ap_git_env()`, `ap_push_pending()`; `--trust-git-changes` is the (loud) override |
|
||||||
|
| redaction | `ap_redact()` — literal `--env NAME=value` and credentials inside remote URLs |
|
||||||
|
| what runs where | `ap_preflight()`, `ap_gate_preview()` (`--validate-in sandbox\|host`), `ap_run_pipeline()`, `ap_status()` |
|
||||||
|
| the contract without the skill installed | `tests/unit/10_autophase.sh` and `tests/fixtures/phase-lib/` |
|
||||||
|
|
||||||
|
## Vocabulary
|
||||||
|
|
||||||
|
* **gate** — the per-session squid container, `--network=host`, bound to the host loopback on a free
|
||||||
|
port ≥ `gate_port`, run as the `proxy` user with `--cap-drop=ALL`, destroyed with the session.
|
||||||
|
`gate up` is the explicit long-lived exception.
|
||||||
|
* **ruleset** — the `inet aisb` nft table installed inside the container's namespace: output
|
||||||
|
`policy drop` with room for loopback, established/related, ICMP, the direct IP entries, the gate's
|
||||||
|
address:port, and DNS only in `--no-gate` mode. Input `policy drop` too, so nothing is published in.
|
||||||
|
* **`POL[...]` / `P_*` / `OPT_*` / `CFG_*`** — resolved policy / resolved lists / raw CLI flags /
|
||||||
|
config-file values. Reading raw env vars elsewhere is the bug pattern; a helper called as
|
||||||
|
`X="$(helper)"` runs in a subshell, so any `POL[..]` it sets is discarded.
|
||||||
|
* **fail closed** — no allowlist in `allow` mode, missing policy file (78), uninstallable ruleset
|
||||||
|
(77), unset `--env NAME`, unset-or-empty bridged token: all refusals, never degradations.
|
||||||
|
* **escape hatch** — `--allow-unenforced`, `--insecure-keep-root`, `--net full`, `--mount`,
|
||||||
|
`extra_args`, `AISB_EXTRA_ARGS`. Named to be uncomfortable; nothing uses them implicitly.
|
||||||
|
|
||||||
|
## FAQ (verify the version before quoting)
|
||||||
|
|
||||||
|
| question | answer |
|
||||||
|
|---|---|
|
||||||
|
| `--print-policy` says "could not create the home cache volume"? | There is no usable podman (missing, or not rootless, or no `/etc/subuid` range) — `--print-policy` ensures the `aisb-home` volume exists, unlike `--dry-run`, which is the fully side-effect-free preview. Run `ai-sandbox --dry-run` to see the policy and `ai-sandbox doctor` for the host. |
|
||||||
|
| Why exit 77? | The ruleset could not be installed, so the sandbox refused to run unfiltered. `ai-sandbox doctor`; check `podman info \| grep -i rootless` and `/etc/subuid`. Debug with `--allow-unenforced` only to see the error, not to ship it. |
|
||||||
|
| Why "no egress allowlist configured"? | `allow` mode with nothing in it is a hard error. `--allow`, `.ai-sandbox/allow`, or `--net none`/`--net full` if you mean it. |
|
||||||
|
| Can it read `~/.ssh`? | No — that path is not in the mount namespace unless you mounted it. Threat model #1 is what you *do* mount and allow. |
|
||||||
|
| Can it rewrite my skills? | No. `~/.agents` is read-only and there is no flag; but its contents are *readable*, so treat the shared tree as published to the agent. |
|
||||||
|
| Why is my project at `/project`? | Mirroring refused because the host path would bury a path the image or sandbox owns; `workdir_note=` says which, `--workdir` chooses. |
|
||||||
|
| `npm ci` works but a package fails | That ecosystem needs another host (python: `files.pythonhosted.org`; rust: `static.crates.io`/`index.crates.io`; go: `sum.golang.org`). Or the package fetched from an allowlisted host — allowing a domain is not a security review. |
|
||||||
|
| How do I let it push? | You don't, from inside. `--allow github.com` + `--env GH_TOKEN` or `--mount ~/.ssh:ro` does it, and the threat model explains the price. For pipelines, run `ai-sandbox-autophase`, which pushes on the host. |
|
||||||
|
| How do I see what the gate allowed? | `ai-sandbox gate logs` (and `gate status`, `gate down`). Don't put secrets in URLs: the gate sees what flows through it. |
|
||||||
|
| A stale container home after a rebuild? | It is the `aisb-home` volume. `ai-sandbox clean --volumes[=GLOB]`, or `--ephemeral-home` per run. |
|
||||||
|
| How do I refresh the base? | `ai-sandbox update --check` then `ai-sandbox update` (or `build --refresh-base`). TTL re-resolves a digest, it never downloads on a preview. |
|
||||||
|
| Do `--dry-run`/`--print-*` touch the network? | No — that determinism is deliberate. `inspect` is the one that asks the machine now. |
|
||||||
|
| Is the container root? | It starts root with `CAP_NET_ADMIN` just long enough to install the ruleset, then `setpriv` to uid 1000 with no capabilities and `no-new-privileges`. `--insecure-keep-root` is the opposite. |
|
||||||
|
| What is NOT protected? | `docs/threat-model.md`, and answer with it: allowlisted destinations, kernel/runtime escapes, anything you mounted, the cached home volume, DNS in `--no-gate` mode, the fact that a host-side push pushes what the agent wrote. |
|
||||||
Executable
+75
@@ -0,0 +1,75 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
# locate.sh -- where the ground truth for an ai-sandbox question lives on THIS machine.
|
||||||
|
#
|
||||||
|
# Read-only, prints no secrets, starts nothing. Answers questions about ai-sandbox from the
|
||||||
|
# program's own text and its docs, never from memory -- so first find them.
|
||||||
|
#
|
||||||
|
# bash locate.sh
|
||||||
|
|
||||||
|
set -uo pipefail
|
||||||
|
|
||||||
|
section() { printf '\n== %s\n' "$1"; }
|
||||||
|
note() { printf ' %s\n' "$1"; }
|
||||||
|
found() { printf ' [x] %s\n' "$1"; }
|
||||||
|
warn() { printf ' [!] %s\n' "$1"; }
|
||||||
|
|
||||||
|
BIN="$(command -v ai-sandbox 2>/dev/null || true)"
|
||||||
|
[[ -n "$BIN" ]] || BIN="$(command -v ai-sandbox-autophase 2>/dev/null || true)"
|
||||||
|
|
||||||
|
section "the program (the authority on flags and behaviour)"
|
||||||
|
if [[ -n "$BIN" ]]; then
|
||||||
|
real="$(readlink -f "$BIN" 2>/dev/null || printf '%s' "$BIN")"
|
||||||
|
found "$real"
|
||||||
|
note "version: $("$BIN" version 2>/dev/null || printf 'unknown -- older than the version subcommand')"
|
||||||
|
note "flags for this exact build: $BIN --help"
|
||||||
|
else
|
||||||
|
warn "ai-sandbox is not on PATH -- answer from the repository instead, and say so"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# A candidate is the script itself, or a repo holding it (bin/ai-sandbox with README.md beside).
|
||||||
|
SCRIPT=""
|
||||||
|
[[ -n "$BIN" ]] && SCRIPT="$(readlink -f "$BIN" 2>/dev/null || printf '%s' "$BIN")"
|
||||||
|
|
||||||
|
candidates=()
|
||||||
|
[[ -n "${AISB_REPO:-}" ]] && candidates+=("$AISB_REPO")
|
||||||
|
[[ -n "${SCRIPT:-}" ]] && candidates+=("$(dirname "$(dirname "$SCRIPT")")")
|
||||||
|
candidates+=("$PWD" "$(git rev-parse --show-toplevel 2>/dev/null || true)")
|
||||||
|
|
||||||
|
REPO=""
|
||||||
|
for c in ${candidates[@]+"${candidates[@]}"}; do
|
||||||
|
[[ -n "$c" && -d "$c" ]] || continue
|
||||||
|
if [[ -f "$c/bin/ai-sandbox" && -f "$c/docs/threat-model.md" ]]; then REPO="$c"; break; fi
|
||||||
|
done
|
||||||
|
|
||||||
|
section "the source tree (the authority on why)"
|
||||||
|
if [[ -n "$REPO" ]]; then
|
||||||
|
found "$REPO"
|
||||||
|
for f in README.md AGENTS.md docs/networking.md docs/threat-model.md docs/recipes.md bin/ai-sandbox bin/ai-sandbox-autophase; do
|
||||||
|
[[ -f "$REPO/$f" ]] && note "$(printf '%-32s %s lines' "$f" "$(wc -l < "$REPO/$f")")"
|
||||||
|
done
|
||||||
|
[[ -d "$REPO/tests" ]] && note "tests/ -- the executable spec: unit/ needs no containers, e2e/ runs real ones"
|
||||||
|
[[ -z "$BIN" ]] && note "not installed, but this tree runs: $REPO/bin/ai-sandbox --help"
|
||||||
|
note "if the installed script and this tree differ, say which one you read"
|
||||||
|
else
|
||||||
|
note "no repository found (tried \$AISB_REPO, the installed script's parent, \$PWD, the git root)"
|
||||||
|
note "the installed script alone answers most questions: it is one file, and it generates"
|
||||||
|
note "the Containerfile, the entrypoint and the squid config from itself"
|
||||||
|
fi
|
||||||
|
|
||||||
|
section "read the machine, or read the script"
|
||||||
|
note "safe, deterministic, no build / container / state / registry:"
|
||||||
|
note " ai-sandbox --help every flag, this version"
|
||||||
|
note " ai-sandbox version"
|
||||||
|
note " ai-sandbox --dry-run the exact podman invocation, secret values redacted"
|
||||||
|
note " ai-sandbox --print-policy effective policy as key=value -- but it also ensures the"
|
||||||
|
note " home volume exists, so it needs podman on the host"
|
||||||
|
note " ai-sandbox --print-entrypoint the enforcement script baked into the image"
|
||||||
|
note " ai-sandbox --print-containerfile the generated Containerfile"
|
||||||
|
note "asks the machine now (may reach the registry, starts nothing): ai-sandbox inspect"
|
||||||
|
note "touches the host: doctor [--deep], build, update, gate up, clean, and any real run"
|
||||||
|
|
||||||
|
section "state a run leaves behind"
|
||||||
|
note "config: ${AISB_CONFIG_DIR:-$HOME/.config/ai-sandbox}/{config,allow}"
|
||||||
|
note "state: ${AISB_STATE_DIR:-$HOME/.local/state/ai-sandbox}/log (every run, no secret values)"
|
||||||
|
note "cache: ${AISB_CACHE_DIR:-$HOME/.cache/ai-sandbox}/base/ (the recorded base digests)"
|
||||||
|
note "repo: ./.ai-sandbox/{config,allow}"
|
||||||
@@ -0,0 +1,223 @@
|
|||||||
|
---
|
||||||
|
name: right-sandbox
|
||||||
|
description: Analyzes a project directory and writes that project's ai-sandbox policy — .ai-sandbox/allow plus .ai-sandbox/config (egress allowlist, environment variable names, bind mounts, working directory, resource limits, harness, extra image packages, access to services on the host) — so that a plain `ai-sandbox` run in the directory is the correct, reviewable invocation. Use when the user asks to set up, configure, write, fix, review or tighten ai-sandbox or the sandbox for a project, wants a .ai-sandbox config committed with the code, or asks why a sandboxed agent cannot reach a package registry, a database, a localhost port or its model gateway. Writes policy files only — never builds, never starts a container, never puts a credential value in a file.
|
||||||
|
---
|
||||||
|
|
||||||
|
# right-sandbox
|
||||||
|
|
||||||
|
Produce the two files ai-sandbox reads from a project, and nothing else:
|
||||||
|
|
||||||
|
| file | contents | committed |
|
||||||
|
|---|---|---|
|
||||||
|
| `.ai-sandbox/allow` | one egress target per line, `#` comments ok | yes — the policy gets reviewed with the code |
|
||||||
|
| `.ai-sandbox/config` | `key = value`: net, harness, limits, mounts, env names, image | yes |
|
||||||
|
| `.ai-sandbox/env` | optional `NAME=VALUE`, mode `600` | **never** — gitignore it |
|
||||||
|
|
||||||
|
`load_config()` reads `./.ai-sandbox/{config,allow}` (after `~/.config/ai-sandbox/{config,allow}`)
|
||||||
|
and nothing else, so do not invent `sandbox.yaml`, `local`, `env.json` or a `phases/` directory in
|
||||||
|
there — a file nobody reads is a policy nobody has.
|
||||||
|
|
||||||
|
Precedence for every key: built-in default < user config < repo config < `AISB_*` env < CLI flag.
|
||||||
|
The repeatable keys (`allow`, `env`, `mount`, `install`, `label`) **accumulate** across all five
|
||||||
|
sources rather than replacing, so a repo config adds to the user's, it does not silence it.
|
||||||
|
|
||||||
|
## What makes a config right
|
||||||
|
|
||||||
|
1. **Names, never values.** Both committed files end up in the repository, in `--print-policy` and
|
||||||
|
in a reviewer's diff. Credentials live in the environment or in `.ai-sandbox/env` (`chmod 600`,
|
||||||
|
gitignored); the config says `env = AI_API_TOKEN`. A literal `NAME=VALUE` is only for things
|
||||||
|
that are not secrets, e.g. `env = DATABASE_URL=postgresql://dev@100.64.0.1:5432/app`.
|
||||||
|
2. **Every key and flag must be real.** An unknown config key is warned about and ignored — a typo
|
||||||
|
is a silently missing policy, which is worse than an error. The authority is the installed
|
||||||
|
program: `ai-sandbox --help`, plus `cfg_read_kv()`'s key list in the script.
|
||||||
|
`references/settings-map.md` holds the list as of writing — check it, do not trust it.
|
||||||
|
Known trap: `project_dest` is accepted by the parser and read by nothing; the key is `workdir`.
|
||||||
|
3. **The git remote stays out.** No `github.com`, `gitlab.com`, `bitbucket.org` or ssh host in
|
||||||
|
`allow` unless the user asks after hearing the cost: an allowlisted remote plus a token or a
|
||||||
|
mounted `~/.ssh` lets a prompt-injected agent ship code nobody reviewed (threat model #1).
|
||||||
|
`git status`, `diff`, `log`, `blame` all work without it, and `ai-sandbox-autophase` commits and
|
||||||
|
pushes on the host precisely so that this line can stay out. If a dependency genuinely has to be
|
||||||
|
fetched over a git host, say which dependency in a comment above the line and prefer a
|
||||||
|
read-only, short-lived token.
|
||||||
|
4. **Escape hatches never go in a committed config**: `net = full`, `extra_args`,
|
||||||
|
`--allow-unenforced`, `--insecure-keep-root`. They are per-run decisions named to be
|
||||||
|
uncomfortable, and a repo file outlives the run that justified it. A run refusing to start
|
||||||
|
(exit 77) is the policy working — debug the host, do not route around it.
|
||||||
|
5. **Least mount.** The cwd is already mounted read-write at its host path, and `~/.agents` is
|
||||||
|
shared read-only with no flag to change it. Never propose a writable skills mount: a sandbox
|
||||||
|
that can write a `SKILL.md` has written an instruction the user follows later on the host.
|
||||||
|
Every extra `mount` line needs a one-line reason in the file.
|
||||||
|
6. **Verify before reporting success** (§5). "It should work" is not an acceptable result for a
|
||||||
|
security policy; `--print-policy` and `--dry-run` answer without building or starting anything.
|
||||||
|
|
||||||
|
## 1. Survey the project
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash scripts/survey.sh [project-dir] # default: $PWD; resolve scripts/ against this skill's directory
|
||||||
|
```
|
||||||
|
|
||||||
|
It is read-only and prints no secret values — variable *names*, remote *hosts*, registry *hosts*
|
||||||
|
and service *ports*. Read its output, then read the files it names: the lockfiles, the compose
|
||||||
|
file, `.env.example`, the dev-server config, CI, and the Makefile or task runner. Prefer evidence
|
||||||
|
over inference: a `pyproject.toml` with an `[[tool.uv.index]]` is a private index, an empty
|
||||||
|
`node_modules` tells you nothing.
|
||||||
|
|
||||||
|
Also read what already exists — `.ai-sandbox/config`, `.ai-sandbox/allow`, the user's
|
||||||
|
`~/.config/ai-sandbox/{config,allow}` — and extend it rather than replacing a decision the user
|
||||||
|
made deliberately.
|
||||||
|
|
||||||
|
## 2. Decide each setting from evidence
|
||||||
|
|
||||||
|
| need | evidence | setting |
|
||||||
|
|---|---|---|
|
||||||
|
| package installs | lockfiles (`pnpm-lock.yaml`, `uv.lock`, `Cargo.lock`, `go.sum`, `Gemfile.lock`, `pom.xml`…) | `allow` entries for the registries that ecosystem really contacts — see the table in `references/settings-map.md` |
|
||||||
|
| model gateway | `~/.pi/agent/models.json` `baseUrl` host, or the base URL the user's harness is configured with | `allow = <gateway host>`; without it a bridged pi starts and cannot answer |
|
||||||
|
| a database / queue / cache | `docker-compose*.yml` published ports, `.env` URLs, `DATABASE_URL` | `allow = 100.64.0.1:<published port>` + an env var that points the app at `100.64.0.1` — see `references/port-and-loopback.md` |
|
||||||
|
| a non-HTTP backend | pinned host:port (a LAN inference box, an internal API) | `allow = <ip or cidr>:<port>` (IP/CIDR become netfilter rules; domains go through the gate) |
|
||||||
|
| credential the harness needs | `.env.example`, CI `secrets.*`, `--env NAME` in the user's launcher | `env = NAME` (name only), and list what the user must export |
|
||||||
|
| reference material / sibling repo | imports or docs that read `../something` | `mount = ../something:/something:ro` |
|
||||||
|
| push over ssh | `~/.ssh` and an `ssh://` remote | do **not** add by default; rule 3 |
|
||||||
|
| a tool the run needs that the image lacks | build logs, `apt-get` in the project's Dockerfile, `rg`, `jq`, a DB client, `ffmpeg` | `install = <apt package>` (each distinct set gets its own cached image tag). Decide it **here**: inside, the harness is uid 1000 with no root and no package manager, so `apt-get` is not something it can do later |
|
||||||
|
| heavy build / flaky cap | repo size, test suite runtime, the user's machine | `cpus`, `memory`, `pids`, `tmpfs_size` |
|
||||||
|
| harness that is not pi | `.claude/`, `codex` config, the user's habit | `harness = pi \| codex \| claude \| none \| "<your command>"` |
|
||||||
|
| paths must look like the host's | a harness that titles by cwd; logs the user pastes | leave `workdir = auto`; set it only when the host path buries an image path |
|
||||||
|
| project-specific skills/prompts | a project `.agents/` | nothing — it arrives with the project mount |
|
||||||
|
| untrusted-code review | the user says so | `net = none`, `agents = 0`, `home_cache = 0`, `read-only` on the CLI, not in the file |
|
||||||
|
|
||||||
|
Two decisions the tool already makes that you should not repeat in the file: the thinking level is
|
||||||
|
`xhigh` policy for a bridged pi, and the pi config bridge is on with the credential by environment
|
||||||
|
reference. Only write `thinking` or `pi_token_env` when the project genuinely differs, with a
|
||||||
|
comment saying why.
|
||||||
|
|
||||||
|
## 3. Write the files
|
||||||
|
|
||||||
|
`.ai-sandbox/allow` — one target per line, grouped and commented, because this file is the diff a
|
||||||
|
human reviews:
|
||||||
|
|
||||||
|
```
|
||||||
|
# model gateway -- without it the sandboxed harness cannot answer
|
||||||
|
gateway.example.com
|
||||||
|
|
||||||
|
# dependencies
|
||||||
|
registry.npmjs.org
|
||||||
|
nodejs.org # node-gyp / prebuild downloads
|
||||||
|
|
||||||
|
# services on this machine, reached through the mapped loopback address (§ports)
|
||||||
|
100.64.0.1:5432 # postgres, `docker compose up db`
|
||||||
|
```
|
||||||
|
|
||||||
|
`.ai-sandbox/config` — only the keys this project needs; a comment per non-obvious one:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
# ai-sandbox policy for <project>. Committed on purpose: review it like code.
|
||||||
|
# Values belong in .ai-sandbox/env (0600, gitignored) or the environment, never here.
|
||||||
|
|
||||||
|
net = allow
|
||||||
|
harness = pi
|
||||||
|
|
||||||
|
# the toolchain needs a bit more than the default 4 cpu / 4g
|
||||||
|
cpus = 8
|
||||||
|
memory = 8g
|
||||||
|
|
||||||
|
# design docs live beside the repo
|
||||||
|
mount = ../specs:/specs:ro
|
||||||
|
|
||||||
|
# names only; ai-sandbox passes them by name through a 0600 file
|
||||||
|
env = AI_API_TOKEN
|
||||||
|
env = @./.ai-sandbox/env
|
||||||
|
|
||||||
|
# apt packages the test suite needs that the image lacks
|
||||||
|
install = postgresql-client
|
||||||
|
```
|
||||||
|
|
||||||
|
`env = @path` is the config-file form of `--env-file` (`--env-file F` becomes the entry `@F`), so
|
||||||
|
it works today and fails closed if the file is missing — note in the file that a newcomer must
|
||||||
|
`cp .ai-sandbox/env.example .ai-sandbox/env && chmod 600` it. If you create `env.example`, put
|
||||||
|
names with dummy values in it and add `.ai-sandbox/env` to `.gitignore` (never overwrite an
|
||||||
|
existing ignore file's rules — append).
|
||||||
|
|
||||||
|
Never write `.ai-sandbox/env` yourself with real values: write the example, then tell the user what
|
||||||
|
to put in it.
|
||||||
|
|
||||||
|
## 4. Egress in one paragraph (get the shape right)
|
||||||
|
|
||||||
|
* A **domain** entry is matched by the gate at CONNECT time, including subdomains. Its `:port` does
|
||||||
|
not add a netfilter rule and the gate only relays **80, 443, 8443** (`Safe_ports`/`SSL_ports` in
|
||||||
|
the generated squid config), so `--allow host:8080` will not do what it looks like.
|
||||||
|
* An **IP, CIDR or `[ipv6]`** entry becomes a direct netfilter rule, default ports 80,443 unless you
|
||||||
|
write `:port` — this is how non-HTTP traffic (postgres, redis, a LAN model box) is allowed.
|
||||||
|
* `--no-gate` skips the proxy: domains are resolved once, on the host, at start and **DNS is
|
||||||
|
opened**; weaker for CDNs and rotating IPs. `--proxy host:port` uses a proxy you already run
|
||||||
|
(default port 3128). Neither belongs in a committed config without a comment justifying it.
|
||||||
|
* An empty allowlist in `allow` mode is a hard error. Never "fix" that by widening net.
|
||||||
|
|
||||||
|
## 5. Verify (no builds, no containers, no network)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <project>
|
||||||
|
ai-sandbox --dry-run # the exact podman invocation + the # egress / # env header lines;
|
||||||
|
# works with no podman and leaves no session directory behind
|
||||||
|
ai-sandbox --print-policy # net=, allow=, gate_domains=, direct=, env_names=, env_missing=,
|
||||||
|
# mounts=, workdir=, agents=, thinking= -- as key=value lines
|
||||||
|
```
|
||||||
|
|
||||||
|
Start with `--dry-run`: it is the one preview path with no side effects at all. `--print-policy`
|
||||||
|
gives the friendlier key=value form but also ensures the home-cache volume exists, so it needs
|
||||||
|
podman present — treat a failure there as "this machine has no podman", not as a policy problem.
|
||||||
|
|
||||||
|
Check, in this order, and fix the files instead of explaining the output:
|
||||||
|
|
||||||
|
1. no `warning: --env NAME requested but not set` for a name nobody intended (unset names are fine
|
||||||
|
to ship — say so in the report — but each must be a deliberate line, not a typo).
|
||||||
|
2. every allow entry appears in `domains=[…]` or `direct=[…]` (or `gate_domains=`/`direct=` under
|
||||||
|
`--print-policy`) — an entry in neither is a parse problem.
|
||||||
|
3. `workdir=` is the host path, not `/project`, unless the fallback was intended (`workdir_note=`
|
||||||
|
says why).
|
||||||
|
4. `mounts=` and `agents=` are what you wrote and nothing more.
|
||||||
|
5. the dry run shows `--network pasta:--map-host-loopback,100.64.0.1`, `--cap-drop=ALL`,
|
||||||
|
`--security-opt no-new-privileges`, `--userns keep-id:…` and no secret values.
|
||||||
|
6. `--print-policy | grep -i` for each credential name from §1: the *name* may appear, a *value*
|
||||||
|
must not.
|
||||||
|
|
||||||
|
Then, with the user watching (this builds the image the first time and starts a container):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ai-sandbox --shell # egress, mounts, env present
|
||||||
|
ai-sandbox --net none -- make test # the offline half of the toolchain
|
||||||
|
ai-sandbox doctor # host readiness
|
||||||
|
```
|
||||||
|
|
||||||
|
Probe the two or three endpoints the project actually needs from inside (`curl -sS -m 5 -o
|
||||||
|
/dev/null -w '%{http_code}\n' https://registry.npmjs.org/`) rather than assuming an allowlist entry
|
||||||
|
means a working toolchain.
|
||||||
|
|
||||||
|
## 6. Report
|
||||||
|
|
||||||
|
Finish with exactly these five points, so the user can act without reading the files:
|
||||||
|
|
||||||
|
1. **Files written** — paths, plus the `.gitignore` change if any.
|
||||||
|
2. **`cd <dir> && ai-sandbox`** is now the invocation (and the alias note if they use one).
|
||||||
|
3. **What they must export** first (`env =` names that are unset), and where values may go.
|
||||||
|
4. **What is deliberately not allowed** — the git remote first, then anything you declined to open
|
||||||
|
because the honest answer was "not without weakening the sandbox" (inbound port publishing is
|
||||||
|
usually on this list).
|
||||||
|
5. **What you verified and how** — the two preview commands and any live probe, with results.
|
||||||
|
|
||||||
|
## Ports, localhost, "the app must be reachable"
|
||||||
|
|
||||||
|
Read `references/port-and-loopback.md` before promising anything about ports. Short version: a
|
||||||
|
sandboxed process reaches *services on your machine* through the mapped loopback address
|
||||||
|
`100.64.0.1`, which needs an `allow` entry **and** a client that does not send that request to the
|
||||||
|
egress proxy; and a port the sandbox listens on is **not** reachable from the host in `--net allow`
|
||||||
|
mode, because the generated ruleset's input chain is `policy drop`. Verify on the machine rather
|
||||||
|
than repeating that from memory — the file has the probes.
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
* `references/settings-map.md` — every accepted config key and flag, defaults, per-ecosystem
|
||||||
|
allowlists, the survey→policy cheat sheet.
|
||||||
|
* `references/port-and-loopback.md` — inbound vs outbound, `100.64.0.1`, the gate's port limits,
|
||||||
|
probes, the three workable dev-server patterns.
|
||||||
|
* `scripts/survey.sh` — the read-only evidence gatherer (prints no values).
|
||||||
|
* The tool's own docs, if this repo is present: `README.md`, `docs/networking.md` (measurements),
|
||||||
|
`docs/threat-model.md` (what is *not* protected), `docs/recipes.md` (invocations).
|
||||||
@@ -0,0 +1,119 @@
|
|||||||
|
# Ports and loopback
|
||||||
|
|
||||||
|
Two separate problems wear the same name. Get the direction right before touching a config.
|
||||||
|
|
||||||
|
| | what it is | possible in `--net allow`? |
|
||||||
|
|---|---|---|
|
||||||
|
| **outbound** | the sandboxed process reaches a service running on your machine (dev postgres, redis, a mock API, a local model server) | **yes** — one allow entry, sometimes plus a proxy bypass |
|
||||||
|
| **inbound** | your browser on the host reaches a server the sandbox started | **no** — the generated ruleset drops it; three workarounds below |
|
||||||
|
|
||||||
|
Container-to-container is a third case, already measured on the reference host: two containers on a
|
||||||
|
shared user-defined network **cannot reach each other**, so do not design a sidecar proxy, a
|
||||||
|
service-mesh sandbox or a "sandbox plus its own database container" topology. The database runs on
|
||||||
|
the host (compose) and is reached as in §1.
|
||||||
|
|
||||||
|
## 1. Outbound: a service on your machine
|
||||||
|
|
||||||
|
With `--net allow` the container is started as
|
||||||
|
`--network pasta:--map-host-loopback,<gate_addr>` (`gate_addr`, default `100.64.0.1`). Inside the
|
||||||
|
container, **`100.64.0.1:PORT` lands on the host's `127.0.0.1:PORT`**. `127.0.0.1` inside the
|
||||||
|
container is the container itself and almost never what you meant.
|
||||||
|
|
||||||
|
Two layers have to agree, and this is where every "it still does not work" comes from:
|
||||||
|
|
||||||
|
1. **The ruleset.** Only the gate's port is routable through that address by default. Add:
|
||||||
|
```
|
||||||
|
allow = 100.64.0.1:5432 # postgres published by docker compose on the host
|
||||||
|
```
|
||||||
|
(IP entries become direct netfilter rules — the right shape for a non-HTTP protocol.)
|
||||||
|
2. **The proxy variables.** When a gate is in use, the container gets `HTTP(S)_PROXY`/`ALL_PROXY`
|
||||||
|
and `NO_PROXY=localhost,127.0.0.1,::1`. A client that honours them sends the request to the gate,
|
||||||
|
which allows the destination if it is in the allowlist **and the port is one of 80, 443, 8443**.
|
||||||
|
|
||||||
|
So:
|
||||||
|
|
||||||
|
| the service | what the config needs |
|
||||||
|
|---|---|
|
||||||
|
| postgres, redis, amqp, ssh, a raw socket — anything that ignores proxy variables | `allow = 100.64.0.1:<port>` |
|
||||||
|
| HTTP on 80, 443 or 8443 | `allow = 100.64.0.1:<port>` (the gate relays it) |
|
||||||
|
| HTTP on any other port (3000, 8000, 5173, 9200…) | `allow = 100.64.0.1:<port>` **and** a proxy bypass for that address, and measure which of the two `NO_PROXY` values wins |
|
||||||
|
|
||||||
|
The bypass, and the honest way to confirm it:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
# .ai-sandbox/config -- the dev API on the host is not reachable through the egress gate
|
||||||
|
env = NO_PROXY=100.64.0.1,localhost,127.0.0.1,::1
|
||||||
|
env = no_proxy=100.64.0.1,localhost,127.0.0.1,::1
|
||||||
|
```
|
||||||
|
|
||||||
|
ai-sandbox sets `NO_PROXY` with `--env` *before* the env file, so the interaction between that and
|
||||||
|
an env-file value is podman's flag handling, not ai-sandbox's. Do not reason about it: run
|
||||||
|
`ai-sandbox --dry-run`, look at the order of the flags, and probe for real:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ai-sandbox --allow 100.64.0.1:3000 --shell
|
||||||
|
curl -sS -m 3 -o /dev/null -w '%{http_code}\n' http://100.64.0.1:3000/health
|
||||||
|
env | grep -i -E 'proxy|no_proxy'
|
||||||
|
```
|
||||||
|
|
||||||
|
Then point the app at the mapped address without putting a secret in a committed file — a URL with
|
||||||
|
no password in it is not a secret:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
env = DATABASE_URL=postgresql://dev@100.64.0.1:5432/app_dev
|
||||||
|
```
|
||||||
|
|
||||||
|
If `100.64.0.1` collides with a real network the project must reach, change `gate_addr` (and
|
||||||
|
remember the gate itself is reached at that address too).
|
||||||
|
|
||||||
|
## 2. Inbound: "I want to see the app the agent is building"
|
||||||
|
|
||||||
|
There is **no publish flag** (`--publish`/`-p` are not in `parse_args()`). You can push one through
|
||||||
|
the escape hatch — `extra_args = -p 8000:8000` or `AISB_EXTRA_ARGS="-p 8000:8000"` — and then read
|
||||||
|
the ruleset the entrypoint installs: the `input` chain is `policy drop` with room only for `lo`,
|
||||||
|
`established,related` and a few icmpv6 types, so a fresh inbound connection is dropped inside the
|
||||||
|
container. Confirm on the machine instead of trusting that reading:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
AISB_EXTRA_ARGS="-p 8000:8000" ai-sandbox --shell
|
||||||
|
# inside: python3 -m http.server 8000 &
|
||||||
|
# host: curl -sS -m 3 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected on a stock host in `--net allow`: no answer. If yours answers, that is a fact worth adding
|
||||||
|
to `docs/networking.md` — measure and report it, do not build the workflow on it.
|
||||||
|
|
||||||
|
What to tell the user instead, in order of preference:
|
||||||
|
|
||||||
|
1. **Run the server on the host.** The project mount *is* their disk: the agent edits, the host's
|
||||||
|
`npm run dev` / `runserver` picks it up, the browser hits a normal host port. Nothing is
|
||||||
|
published, nothing is opened, egress stays enforced. This is the answer for 90% of "preview the
|
||||||
|
app" requests.
|
||||||
|
2. **One named preview run**, when the server itself must be the sandboxed process (the agent needs
|
||||||
|
to drive it, seed it, watch its logs):
|
||||||
|
```bash
|
||||||
|
AISB_EXTRA_ARGS="-p 8000:8000" ai-sandbox --net full -- npm run dev
|
||||||
|
```
|
||||||
|
Say out loud what this is: `--net full` means that run has **no egress policy**. It is a
|
||||||
|
preview of a trusted project, not a project setting — which is why it never belongs in
|
||||||
|
`.ai-sandbox/config`.
|
||||||
|
3. **Split the loop**: the agent builds and unit-tests in the sandbox, writes a screenshotable
|
||||||
|
static export or a `make preview` target, and the human runs that target. This keeps the review
|
||||||
|
step where it belongs.
|
||||||
|
|
||||||
|
If the user genuinely needs publish-with-enforcement, the honest answer is that it is not
|
||||||
|
implemented: a `--publish PORT` would need an `input` accept rule per port in `gen_rules()`, the
|
||||||
|
port list carried in the session policy, and a threat-model line about who may connect. Offer to
|
||||||
|
write it as a change to `bin/ai-sandbox` — as its own phase, with a `tests/e2e` probe — rather than
|
||||||
|
hacking `extra_args` into a committed config and calling it secure.
|
||||||
|
|
||||||
|
## 3. Notes that keep coming up
|
||||||
|
|
||||||
|
* The gate binds the **host's loopback** only, on a free port at or above `gate_port` (18081);
|
||||||
|
`ai-sandbox gate status` and `gate logs` show a long-lived one.
|
||||||
|
* `NO_PROXY` covering `localhost` is correct and must stay — tooling that refuses to proxy the
|
||||||
|
container's own loopback (dev databases, auth servers, vite HMR) breaks otherwise.
|
||||||
|
* `--no-gate` opens DNS inside the container; the mapped loopback address still needs its `allow`
|
||||||
|
line.
|
||||||
|
* `--net none` has no interface at all: neither direction works, which makes it the right mode for
|
||||||
|
`make test` on a toolchain that is already installed.
|
||||||
@@ -0,0 +1,135 @@
|
|||||||
|
# Settings map
|
||||||
|
|
||||||
|
Check this against the installed program before writing a config: `ai-sandbox --help`, and
|
||||||
|
`cfg_read_kv()` / `resolve_opts()` in the script. Where they disagree, the script wins and this
|
||||||
|
file is the bug.
|
||||||
|
|
||||||
|
## Precedence
|
||||||
|
|
||||||
|
```
|
||||||
|
built-in default < ~/.config/ai-sandbox/{config,allow} < ./.ai-sandbox/{config,allow}
|
||||||
|
< AISB_* environment < command-line flag
|
||||||
|
```
|
||||||
|
|
||||||
|
`allow`, `env`, `mount`, `install`, `label` **accumulate** from every source (deduped); every other
|
||||||
|
key replaces. So a repo file cannot revoke a user-wide `allow` line — say so if the user expects a
|
||||||
|
repo config to tighten their own machine.
|
||||||
|
|
||||||
|
## The container, for orientation
|
||||||
|
|
||||||
|
Anything named "container" below is inside the sandbox: uid/gid **1000**, the image's own `sandbox`
|
||||||
|
account, its home the value of `HOME` in there (`--userns=keep-id` makes files the agent writes
|
||||||
|
owned by *you* on the host). So `~/.agents` exists on both sides of the wall and they are different
|
||||||
|
directories — the host one is bind-mounted read-only onto the container one at `agents_dest`.
|
||||||
|
`/project` is the image's own directory and the fallback working directory, not the normal one.
|
||||||
|
|
||||||
|
## Config keys (`key = value`, `#` comments)
|
||||||
|
|
||||||
|
| key | default | notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `net` | `allow` | `none` \| `allow` \| `full`. `allow` requires a non-empty allowlist. |
|
||||||
|
| `harness` | `pi` | `pi` \| `codex` \| `claude` \| `none` \| a command line, e.g. `pi --model turbo` |
|
||||||
|
| `workdir` | `auto` | `auto` mirrors the host path; or an absolute path. **`project_dest` is parsed and never read — use `workdir`.** |
|
||||||
|
| `cpus` | `4` | |
|
||||||
|
| `memory` | `4g` | `512m`/`4g` shape |
|
||||||
|
| `pids` | `512` | |
|
||||||
|
| `tmpfs_size` | `1g` | sizes `/tmp` and, with `home_cache = 0`, the container home |
|
||||||
|
| `base_image` | `docker.io/library/ubuntu:24.04` | may itself be `name@sha256:…` |
|
||||||
|
| `node_version` | `22.23.4` | checksum-verified against nodejs.org |
|
||||||
|
| `pi_version` | `1.4.0` | npm package version baked into the image |
|
||||||
|
| `base_ttl_days` | `7` | `0` re-resolve every build, `-1` never |
|
||||||
|
| `base_auto_update` | `1` | `0` keeps the recorded digest offline |
|
||||||
|
| `selinux` | `:z` when `getenforce` exists | `:z`, `:Z` or empty |
|
||||||
|
| `home_cache` | `1` | `0` = throwaway tmpfs home (also `--ephemeral-home`) |
|
||||||
|
| `gate_addr` | `100.64.0.1` | the address that *means* the host's loopback inside the container |
|
||||||
|
| `gate_port` | `18081` | preferred first port; next free is used |
|
||||||
|
| `extra_args` | empty | appended verbatim to `podman run`, word-split. Escape hatch: do not commit it |
|
||||||
|
| `pi_config` | `1` | bridge `~/.pi/agent/{models,settings}.json` with the credential as `$VAR` |
|
||||||
|
| `pi_token_env` | `AI_API_TOKEN` | the variable the bridged config reads |
|
||||||
|
| `pi_token_auto` | `1` | pass that variable automatically when set |
|
||||||
|
| `pi_agent_dir` | `~/.pi/agent` | where to read the host config from |
|
||||||
|
| `thinking` | `xhigh` | `off minimal low medium high xhigh max host`; pi only, re-applied every run |
|
||||||
|
| `agents` | `1` | share `~/.agents` read-only when the directory exists |
|
||||||
|
| `agents_dir` | `~/.agents` | which directory; a project's own `.agents/` needs nothing |
|
||||||
|
| `agents_dest` | the container's `~/.agents` | keep it under the container `$HOME` — that is the only place a harness looks for user-level skills |
|
||||||
|
| `allow` | — | repeatable; same grammar as `--allow` |
|
||||||
|
| `env` | — | repeatable; `NAME`, `NAME=VALUE` (no secret in a committed file), or `@path` = an env file |
|
||||||
|
| `mount` | — | repeatable; `SRC[:DEST][:ro\|rw]`, default `DEST=/mnt/<basename>` |
|
||||||
|
| `install` | — | repeatable; apt packages, each distinct set is its own image tag |
|
||||||
|
| `label` | — | repeatable; `K=V` on the container |
|
||||||
|
|
||||||
|
Anything else warns (`unknown key`) and is ignored.
|
||||||
|
|
||||||
|
## Flags
|
||||||
|
|
||||||
|
```
|
||||||
|
egress --net none|allow|full --allow HOST[:PORT] --allow-file F --proxy HOST:PORT --no-gate
|
||||||
|
files --mount SRC[:DEST][:ro] --no-cwd --workdir DIR|auto --read-only
|
||||||
|
--home-cache --ephemeral-home --agents | --no-agents --agents-dir PATH
|
||||||
|
env --env NAME --env NAME=VALUE --env-file F (F should be 0600)
|
||||||
|
image --base-image REF --install PKG --no-build
|
||||||
|
harness --harness NAME --shell --thinking LEVEL --pi-token-env NAME --no-pi-token-env
|
||||||
|
--no-pi-config
|
||||||
|
limits --cpus N --memory SIZE --pids N --tmpfs-size SIZE
|
||||||
|
run --name NAME --label K=V --keep --interactive | --no-interactive --no-tty
|
||||||
|
preview --dry-run|-n --print-policy --print-entrypoint --print-containerfile
|
||||||
|
hatches --allow-unenforced --insecure-keep-root --strict-args
|
||||||
|
```
|
||||||
|
|
||||||
|
Parsing stops at the first positional or unknown argument, which becomes an argument **to the
|
||||||
|
harness** — that is what makes `alias pi=ai-sandbox` behave like the harness. `--` replaces the
|
||||||
|
command entirely. `--strict-args` makes an unknown flag an error instead (use it in scripts).
|
||||||
|
|
||||||
|
Subcommands: `build [--rebuild] [--gate] [--refresh-base]`, `update [--check]`, `doctor [--deep]`,
|
||||||
|
`gate up|down|status|logs`, `ps`, `clean [--all] [--volumes[=GLOB]]`, `inspect`, `version`.
|
||||||
|
|
||||||
|
Exit status: the command's own code; **77** the egress ruleset could not be installed; **78** the
|
||||||
|
policy file was missing in the container. Both refusals are the sandbox working.
|
||||||
|
|
||||||
|
## Allow-entry grammar
|
||||||
|
|
||||||
|
| entry | effect |
|
||||||
|
|---|---|
|
||||||
|
| `example.com` | gate matches that name and anything below it, at CONNECT time |
|
||||||
|
| `example.com:8443` | same; the port does **not** create a netfilter rule, and the gate only relays 80/443/8443 |
|
||||||
|
| `10.0.0.5:5432` | direct netfilter rule for that host and port — the way to allow non-HTTP |
|
||||||
|
| `10.20.0.0/16` | direct rule for the subnet, default ports 80,443 unless `:port` |
|
||||||
|
| `[fd00::5]:8443` | direct ipv6 rule |
|
||||||
|
| `localhost` | resolves on the host → a direct rule for `127.0.0.1`, i.e. the *container's* loopback. For your machine's services use `100.64.0.1` |
|
||||||
|
|
||||||
|
## Per-ecosystem starting points
|
||||||
|
|
||||||
|
Add only what the project's own lockfiles and build files prove it contacts. Everything left out
|
||||||
|
fails loudly, which is the feature.
|
||||||
|
|
||||||
|
| stack | entries |
|
||||||
|
|---|---|
|
||||||
|
| npm | `registry.npmjs.org` (+ `nodejs.org` and, for prebuilds, `release-assets.githubusercontent.com` — read the git-host warning before adding anything from `github.com`) |
|
||||||
|
| python | `pypi.org`, `files.pythonhosted.org` (the file CDN is separate; both are needed). A private index: whatever host `--index-url`, `PIP_INDEX_URL`, `[[tool.uv.index]]` or `tool.poetry.source` names |
|
||||||
|
| rust | `crates.io`, `static.crates.io`, `index.crates.io` (+ `static.rust-lang.org` if it installs toolchains) |
|
||||||
|
| go | `proxy.golang.org`, `sum.golang.org` (+ the host of a private module path, `allow = <host>` and `GOPRIVATE` in the env) |
|
||||||
|
| ruby | `rubygems.org`, `index.rubygems.org` |
|
||||||
|
| php | `repo.packagist.org`, `api.github.com` (composer metadata; check before allowing) |
|
||||||
|
| jvm | `repo1.maven.org`, `repo.maven.apache.org`, `plugins.gradle.org`, `services.gradle.org`, `dl.google.com` |
|
||||||
|
| dotnet | `api.nuget.org` |
|
||||||
|
| terraform | `registry.terraform.io`, `releases.hashicorp.com` |
|
||||||
|
| playwright / puppeteer | their download hosts (`cdn.playwright.dev`, `storage.googleapis.com`) — or commit the browsers and go `--net none` |
|
||||||
|
| container builds inside the sandbox | `registry-1.docker.io`, `auth.docker.io`, `production.cloudflare.docker.com` |
|
||||||
|
|
||||||
|
## Gotchas worth a comment in the file
|
||||||
|
|
||||||
|
* `--env NAME=VALUE` shows up in `ps`; the name-only and `--env-file` forms do not.
|
||||||
|
* An unset variable named with `--env` **fails the run** (in preview it is reported as
|
||||||
|
`env_missing=` instead) — that fail-closed behaviour is why preview output is worth reading.
|
||||||
|
* The image's home is a named volume (`aisb-home`) that outlives the image: after a rebuild the
|
||||||
|
home may be stale. `ai-sandbox clean --volumes` reclaims unused `aisb-*` volumes.
|
||||||
|
* A project under `/tmp`, `/usr`, `/etc`, `/var`, `/opt`, `/run`, `/home` itself or the container's
|
||||||
|
own home cannot mirror its host path and lands in `/project`, with a line saying so. Do not "fix"
|
||||||
|
that with `--workdir /tmp/...`; the tmpfs covers it.
|
||||||
|
* The host path may not contain `:` at all — podman cannot parse such a mount spec, and
|
||||||
|
ai-sandbox refuses rather than passing the error along.
|
||||||
|
* Nothing is inherited but `TERM LANG LC_ALL LC_CTYPE TZ` (plus `HOME`, set to the container home,
|
||||||
|
`AISB=1`, `AISB_SESSION`). A tool that needs `PATH`, a dotfile or anything else from your real home
|
||||||
|
needs an explicit grant.
|
||||||
|
* `.env` files inside the project are readable by the agent — that is the point of the mount, and
|
||||||
|
it is why the *sandbox* token should be a narrow one.
|
||||||
+231
@@ -0,0 +1,231 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
# survey.sh -- gather the evidence a .ai-sandbox policy needs from a project directory.
|
||||||
|
#
|
||||||
|
# Read-only, and it prints no secret values: variable NAMES, registry HOSTS, service PORTS. A URL
|
||||||
|
# is reduced to its host and any credentials inside one are stripped before anything is printed --
|
||||||
|
# the rule ai-sandbox holds itself to in --dry-run, --print-policy and the session log.
|
||||||
|
#
|
||||||
|
# bash survey.sh [project-dir] # default: $PWD
|
||||||
|
#
|
||||||
|
# It reports what it found and proposes nothing on its own authority: the agent decides, writes the
|
||||||
|
# two files, and verifies them with --print-policy / --dry-run.
|
||||||
|
|
||||||
|
set -uo pipefail
|
||||||
|
|
||||||
|
DIR="${1:-$PWD}"
|
||||||
|
[[ -d "$DIR" ]] || { printf 'not a directory: %s\n' "$DIR" >&2; exit 2; }
|
||||||
|
cd "$DIR" || exit 2
|
||||||
|
|
||||||
|
section() { printf '\n== %s\n' "$1"; }
|
||||||
|
note() { printf ' %s\n' "$1"; }
|
||||||
|
found() { printf ' [x] %s\n' "$1"; }
|
||||||
|
warn() { printf ' [!] %s\n' "$1"; }
|
||||||
|
list() { while IFS= read -r l; do [[ -n "$l" ]] && printf ' %s\n' "$l"; done; }
|
||||||
|
|
||||||
|
# Text in, sorted unique hosts out, with URL credentials gone. Never emits a path or a value.
|
||||||
|
hosts_of() {
|
||||||
|
sed -E -e 's#(://)[^/@[:space:]"'"'"']*@#\1#g' -e 's#^[a-z][a-z0-9+.-]*://##' -e 's#^//##' -e 's#^[A-Za-z0-9._-]+@##' \
|
||||||
|
| grep -oE '^[A-Za-z0-9._*+-]+(:[0-9]{1,5})?' | sort -u || true
|
||||||
|
}
|
||||||
|
|
||||||
|
# Existing files by basename glob, shallow, skipping build and dependency noise.
|
||||||
|
files_matching() {
|
||||||
|
local g
|
||||||
|
for g in "$@"; do
|
||||||
|
find . -maxdepth 3 \( -name node_modules -o -name .git -o -name .venv -o -name venv \
|
||||||
|
-o -name target -o -name dist -o -name build -o -name __pycache__ -o -name vendor \) -prune \
|
||||||
|
-o -name "$g" -print 2>/dev/null
|
||||||
|
done
|
||||||
|
}
|
||||||
|
|
||||||
|
printf 'project survey -- %s\n' "$DIR"
|
||||||
|
note "reads only, writes nothing, prints no secret values"
|
||||||
|
|
||||||
|
# --------------------------------------------------------------------------- the tool
|
||||||
|
section "ai-sandbox on this machine"
|
||||||
|
if command -v ai-sandbox >/dev/null 2>&1; then
|
||||||
|
found "$(ai-sandbox version 2>/dev/null || command -v ai-sandbox)"
|
||||||
|
note "script: $(readlink -f "$(command -v ai-sandbox)")"
|
||||||
|
note "policy: $PWD/.ai-sandbox/{config,allow} user: ${AISB_CONFIG_DIR:-$HOME/.config/ai-sandbox}/{config,allow}"
|
||||||
|
note "the flag and key list for THIS version: ai-sandbox --help"
|
||||||
|
else
|
||||||
|
warn "ai-sandbox is not on PATH -- install it before writing a policy nobody can run"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# --------------------------------------------------------------------------- repository
|
||||||
|
section "repository"
|
||||||
|
remote_hosts=""
|
||||||
|
if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
|
||||||
|
note "branch $(git branch --show-current 2>/dev/null || echo '?'), $(git status --porcelain 2>/dev/null | wc -l) dirty path(s)"
|
||||||
|
remote_hosts="$(git remote -v 2>/dev/null | awk '{print $2}' | hosts_of | cut -d: -f1 | sort -u)"
|
||||||
|
if [[ -n "$remote_hosts" ]]; then
|
||||||
|
printf ' remotes (hosts only):%s\n' "$(printf '%s' "$remote_hosts" | tr '\n' ' ')"
|
||||||
|
note "allowlisting a remote host hands the sandbox the ability to ship what it wrote"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
note "not a git repository"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# --------------------------------------------------------------------------- stacks
|
||||||
|
section "toolchains (manifest -> the endpoints that ecosystem needs)"
|
||||||
|
declare -A STACK=(
|
||||||
|
[package-lock.json]="npm | registry.npmjs.org"
|
||||||
|
[pnpm-lock.yaml]="pnpm | registry.npmjs.org"
|
||||||
|
[yarn.lock]="yarn | registry.npmjs.org"
|
||||||
|
[pyproject.toml]="python | pypi.org files.pythonhosted.org"
|
||||||
|
[requirements.txt]="python | pypi.org files.pythonhosted.org"
|
||||||
|
[poetry.lock]="python/poetry | pypi.org files.pythonhosted.org"
|
||||||
|
[uv.lock]="python/uv | pypi.org files.pythonhosted.org"
|
||||||
|
[Pipfile.lock]="python/pipenv | pypi.org files.pythonhosted.org"
|
||||||
|
[Cargo.lock]="rust | crates.io static.crates.io index.crates.io"
|
||||||
|
[go.sum]="go | proxy.golang.org sum.golang.org"
|
||||||
|
[Gemfile.lock]="ruby | rubygems.org index.rubygems.org"
|
||||||
|
[composer.json]="php | repo.packagist.org"
|
||||||
|
[pom.xml]="maven | repo1.maven.org"
|
||||||
|
[build.gradle]="gradle | repo.maven.apache.org plugins.gradle.org services.gradle.org"
|
||||||
|
[build.gradle.kts]="gradle | repo.maven.apache.org plugins.gradle.org services.gradle.org"
|
||||||
|
[mix.exs]="elixir | hex.pm repo.hex.pm"
|
||||||
|
[deno.json]="deno | deno.land registry.npmjs.org"
|
||||||
|
[*.csproj]="dotnet | api.nuget.org"
|
||||||
|
[*.tf]="terraform | registry.terraform.io releases.hashicorp.com"
|
||||||
|
)
|
||||||
|
stacks=0
|
||||||
|
for f in "${!STACK[@]}"; do
|
||||||
|
hits="$(files_matching "$f")"
|
||||||
|
[[ -n "$hits" ]] || continue
|
||||||
|
found "$(printf '%-26s %s' "${STACK[$f]}" "$(printf '%s\n' "$hits" | head -2 | tr '\n' ' ')")"
|
||||||
|
stacks=$((stacks + 1))
|
||||||
|
done
|
||||||
|
(( stacks )) || note "no recognised manifest within depth 3 -- script tree, docs tree, or an unusual layout"
|
||||||
|
note "also read: $(files_matching Makefile Taskfile.yml Dockerfile 'Dockerfile.*' Justfile package.json pyproject.toml | head -6 | tr '\n' ' ')"
|
||||||
|
|
||||||
|
section "custom registries named in the project's own files"
|
||||||
|
idx="$(grep -rIhoE --include='*.toml' --include='*.txt' --include='*.cfg' --include='*.json' \
|
||||||
|
--include='*.yaml' --include='*.yml' --include='*.npmrc' --include='*.pip.conf' --include='Makefile' \
|
||||||
|
'(--index-url|--extra-index-url|--add-registry|index-url|GOPROXY|npmRegistryServer)[[:space:]]*[=:]?[[:space:]]*"?[^[:space:]#",]+' \
|
||||||
|
. 2>/dev/null \
|
||||||
|
| sed -E 's/^(-{1,2})?[A-Za-z-]*(index-url|add-registry|GOPROXY|npmRegistryServer)[[:space:]]*[=:]?[[:space:]]*"?//' \
|
||||||
|
| hosts_of)"
|
||||||
|
if [[ -n "$idx" ]]; then list <<< "$idx"; note "these decide whether the build works at all"; else note "none found"; fi
|
||||||
|
|
||||||
|
# --------------------------------------------------------------------------- services and ports
|
||||||
|
section "services and ports"
|
||||||
|
compose="$(files_matching 'docker-compose*.yml' 'docker-compose*.yaml' compose.yml compose.yaml)"
|
||||||
|
if [[ -n "$compose" ]]; then
|
||||||
|
for c in $compose; do
|
||||||
|
note "${c#./}:"
|
||||||
|
svc="$(grep -oE '^ [a-zA-Z0-9_.-]+:[[:space:]]*$' "$c" | tr -d ' :' | tr '\n' ' ')"
|
||||||
|
[[ -n "$svc" ]] && printf ' services: %s\n' "$svc"
|
||||||
|
ports="$(grep -oE '[0-9]{1,5}:[0-9]{1,5}' "$c" | sort -u | tr '\n' ' ')"
|
||||||
|
[[ -n "$ports" ]] && printf ' published: %s -> one "allow = 100.64.0.1:<port>" per port you grant\n' "$ports"
|
||||||
|
done
|
||||||
|
else
|
||||||
|
note "no compose file"
|
||||||
|
fi
|
||||||
|
devports="$(grep -rIhoE --include='vite.config.*' --include='next.config.*' --include='webpack*.js' \
|
||||||
|
--include='package.json' --include='*.env' --include='*.env.*' --include='settings.py' \
|
||||||
|
--include='Procfile' --include='manage.py' \
|
||||||
|
'(--[Pp][Oo][Rr][Tt][[:space:]=]+[0-9]{4,5})|([Pp][Oo][Rr][Tt][[:space:]]*[=:][[:space:]]*"?[0-9]{4,5})' . 2>/dev/null \
|
||||||
|
| grep -oE '[0-9]{4,5}$' | sort -u | tr '\n' ' ')"
|
||||||
|
[[ -n "$devports" ]] && note "ports named in dev-server configs: $devports"
|
||||||
|
note "outbound (sandbox -> a service on this machine) is grantable: 100.64.0.1:<port>."
|
||||||
|
note "inbound (host -> a server the sandbox started) is dropped by the ruleset -- references/port-and-loopback.md"
|
||||||
|
|
||||||
|
# --------------------------------------------------------------------------- environment names
|
||||||
|
section "environment variable NAMES the project references (no values)"
|
||||||
|
names="$(
|
||||||
|
files_matching .env .env.* '*.env.example' '*.env.sample' '*.env.template' env.example \
|
||||||
|
| xargs -r grep -hoE '^[[:space:]]*(export[[:space:]]+)?[A-Za-z_][A-Za-z0-9_]*[[:space:]]*=' 2>/dev/null
|
||||||
|
[[ -n "$compose" ]] && printf '%s\n' $compose | xargs -r grep -hoE '^[[:space:]]+-?[[:space:]]*[A-Z][A-Z0-9_]{2,}[:=]' 2>/dev/null
|
||||||
|
grep -rIhoE 'secrets\.[A-Z][A-Z0-9_]+' .github 2>/dev/null
|
||||||
|
files_matching Dockerfile 'Dockerfile.*' | xargs -r grep -hoE '^ENV[[:space:]]+[A-Za-z_][A-Za-z0-9_]*' 2>/dev/null | awk '{print $2}'
|
||||||
|
)"
|
||||||
|
names="$(printf '%s\n' "$names" | sed -E 's/^[[:space:]]*(export[[:space:]]+)?//; s/^secrets\.//; s/[[:space:]]*[=:]$//' \
|
||||||
|
| sort -u | grep -vE '^(PATH|HOME|USER|SHELL|PWD|LANG|LC_ALL|LC_CTYPE|TZ|TERM|HOSTNAME|SHLVL|ENV|_)$')"
|
||||||
|
if [[ -n "$names" ]]; then
|
||||||
|
printf ' %s\n' "$(printf '%s\n' "$names" | tr '\n' ' ')"
|
||||||
|
note "grant what a run needs as 'env = NAME' -- names only"
|
||||||
|
secretn="$(printf '%s\n' "$names" | grep -iE 'KEY|TOKEN|SECRET|PASSW|CREDENTIAL|AUTH' | tr '\n' ' ')"
|
||||||
|
[[ -n "$secretn" ]] && warn "credential-shaped (values must never enter a committed file): $secretn"
|
||||||
|
else
|
||||||
|
note "none in .env*/compose/Dockerfile/CI -- check the README and the user's launcher"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# --------------------------------------------------------------------------- the model endpoint
|
||||||
|
section "model endpoint on this host (from the pi agent config)"
|
||||||
|
pi_dir="${AISB_PI_AGENT_DIR:-$HOME/.pi/agent}"
|
||||||
|
if [[ -r "$pi_dir/models.json" ]]; then
|
||||||
|
if command -v jq >/dev/null 2>&1; then
|
||||||
|
eps="$(jq -r '.. | .baseUrl? // empty' "$pi_dir/models.json" 2>/dev/null | hosts_of)"
|
||||||
|
else
|
||||||
|
eps="$(grep -oE '"baseUrl"[[:space:]]*:[[:space:]]*"[^"]+"' "$pi_dir/models.json" 2>/dev/null | sed -E 's/.*"baseUrl"[[:space:]]*:[[:space:]]*"//' | hosts_of)"
|
||||||
|
fi
|
||||||
|
if [[ -n "$eps" ]]; then
|
||||||
|
list <<< "$eps"
|
||||||
|
note "the bridge turns apiKey into \$AI_API_TOKEN and copies nothing -- but this host must be allowed"
|
||||||
|
note "no credential value was read or printed"
|
||||||
|
else
|
||||||
|
note "models.json is readable, no baseUrl in it"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
note "no readable $pi_dir/models.json -- nothing to bridge"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# --------------------------------------------------------------------------- existing policy
|
||||||
|
section "existing policy"
|
||||||
|
KV_KEYS="net harness workdir cpus memory pids tmpfs_size base_image node_version pi_version \
|
||||||
|
base_ttl_days base_auto_update selinux home_cache gate_addr gate_port extra_args pi_config \
|
||||||
|
pi_token_env pi_token_auto pi_agent_dir thinking agents agents_dir agents_dest allow env mount install label"
|
||||||
|
for f in .ai-sandbox/config .ai-sandbox/allow; do
|
||||||
|
[[ -r "$f" ]] && found "$f ($(wc -l < "$f") lines)" || note "$f: absent"
|
||||||
|
done
|
||||||
|
if [[ -r .ai-sandbox/config ]]; then
|
||||||
|
while IFS= read -r line; do
|
||||||
|
line="${line%%#*}"
|
||||||
|
line="$(printf '%s' "$line" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
|
||||||
|
[[ -n "$line" && "$line" == *=* ]] || continue
|
||||||
|
k="$(printf '%s' "${line%%=*}" | sed -E 's/[[:space:]]+$//')"
|
||||||
|
v="$(printf '%s' "${line#*=}" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/^"//; s/"$//')"
|
||||||
|
[[ " $KV_KEYS " == *" $k "* ]] || warn "unknown key (ai-sandbox ignores it): $k"
|
||||||
|
[[ "$k" != project_dest ]] || warn "project_dest is parsed and read by nothing -- use workdir"
|
||||||
|
if [[ "$k" == env && "$v" == *=* && "${v%%=*}" =~ (KEY|TOKEN|SECRET|PASSW|CREDENTIAL|AUTH) ]]; then
|
||||||
|
warn "env = ${v%%=*}=... is a literal value for a credential-shaped name in a committed file"
|
||||||
|
fi
|
||||||
|
if [[ "$k" == net && "$v" == full ]]; then warn "net = full in a committed config: that is an escape hatch, not a policy"; fi
|
||||||
|
if [[ "$k" == extra_args ]]; then warn "extra_args in a committed config: the podman escape hatch -- it belongs on one command line"; fi
|
||||||
|
done < .ai-sandbox/config
|
||||||
|
fi
|
||||||
|
if [[ -r .ai-sandbox/allow ]]; then
|
||||||
|
while IFS= read -r line; do
|
||||||
|
line="$(printf '%s' "${line%%#*}" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
|
||||||
|
[[ -n "$line" ]] || continue
|
||||||
|
body="$line"
|
||||||
|
host="$(printf '%s' "$line" | sed -E 's/^\[([^]]*)\].*/\1/; s/^([^:]*):.*/\1/')"
|
||||||
|
if printf '%s' "$body" | grep -qE '^[0-9]{1,3}(\.[0-9]{1,3}){3}(/[0-9]{1,2})?(:[0-9]{1,5})?$'; then
|
||||||
|
note "allow $body -- ipv4/cidr: a direct netfilter rule (ports 80,443 unless :port)"
|
||||||
|
elif printf '%s' "$line" | grep -qE '^\[[^]]*\](:[0-9]{1,5})?$' \
|
||||||
|
|| printf '%s' "$host" | grep -qE '^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$'; then
|
||||||
|
note "allow $body -- ipv6: a direct rule; write it as [addr]:port"
|
||||||
|
elif printf '%s' "$host" | grep -qE '^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$'; then
|
||||||
|
note "allow $body -- domain: the gate filters it at CONNECT (only 80,443,8443 relayed)"
|
||||||
|
else
|
||||||
|
warn "allow $body -- matches no grammar (domain, ip, cidr, [ipv6]:port): check the spelling"
|
||||||
|
fi
|
||||||
|
if [[ -n "$remote_hosts" ]] && printf '%s\n' "$remote_hosts" | grep -qxF -- "$host"; then
|
||||||
|
warn "allow $body is a git remote of this repository -- the sandbox could push what it wrote"
|
||||||
|
fi
|
||||||
|
done < .ai-sandbox/allow
|
||||||
|
fi
|
||||||
|
if [[ -e .ai-sandbox/env ]]; then
|
||||||
|
mode="$(stat -c '%a' .ai-sandbox/env 2>/dev/null || echo '?')"
|
||||||
|
[[ "$mode" == 600 || "$mode" == 400 ]] && found ".ai-sandbox/env present, mode $mode" || warn ".ai-sandbox/env is mode $mode -- chmod 600"
|
||||||
|
git check-ignore -q .ai-sandbox/env 2>/dev/null || warn ".ai-sandbox/env is not gitignored"
|
||||||
|
else
|
||||||
|
note "no .ai-sandbox/env -- write env.example with names and dummy values; the user writes the real one"
|
||||||
|
fi
|
||||||
|
|
||||||
|
section "next"
|
||||||
|
note "1. decide net / allow / env / mount / install / limits from the above (SKILL.md step 2)"
|
||||||
|
note "2. write .ai-sandbox/allow and .ai-sandbox/config, commented, names only"
|
||||||
|
note "3. verify with ai-sandbox --print-policy and --dry-run (no build, no container, no network)"
|
||||||
|
note "4. then one live probe per endpoint the project really needs"
|
||||||
Reference in New Issue
Block a user