5.8 KiB
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).
Gate rulings [gated 2026-11-05] (proposed by the controller after GATE 1 ECARTS(2) and GATE 2 PASS with 4 MEDIUM; user approved both the SC2016 suppression and the cd inheritance: "Oui, les deux"): the test suite's # shellcheck disable=SC2016 is authorized (the single-quoted forms are the commands under test; same line in guard-bash.test.sh and seven other suites); a quoted script inherits the caller's cd directory (a bash -c script runs in the caller's cwd), so cd / && ssh vm "tar xf a" is a stated false positive; a ( … ) subshell restores the directory at its end; glob and brace destinations (*, ?, [, {a,b}) are unresolvable (refused); cpio copy-pass (-p) counts as an extraction; commands over 256 KiB that name a watched tool are refused as too large to check. Re-scan round [gated 2026-11-05] (user: "Oui"): the cap is 64 KiB (busybox awk timing), $"…" is a quote, tool names built by expansion (t$'a'r, t${x}ar, empty $()/backticks) are a stated MISS.
ACCEPTANCE CRITERIA
- 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;tarextracting with-C/--directoryto one, or after acdto one in the same command;unzip -dto one; including when the command sits insidessh … '<cmd>',vaas-cli ssh … '<cmd>'orbash -c '<cmd>'. The refusal names the rule and the safe path (list first, extract into a work dir, or let the user run it). - The same tools with a non-system destination (a relative path,
/tmp/x, amktemp -dpath, the project dir) and listing forms (dpkg -c,tar tf,unzip -l) pass untouched; any other command passes silently. - 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(matcherBash) committed through the git index without the uncommitted UI writes (LRN-253). - 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.
- A test suite drives the hook with deny and allow cases (each criterion-1 form, each criterion-2 form) and
make testis 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