Skip to content
This repository was archived by the owner on Nov 18, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
86 changes: 86 additions & 0 deletions docs/security-vuln-566-followup.md
Original file line number Diff line number Diff line change
@@ -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.
117 changes: 117 additions & 0 deletions tests/trust_followup.bats
Original file line number Diff line number Diff line change
@@ -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
}
Loading