Skip to content

Stateful Terraform is denied outside an allowlisted sandbox root

  • Date: 2026-08-25
  • Status: Accepted
  • Tags: tooling

Context

terraform apply, destroy, import and state mutate real infrastructure, and the blast radius is not local — a wrong directory means the wrong account. Nothing in the Bash permission stack distinguished a sandbox checkout from a production one; a prefix rule can see the command but not which state file it will reach.

The obvious shape — a regex matching dangerous invocations — was tried first and is recorded in the hook's own "HOW IT FAILS CLOSED" section as having been beaten 20 times out of 21. terraform can be reached through a wrapper, an alias, env, a subshell, a changed TF_* variable, a relative path, or a different binary name entirely. Enumerating invocation shapes fails open forever, because the attacker picks the shape.

A second problem surfaced in use rather than in design. The guard allowlists checkout paths and matches by prefix, but if you branch by git worktree every worktree of an allowlisted repo sits at a different path — so every one of them was denied. That is a live false positive on every apply, not a hypothetical, and false positives on a safety control are how the control gets disabled.

Decision

Deny stateful Terraform unless the resolved working directory is inside an allowlisted root.

The check is on location, not on invocation shape. Whatever wrapper, alias or path was used to reach terraform, the state it touches is determined by where it runs — so that is what gets vetted. A shape the guard has never seen still resolves to a directory, and a directory is either inside a root or it is not.

Git worktrees are in scope automatically. Each allowlisted root is re-pointed at every worktree of its repo, so one configured root covers a repo however many worktrees exist. git worktree list --porcelain is the authority: a sibling directory that merely looks like a worktree gets nothing, and a different relative path inside a real worktree gets nothing. git is consulted only after the configured roots have already missed, so ordinary commands pay no subprocess, and a git error yields no extra roots rather than opening the gate.

Read-only Terraform (plan, fmt, validate, version, providers) is untouched.

Alternatives Considered

Option Why Rejected
Regex on dangerous invocation shapes Measured: beaten 20 times out of 21. The caller chooses the shape, so enumeration always trails the attack.
permissions.deny on Bash(terraform apply*) Prefix matching cannot see through cd, a wrapper script, an alias, or env terraform, and cannot express "except in sandbox".
Allowlist each worktree path by hand One entry per worktree per repo, added before each use — friction on the safe path, which is how a control ends up bypassed.
Resolve worktrees by path convention A sibling directory that looks like a worktree would be trusted. git already knows the answer; guessing is strictly worse.

Consequences

Positive:

  • The guard vets the thing that determines blast radius — the working directory — rather than the thing the caller controls.
  • Worktree-based branching stops costing a false denial on every apply.
  • Read-only Terraform stays frictionless, so the guard is not something to work around.

Negative / Trade-offs:

  • A new sandbox checkout must be added to the roots before stateful Terraform runs there. Deliberate: the failure direction is a denial, not an unreviewed apply.
  • The worktree lookup shells out to git. Bounded to the case where configured roots have already missed, so the common path is unaffected.

Ongoing obligations:

  • Do not add invocation-shape matching back. That approach is recorded in-file as having failed 20/21, and this hook exists because location-checking succeeded where it did not.
  • Any widening must keep an external authority for the widened set — git decides what a worktree is. A widening justified by a naming convention is a widening that guesses.
  • Keep the selftest's real-repo-real-worktree fixture. It proves behaviour rather than asserting the implementation back to itself, which is the only reason the worktree change could be trusted without a manual test.

ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.