diff --git a/docs/configuration.md b/docs/configuration.md index 975a2f8..7f4c1ae 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -108,7 +108,13 @@ Create a `.gtrconfig` file in your repository root to share configuration across > [!IMPORTANT] > Hooks and editor/AI defaults from `.gtrconfig` are executable command entries. They are ignored until you review them with `git gtr trust`; changing those entries requires re-approval. -Approval is bound to the repository path and the filesystem identity of its common Git directory. A replacement or fresh clone at the same path needs new approval, as do approvals created by older versions that only used the path. Normal commits and linked worktrees retain approval. This is command-definition trust: scripts, dependencies, and tools invoked by approved commands are not hashed or pinned, so their contents can change within the trusted repository. Review delegated code and trust its contributors before approving. +Approval is bound to the repository path and the filesystem identity of its common Git directory. Replacing that directory, for example with a fresh clone at the same path, needs new approval, as do approvals created by older versions that only used the path. Normal commits and linked worktrees retain approval. This is command-definition trust: scripts, dependencies, and tools invoked by approved commands are not hashed or pinned, so their contents can change within the trusted repository. Review delegated code and trust its contributors before approving. + +Preserving the common Git directory while replacing its contents preserves its +identity and approval when the command definitions are unchanged. This check +does not attest repository contents, history, or provenance. Do not reuse an +approved Git directory to import a repository whose contributors you do not +trust; use a separate clone and review its commands and delegated code. Command definitions are captured once for trust verification and consumption, with NUL-delimited records preserving multiline values. The version 3 trust format invalidates older approvals; review commands again with `git gtr trust` after upgrading. diff --git a/docs/security-vuln-566-followup.md b/docs/security-vuln-566-followup.md new file mode 100644 index 0000000..a9b511c --- /dev/null +++ b/docs/security-vuln-566-followup.md @@ -0,0 +1,86 @@ +# VULN-566 follow-up validation + +Retested on November 10, 2026 against main `fc8afc0` and the published +`v3.0.0` tag (`2d4852d`). All execution fixtures write harmless marker files +inside disposable repositories. No real shell startup files are modified. + +## Repository contents replaced in place + +`tests/trust_followup.bats` approves an unchanged command invoking +`bootstrap.sh`, initializes an unrelated donor repository, deletes every child +of the approved `.git` directory, and copies the donor's Git contents into it. +The `.git` device, inode, birth time, canonical path, and command definitions +remain identical. The replacement script executes in CLI, Bash, Zsh, and Fish. +Changing the command definition then blocks execution on every path. + +This behavior is reproducible on both v3.0.0 and current main. It demonstrates +the limit of the existing command-definition trust model: neither repository +history nor delegated script bytes are attested. It requires the ability to +replace the approved repository's contents; an ordinary checkout of changed +delegated code already has the same effect. Replacing the common Git directory +itself is a different case and remains covered by the original identity tests. + +Assessment: this is not a new command-approval bypass under the documented +model, but the original statement that any replacement requires approval was +too broad. The configuration documentation now explicitly describes retaining +the directory while reseeding its contents. A requirement to reject this case +would require a stronger content/provenance approval model and a decision about +normal commits and updates to delegated code. Adding another repository-owned +identity file would not attest that code. Seif's final scope decision remains +outstanding; this assessment does not decide HackerOne report status or payment. + +## Old shell caches: H1 #4153317 + +Controlled historical retest generated actual init=6 helpers using v2.11.1, +created its path-only approval, replaced `.git`, and changed the delegated +script while retaining the command. Executing the Bash/Zsh/Fish setup from the +v3.0.0 README loaded the old cache and executed the replacement marker in all +three shells. Fresh v3.0.0 init=7 helpers blocked the same old approval, as did +current init=16 helpers. This confirms an upgrade bypass, rather than a failure +of a fresh installation's identity check. + +The old startup snippets skip the installed CLI entirely when `init=6` matches. +Consequently, a CLI schema bump alone cannot invalidate that path. The v3.0.0 +release still contained those snippets. [PR #215](https://github.com/coderabbitai/git-worktree-runner/pull/215) +subsequently changed the README/help setup to invoke the installed CLI at every +startup, bumped the schema, and documented migration. Current init tests execute +the actual README/help snippets against old caches, including schemas 6 and 7, +and test rejection of older trust formats. The new follow-up tests retain the +old snippet as a counterexample and verify explicit regeneration removes it. + +Users must replace direct-cache or hard-coded-schema startup snippets with the +current documented setup and restart/reload their shell. Already-loaded +functions also require reloading. Merely installing a binary cannot rewrite +startup files or functions in another running shell. + +## Versions, impact, and closure evidence + +- The original trust mechanism appears in released tags beginning with v2.7.1; + this retest directly demonstrates the old-cache path from v2.11.1 to v3.0.0. + It does not claim exhaustive testing of every intermediate release. +- Retained-directory behavior remains present in v3.0.0 and main by design. + Impact is execution of changed code delegated by an already approved command. +- #4153317 overlaps VULN-566 as incomplete upgrade remediation: the old helpers + preserve the original path-only approval behavior. The retained-directory + case shares the delegated-script impact but has different preconditions and + is not automatically equivalent to that migration defect. +- The October 28 statement that the original H1 report was Resolved is supplied + history. No live HackerOne status or private report contents were accessed. +- v3.0.0 was published October 28 at 22:58:54 UTC and contains #207/#211 but + predates #215. At retest time it was the latest published GitHub release. + [Release evidence](https://github.com/coderabbitai/git-worktree-runner/releases/tag/v3.0.0). + A release containing #215 plus upgrade retesting is still needed for closure; + this PR does not publish a release or claim researcher acceptance. + +Local validation: all seven follow-up cases pass on current main; all seven also +pass against the v3.0.0 source archive (they intentionally document the retained +identity and legacy-startup behavior). Historical cache execution used Bash +5.3, Zsh 5.9, and Fish 4.9 on macOS with private XDG directories and isolated Git +configuration. Fresh/current helpers blocked the legacy approval in each shell. +Use `bats tests/trust_followup.bats tests/cmd_trust.bats tests/hooks.bats tests/init.bats` +for the maintained regression suite. CI on this PR provides the corresponding +Linux checks. + +The validation and documentation work is ready for review. Release timing and +Seif's stronger-boundary/duplicate decision are the closure blockers; no release +ETA or deadline is assumed. No Linear, Slack, or HackerOne updates were posted. diff --git a/tests/trust_followup.bats b/tests/trust_followup.bats new file mode 100644 index 0000000..3caacc0 --- /dev/null +++ b/tests/trust_followup.bats @@ -0,0 +1,117 @@ +#!/usr/bin/env bats + +load test_helper + +setup() { + setup_integration_repo + export XDG_CONFIG_HOME="$TEST_REPO/private-config" + export XDG_CACHE_HOME="$TEST_REPO/private-cache" + export XDG_DATA_HOME="$TEST_REPO/private-data" + source_gtr_commands + export PATH="$PROJECT_ROOT/bin:$PATH" +} + +teardown() { + teardown_integration_repo +} + +# Command trust deliberately does not pin delegated script bytes. Replacing +# every child of .git while retaining the directory is equivalent, for this +# boundary, to changing the checkout and refs in an already approved repository. +preserved_directory_case() { + local runtime="$1" identity key donor="$TEST_REPO/donor" + export TEST_REPO FOLLOWUP_INIT + git config -f .gtrconfig hooks.postCd 'sh "$REPO_ROOT/bootstrap.sh"' + printf 'echo original > "$REPO_ROOT/result"\n' > bootstrap.sh + _hooks_mark_trusted "$TEST_REPO/.gtrconfig" + identity=$(_hooks_repo_identity "$TEST_REPO") + key=$(_hooks_current_trust_key "$TEST_REPO/.gtrconfig") + + git init --quiet "$donor" + git -C "$donor" -c user.name=Fixture -c user.email=fixture@example.test \ + -c commit.gpgsign=false commit --allow-empty --quiet -m replacement + # All deleted entries belong to this test's disposable repository. + find "$TEST_REPO/.git" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} + + cp -R "$donor/.git/." "$TEST_REPO/.git/" + printf 'echo replacement > "$REPO_ROOT/result"\n' > bootstrap.sh + [ "$(_hooks_repo_identity "$TEST_REPO")" = "$identity" ] + [ "$(_hooks_current_trust_key "$TEST_REPO/.gtrconfig")" = "$key" ] + + if [ "$runtime" = cli ]; then + run_hooks postCd REPO_ROOT="$TEST_REPO" + else + FOLLOWUP_INIT="$TEST_REPO/init.$runtime" + cmd_init "$runtime" > "$FOLLOWUP_INIT" + "$runtime" -c 'source "$FOLLOWUP_INIT"; gtr_run_post_cd_hooks "$TEST_REPO"' + fi + [ "$(cat result)" = replacement ] + rm result + git config -f .gtrconfig hooks.postCd 'echo changed > "$REPO_ROOT/result"' + if [ "$runtime" = cli ]; then + run_hooks postCd REPO_ROOT="$TEST_REPO" + else + "$runtime" -c 'source "$FOLLOWUP_INIT"; gtr_run_post_cd_hooks "$TEST_REPO"' + fi + [ ! -e result ] +} + +@test "CLI command trust retains approval when Git directory contents change in place" { + preserved_directory_case cli +} + +@test "bash command trust retains approval when Git directory contents change in place" { + preserved_directory_case bash +} + +@test "zsh command trust retains approval when Git directory contents change in place" { + command -v zsh >/dev/null || skip "zsh unavailable" + preserved_directory_case zsh +} + +@test "fish command trust retains approval when Git directory contents change in place" { + command -v fish >/dev/null || skip "fish unavailable" + preserved_directory_case fish +} + +# Historical README setup bypassed the installed CLI entirely on an init=6 +# cache hit. A binary upgrade cannot repair shell startup code it never runs. +legacy_setup_case() { + local runtime="$1" snippet + export LEGACY_CACHE_MARKER="$TEST_REPO/legacy-loaded" + mkdir -p "$XDG_CACHE_HOME/gtr" + printf '# gtr-cache: version=old init=6 func=gtr shell=%s\n' "$runtime" \ + > "$XDG_CACHE_HOME/gtr/init-gtr.$runtime" + printf 'echo legacy > "$LEGACY_CACHE_MARKER"\n' \ + >> "$XDG_CACHE_HOME/gtr/init-gtr.$runtime" + if [ "$runtime" = fish ]; then + snippet='set -l _gtr_init "$XDG_CACHE_HOME/gtr/init-gtr.fish" +test -f "$_gtr_init"; and head -n 1 "$_gtr_init" | string match -q "* init=6 *"; or git gtr init fish >/dev/null 2>&1 +source "$_gtr_init" 2>/dev/null' + else + export LEGACY_SHELL="$runtime" + snippet='_gtr_init="$XDG_CACHE_HOME/gtr/init-gtr.$LEGACY_SHELL" +[[ -f "$_gtr_init" ]] && head -n 1 "$_gtr_init" | grep -q " init=6 " || eval "$(git gtr init "$LEGACY_SHELL")" || true +source "$_gtr_init" 2>/dev/null || true; unset _gtr_init' + fi + "$runtime" -c "$snippet" + [ "$(cat "$LEGACY_CACHE_MARKER")" = legacy ] + rm "$LEGACY_CACHE_MARKER" + # Explicitly invoking the installed generator migrates the old cache. + cmd_init "$runtime" >/dev/null + "$runtime" -c "$snippet" + [ ! -e "$LEGACY_CACHE_MARKER" ] +} + +@test "legacy bash init=6 startup needs regeneration or startup migration" { + legacy_setup_case bash +} + +@test "legacy zsh init=6 startup needs regeneration or startup migration" { + command -v zsh >/dev/null || skip "zsh unavailable" + legacy_setup_case zsh +} + +@test "legacy fish init=6 startup needs regeneration or startup migration" { + command -v fish >/dev/null || skip "fish unavailable" + legacy_setup_case fish +}