Skip to content

v0.3.0

Choose a tag to compare

@zpratt zpratt released this 09 Aug 04:28

Feature release on the v0.x local-pilot line. Headline: a new deterministic CodeSignal security rule helps agentic software engineers catch selected filesystem check-then-act races in AI-generated changes before review.

Coach remains experimental and intentionally stays on the 0.x line. This release adds a backward-compatible signal to the local CLI preview; it is not a 1.0 completeness or hosted-platform promise.

What’s new

security.toctou_check_then_act

Flags a selected non-atomic filesystem pattern: code checks a path or its state, then acts on the same path later under the assumption that the checked state still holds. The gap can let another process or actor create, remove, or replace the file between the check and the act (CWE-367, Time-of-Check Time-of-Use).

Language Checks recognized Act calls recognized
Go os.Stat or os.Lstat in the if initializer with a direct err == nil success gate os.Open, os.OpenFile, os.Remove, os.RemoveAll, os.ReadFile
TypeScript / TSX Bare existsSync(path) or member-call forms in an if/ while condition readFileSync, writeFileSync, appendFileSync, unlinkSync, rmSync

The signal is:

  • medium severity and medium confidence by default;
  • located at the filesystem act call, with the check and act preserved as evidence;
  • provenance-tagged as a deterministic semantics finding;
  • rule-versioned as security.toctou_check_then_act version 1;
  • available through coach codesignal diff and baseline reports, including introduced, existing, and resolved lifecycle classification.

The recommended remediation is EAFP-style: perform the filesystem operation directly and handle its error rather than checking existence in a separate step. A second check such as fs.promises.access does not close the race.

Coverage and reliability

  • Go, TypeScript, and TSX analyzer paths are covered with acceptance tests.
  • Go/JS parity fixtures cover the new finding and its stable JSON representation.
  • Diff and baseline lifecycle tests verify that the security signal survives report classification.
  • Dependency and toolchain maintenance updates accompany the feature, including parser, Node.js, AWS SDK, Redis, mise, and release-action refreshes.

Try it

Download the coach binary for your platform from the release assets, then run:

coach codesignal --baseline
# or compare the current worktree with a base ref:
coach codesignal --base main

Look for security.toctou_check_then_act in text or JSON output.

Limits and trust notes

This is an advisory static signal, not a complete security scanner. It does not execute code, provide runtime proof, block merges, or write to GitHub.

Detection is intentionally narrow:

  • path identity uses exact source-text equality; aliases and path.join/path.resolve reconstruction are not followed;
  • common Go inverse early-return and sentinel-gate forms are excluded;
  • TypeScript combined conditions, ternaries, negated/else-only forms, and asynchronous pairs are excluded;
  • TypeScript member-call matching is syntactic name matching, not proof that the object is an fs binding, so false positives are possible;
  • cross-file analysis, alias resolution, and scope-aware filesystem reasoning are out of scope.

An empty report means no matched signal was produced for the inputs analyzed. It must not be interpreted as evidence that no TOCTOU risk exists. Coverage and TypeScript binding precision remain pilot follow-up work in #205.

As in the previous release, this is a local preview: no hosted/AWS deployment, pr_history_scan, web UI, or harness hooks are included. The future API/worker path is specified but TOCTOU-specific delivery there is not independently verified.

Binaries

GoReleaser publishes archives for macOS (Apple silicon darwin_arm64 and Intel darwin_x86_64), Linux (linux_x86_64), and Windows (windows_x86_64), plus signed checksums.txt and its cosign signature bundle.

Related

Area Issue / PR
TOCTOU security signal #162
TypeScript coverage and binding precision follow-up #205
TypeScript / TSX detector implementation #185
Go detector implementation #179
CodeSignal rule registration #178
Previous release v0.2.1