Files
claude/.claude/tasks/contracts/2026-11-04-extract-guard-2214.md
T

5.8 KiB
Raw Blame History

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

  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