chore(contract): extract-guard contract and plan r3

This commit is contained in:
bchanot committed 2026-11-04 22:39:46 +01:00
1 parent 06d2576bc0
commit bc41d62c89
2 files changed
+97

No files matched your search

@@ -0,0 +1,31 @@
# CONTRACT — extract-guard
- date: 2026-11-04 | flow: feat | branch: feature/extract-guard (off develop 06d2576)
- status: active
## REQUEST (verbatim — IMMUTABLE)
on a eu un cas la ou on a extrait un paquet debian et ca a ecrase des binaires etc. voici le raport claude
[pasted incident report, verbatim essentials:] « Une règle dans ~/.claude/CLAUDE.md, sous « Destructive tools & data loss », à côté de la règle lftp. Texte proposé : Installer un paquet ou une archive sur une machine ou une VM : jamais d'extraction (dpkg -x, tar x, unzip, cp -r) vers /, /usr, /etc ou un autre répertoire système. Les distributions usr-merge ont /lib, /bin, /sbin et /lib64 en liens symboliques, et une archive qui contient ces chemins les remplace par de vrais dossiers. D'abord lister le contenu (dpkg -c, tar tf), puis extraire dans un dossier de travail et passer par PATH ou PYTHONPATH. Sans gestionnaire de paquets sur la cible, on le dit à l'utilisateur au lieu de bricoler. 2. Un hook PreToolUse sur Bash qui bloque ces commandes avant exécution. C'est le seul vrai garde-fou, puisqu'une règle écrite peut être oubliée ou mal appliquée. Il refuserait toute commande, y compris dans un ssh ou vaas-cli ssh, qui contient : dpkg -x ou dpkg-deb -x avec une destination / ou absente ; tar avec -C / ; unzip -d /. Cela passerait par la skill update-config. »
fais en sorte d'eviter ca a l'avenir en ajoutant au harnais
## CLARIFICATIONS
Pass A: request complete (outcome: such commands are refused before they run and the doctrine names the rule; scope: the harness = this repo's hooks, settings.json, CLAUDE.global.md).
Context: BLK-022 (open) — the general `hooks/guard-bash.sh` was withheld by the safety classifier; its spec `lib/tests/guard-bash.test.sh` (214 cases) SKIPs while the hook is absent. This guard is a separate, narrow hook so that spec stays untouched.
Pass B `[gated 2026-11-04]` (user: recommended options): deny, not ask (the user runs a real install with `! <command>`); watched commands = dpkg -x / dpkg-deb -x (long forms), tar extraction, unzip, cpio -i, plus recursive `cp` (-r/-R/-a); system roots = /, /usr, /etc, /bin, /sbin, /lib, /lib32, /lib64, /libx32, /boot, /opt, /var, /srv, /root, /sys, /proc, /dev (subdirectories included; /tmp, /home, /mnt, /media and relative paths pass); an unresolvable destination ($VAR, $(…), backtick) is refused.
Design gate `[gated 2026-11-04]` (after the plan challenge: r1 FATAL ×3, r2 FATAL(9)/FATAL(7)/CONCERNS(2); user: "Hook simple + soft_deny", vaas-cli "les deux formes"): one POSIX-awk scanner that re-tokenizes every quoted, `$(…)`, backtick and heredoc text (no carrier list) and runs a detector from every watched tool word; remote commands follow the local rules (relative or absent destination passes); plus an `autoMode.soft_deny` line in settings.json for the forms no static parser sees; `vaas-cli ssh <vm> -- <cmd>` and `vaas-cli ssh <vm> '<cmd>'` both covered; accepted false positive: a text containing a complete extraction command into a system dir. Ruling: matcher `Bash|Monitor` (push-guard precedent, BDR-112), FILE SCOPE gains templates/settings/SETTINGS.md and CHANGELOG.md (doc-sync).
## ACCEPTANCE CRITERIA
1. A PreToolUse Bash hook refuses, before it runs, a command that extracts a package or archive into `/` or a system directory: `dpkg -x` / `dpkg-deb -x` (and their long forms) with such a destination; `tar` extracting with `-C` / `--directory` to one, or after a `cd` to one in the same command; `unzip -d` to one; including when the command sits inside `ssh … '<cmd>'`, `vaas-cli ssh … '<cmd>'` or `bash -c '<cmd>'`. The refusal names the rule and the safe path (list first, extract into a work dir, or let the user run it).
2. The same tools with a non-system destination (a relative path, `/tmp/x`, a `mktemp -d` path, the project dir) and listing forms (`dpkg -c`, `tar tf`, `unzip -l`) pass untouched; any other command passes silently.
3. The hook fails safe on its own errors per the push-guard precedent (missing jq: warn on stderr and allow), never prints on an allowed command, and is wired in settings.json `hooks.PreToolUse` (matcher `Bash`) committed through the git index without the uncommitted UI writes (LRN-253).
4. CLAUDE.global.md § "Destructive tools & data loss" holds the doctrine bullet (list first, work dir + PATH/PYTHONPATH, usr-merge reason, no package manager → tell the user), and the doctrine-citers census stays green.
5. A test suite drives the hook with deny and allow cases (each criterion-1 form, each criterion-2 form) and `make test` is green; shellcheck clean.
## FILE SCOPE
- hooks/extract-guard.sh (new), lib/tests/extract-guard.test.sh (new)
- settings.json (one PreToolUse entry + one autoMode.soft_deny line, through the index)
- CLAUDE.global.md (one bullet)
- README.md / USAGE.md / templates/settings/SETTINGS.md / CHANGELOG.md (doc-sync), .claude/tasks/plans/ (plan), this contract