chore(contract): extract-guard contract and plan r3
This commit is contained in:
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
|
||||
Reference in new issue
Block a user