A Committed Symlink That Points Outside the Worktree — Auditing Repos Before You Let AI Spin Up Parallel Trees

An audit script that surfaces only dangerous links

You do not need to delete every symlink. Legitimate links (relative links inside the repo) are used all the time. What you want to surface is only "points outside the repo," "absolute paths," and "points into .git or .claude."

Take the 120000 entries from git ls-files -s, normalize each blob's content (the target), and flag any that resolve outside the repo root. Because it reads the index rather than the working tree, it runs even on a fresh clone before checkout.

#!/usr/bin/env bash
# audit-symlinks.sh — list only the dangerous committed symlinks
# Usage: run at the repo root:  bash audit-symlinks.sh
set -euo pipefail
 
ROOT="$(git rev-parse --show-toplevel)"
DANGER=0
 
# Pull out only the 120000 (symlink) entries
git ls-files -s | awk '$1 == "120000" { $1=$2=$3=""; sub(/^ +/,""); print }' \
| while IFS= read -r path; do
    # blob content = the link target string
    target="$(git cat-file blob ":${path}")"
 
    verdict=""
    case "$target" in
      /*) verdict="absolute path" ;;                   # starts with /
    esac
 
    # Normalize the target relative to the link's location; flag if outside root
    linkdir="$(dirname "${ROOT}/${path}")"
    resolved="$(cd "$linkdir" 2>/dev/null && \
                python3 -c "import os,sys;print(os.path.normpath(os.path.join(os.getcwd(), sys.argv[1])))" "$target" 2>/dev/null || true)"
    case "$resolved" in
      "$ROOT"|"$ROOT"/*) : ;;                          # under root is fine
      *) [ -n "$verdict" ] || verdict="escapes the root" ;;
    esac
 
    # Anything into .git / .claude is dangerous, no exceptions
    case "$resolved" in
      "$ROOT"/.git|"$ROOT"/.git/*|"$ROOT"/.claude|"$ROOT"/.claude/*) verdict="into a managed dir" ;;
    esac
 
    if [ -n "$verdict" ]; then
      printf '⚠️  %-40s → %s  [%s]\n' "$path" "$target" "$verdict"
      DANGER=1
    fi
  done
 
exit "$DANGER"

The script exits with code 1 if it finds even one dangerous link, so you can wrap it with if ! bash audit-symlinks.sh; then … in CI or a hook. Running it across my four repos, dangerous links came back at zero. Confirming zero was itself the payoff: the state moved from "never looked" to "looked and found nothing wrong."

What counts as "dangerous" — the criteria

Here are the criteria as a table. This is where you tune so you do not sweep up legitimate links.

One honest caveat. This audit inspects committed links. It does not cover links created at runtime, or the TOCTOU window where core.symlinks resolution timing matters. The audit narrows the entrance; it is not a substitute for the fix that stops traversal itself. That is why, to me, applying the patch and running the audit are two things you do together, not one instead of the other.

Quarantine first, then create the worktree

When you open a low-trust repository, you can seal off traversal at clone time. Cloning with core.symlinks=false expands links as ordinary files whose content is the target string, so the OS does not follow them.

# For an untrusted clone, first land links as "plain text"
git -c core.symlinks=false clone "$REPO_URL" ./untrusted
 
cd ./untrusted
bash /path/to/audit-symlinks.sh || {
  echo "Dangerous link detected. Aborting worktree creation."
  exit 1
}
 
# Only after the audit passes, re-enable links if needed and cut a worktree

core.symlinks=false affects legitimate links too. A project that builds on symlinks will not work while that setting stands. So use it in the order "seal untrusted clones, inspect, then re-enable if clean." In my automation, I apply this clone only to externally sourced repos and leave my own repos on a normal clone. Locking everything down breaks legitimate uses, so splitting the target by provenance turned out to be the practical line.

The practice of having Claude Code spin up many worktrees is covered in Parallel Development with Claude Code Worktrees. Think of this article as the inspection layer that sits in front of it.

Wiring the check into clone and CI

The check works when it is pinned to the path, not when you remember to run it by hand. Here is where to drop it in.

The minimal shape for wrapping worktree creation looks like this. If the audit does not pass, the branch never opens.

safe_worktree_add() {
  local branch="$1" dir="$2"
  bash "$(git rev-parse --show-toplevel)/audit-symlinks.sh" || {
    echo "Audit failed. Not creating worktree: $dir"
    return 1
  }
  git worktree add "$dir" "$branch"
}

Locking down headless runs from the permissions side is covered in Answering auto mode's confirmation prompts in headless runs, and a record of the destructive-command preflight saving me is in An Empty Variable and rm -rf. Those are a different layer from sealing filesystem paths, but running repos unattended needs both.

Before / After — with and without the check

What changed was order more than code.

The added script is a few dozen lines; the CI job is one. That turned a "path I never looked at" into a "path I look at, and open only if it passes." When the weight of the implementation and the weight of the incident it prevents are this lopsided, finding that asymmetry is a small pleasure.

Closing

If you try just one thing, run audit-symlinks.sh once at the root of a repo you currently let AI touch. In most cases the result is zero. That zero confirms there is no danger, and it is also a step past "never looked." If something does come up, the fact that the one link was found before cutting a worktree is itself the argument for pinning the check to the path.

I would not call myself a security expert, and this audit is not complete either. Still, rather than relying on the patch alone, I add one layer on my own side. I wrote this hoping to share that small habit. Thank you for reading.