registry / gutcheck / 0.3.2

gutcheck@0.3.2

Prove your AI-written tests actually test your code: a diff-scoped mutation probe that guts each tested function and reruns only its test — plus a sub-second lint and a Claude Code Stop hook that re-probes what an agent just changed.

AI Security Review

scanned 3h ago · by lpm-firewall-ai

No confirmed malicious attack surface. The user-invoked CLI performs local mutation testing; optional static hook templates invoke it after explicit configuration.

Static reason

One or more suspicious static signals were detected.; previous stored version diff introduced dangerous source

Trigger

User runs `gutcheck` or explicitly installs a supplied agent-hook template.

Impact

Project files are mutated only during testing and restored; configured hooks may request one corrective agent retry.

Mechanism

Temporary local source mutation, test-runner execution, and Git-local hook bookkeeping.

Rationale

Static inspection shows a lifecycle-free mutation-testing CLI with explicit, shipped hook templates. Scanner signals map to expected local filesystem and subprocess behavior; no exfiltration, remote payload execution, persistence, or unconsented agent-control mutation is established.

Evidence

package.jsonmutation/gutcheck.mjsmutation/prove.mjsmutation/gate.mjsmutation/probe.mjshooks/session-startmutation/lock.mjsmutation/selfcheck.mjsintegrations/codex/hooks.jsonintegrations/cursor/hooks.jsonintegrations/antigravity/hooks.jsonintegrations/copilot/hooks/gutcheck.json

Decision evidence

public snapshot

AI called this Clean at 96.0% confidence as Benign with low false-positive risk.

Evidence for block

`mutation/prove.mjs` executes configured project test runners and temporarily mutates copied project files.
`mutation/gate.mjs` supports explicit AI-agent Stop-hook responses and stores a Git-local memo.
`hooks/session-start` writes `<git-dir>/gutcheck-baseline` when its static hook template is installed.

Evidence against

`package.json` contains no `preinstall`, `install`, or `postinstall` lifecycle hook.
No network client imports, network requests, dynamic loaders, `eval`, or `Function` calls were found.
`mutation/prove.mjs` restores temporary mutations and removes its temp workspace in `finally`.
Hook configurations are static templates; no code writes `.claude`, `.codex`, `.cursor`, Copilot, or other agent configuration.
Subprocess use is local Git, Python AST helper, and user-project test runners.

Behavioral surface

Source

ChildProcessCryptoEnvironmentVarsFilesystemShell

Supply chain

HighEntropyStringsUrlStrings

ManifestNo manifest risk signals triggered.

scanned 28 file(s), 485 KB of source, external domains: github.com, json.schemastore.org

Source & flagged code

5 flagged

mutation/probe.mjsView file

Lines 1-32javascript

1// mutation/probe.mjs — the minimal-decisive-probe: confirm a hollow/shadow test oracle by EXECUTION.

2//

3// A hollow test (a tautological / shadow oracle whose expected value re-runs or re-derives the code it

4// tests) is, by definition, one that SURVIVES a non-equivalent change to the code under test. This is

5// extreme mutation testing / "pseudo-tested method" detection (Niedermayr/Juergens/Wagner 2016;

6// Descartes/Vera-Pérez/Monperrus/Baudry 2018), scoped to ONE function feeding ONE flagged assertion:

7// gut that function with a gross, guaranteed-non-equivalent return and run ONLY the one test. If a

8// deliberately-broken SUT does not break the test, the oracle is HOLLOW.

9//

10// Pairs with the cheap static shadowOracleGuard, which is a high-recall CANDIDATE generator (it over-

11// flags — fixture-builders, formatters, equivalence tests). The probe is the precision gate: it clears

12// those false positives (a broken SUT makes a real test fail) and confirms the genuinely hollow ones.

13import { execSync } from 'node:child_process';

14import { mkdtempSync, cpSync, readFileSync, writeFileSync, rmSync, existsSync, symlinkSync } from 'node:fs';

High

Child Process

Package source references child process execution.

mutation/probe.mjsView on unpkg · L12

15import { tmpdir } from 'node:os';

16import { join } from 'node:path';

17import { codeOnly } from '../checker/lexer.mjs';

19// A mutation can induce an infinite loop (e.g. gutting a loop's termination condition), which without a

20// bound would hang the probe — and any CI / agent loop calling it — forever. Cap each test run; override

21// with GUTCHECK_PROBE_TIMEOUT_MS. A run that exceeds

22// it is treated as "not green" (the mutant is caught, or the unmutated test is too slow to probe →

23// INCONCLUSIVE at the baseline).

24const PROBE_TIMEOUT_MS = Number(process.env.GUTCHECK_PROBE_TIMEOUT_MS) || 60000;

26// Locate a named function's BODY and return a replacement descriptor, or null if it can't be located/

27// parsed (so the caller reports INCONCLUSIVE, never a wrong verdict). Handles `function NAME(` incl.

28// generators (`function* NAME` / `async function* NAME`), `def NAME(`, `NAME = function` / `NAME: function`

29// (a `=` binding or a `:` object property), parenthesised and bare single-param arrows (`NAME = x =>`),

30// block- and expression-bodied. All structural scanning is on a string/comment MASK (codeOnly blanks them

31// to spaces, positions preserved) so braces/parens/`=>` inside string literals or comments can't fool it,

32// and the parameter list is paren-balanced before the body is located so a default-param arrow

mutation/lock.mjsView file

Lines 3-42javascript

3// Stop hook firing mid-CLI-sweep). The second run must refuse with a stated reason, never collide.

4// The lockfile lives in the OS tmpdir keyed by the canonical repo path — never inside the repo (no

5// git-status pollution, no accidental commit). Stale = the owning pid is no longer alive; cleared

6// silently and retried once. A lock held by THIS process is re-entrant (main()'s full-suite fallback

7// re-runs prove(); an exception can leave a residue lock behind the same pid) — refusing ourselves

8// would deadlock the fallback for no safety gain.

9import { createHash } from 'node:crypto';

10import { writeFileSync, readFileSync, unlinkSync, realpathSync } from 'node:fs';

11import { tmpdir } from 'node:os';

12import { join } from 'node:path';

14export function lockPathFor(dir) {

15 let real; try { real = realpathSync(dir); } catch { real = dir; }

16 return join(tmpdir(), `gutcheck-${createHash('sha1').update(String(real)).digest('hex').slice(0, 12)}.lock`);

17}

19// → { path, release() } when acquired (release only unlinks a lock this pid still owns), or

20// → { held: {pid, started}|null } when a live foreign process holds it (null = lost the takeover race

21// twice — read as held: refusing is fail-closed, colliding is not).

22export function acquireRepoLock(dir) {

23 const path = lockPathFor(dir);

24 const handle = { path, release() { try { if (JSON.parse(readFileSync(path, 'utf8')).pid === process.pid) unlinkSync(path); } catch {} } };

25 for (let attempt = 0; attempt < 2; attempt++) {

Low

Weak Crypto

Package source references weak cryptographic algorithms.

mutation/lock.mjsView on unpkg · L23

26 try {

27 writeFileSync(path, JSON.stringify({ pid: process.pid, started: new Date().toISOString() }), { flag: 'wx' });

28 return handle;

29 } catch {

30 let holder = null; try { holder = JSON.parse(readFileSync(path, 'utf8')); } catch {}

31 if (holder && holder.pid === process.pid) return handle; // re-entrant (see header)

32 if (holder && Number.isInteger(holder.pid) && pidAlive(holder.pid)) return { held: holder };

33 try { unlinkSync(path); } catch {} // stale (dead pid) or unreadable — clear and retry once

34 }

35 }

36 return { held: null };

37}

39// kill(pid, 0) probes liveness without signaling; EPERM = alive under another user (still a real

40// holder), any other failure (ESRCH) = dead.

41function pidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return !!e && e.code === 'EPERM'; } }

mutation/gate.mjsView file

Lines 1-32javascript

1// mutation/gate.mjs — the Stop-hook gate CORE, harness-agnostic. Ported verbatim from

2// hooks/check-changed-tests (now a thin `exec node ... gate --harness=<h>` caller) so more agent-loop

3// integrations can share the same probe-gate logic behind a small harness-adapter interface: one adapter

4// = how to read the world (parseEvent) + how to speak back (renderBlock/renderVoice/renderResidue).

5// Everything else below is shared, harness-agnostic gate logic.

6//

7// runGate() owns, in order: the harness event parse (fail-open on a malformed/unrecognized event), the

8// per-repo opt-outs (.gutcheck-off walked up-tree, GUTCHECK_HOOK=off), the git prerequisite (fail-open if

9// not a repo or git is missing), baseline resolution (<git-dir>/gutcheck-baseline, falling back to HEAD),

10// the diff-hash memo (read/write), loop-guard dispatch (one forced retry, then residue-only), the probe

11// invocation, and verdict-to-message building (block / clean voice / residue — the exact strings the bash

12// hook built). Every error path fails OPEN: null means "print nothing", same as the bash hook's exit 0.

13import { execFileSync } from 'node:child_process';

14import { existsSync, readFileSync, writeFileSync, statSync, realpathSync } from 'node:fs';

15import { dirname, join, isAbsolute } from 'node:path';

16import { fileURLToPath } from 'node:url';

18const GUTCHECK_PATH = fileURLToPath(new URL('./gutcheck.mjs', import.meta.url));

20// One harness adapter = how to read the world and how to speak back. `claude` is the Claude Code Stop

21// hook's own JSON-line protocol.

22export const HARNESSES = {

23 claude: {

24 // parseEvent(stdinText) -> { gate: boolean, loopActive: boolean }

25 // gate=false → print nothing, exit 0 (malformed stdin: fail-open — a NEW guard the bash hook's own

26 // embedded `node -e` parser never had, since Claude Code always sends valid JSON; no existing test

27 // exercises malformed input, so this adds safety without touching pinned behavior).

28 parseEvent(stdinText) {

29 try {

30 const parsed = JSON.parse(stdinText);

31 return { gate: true, loopActive: !!parsed && parsed.stop_hook_active === true };

High

Cross File Remote Execution Context

Source spawns a local helper that also contains network and dynamic execution context; review data flow before blocking.

mutation/gate.mjsView on unpkg · L12

32 } catch {

mutation/py_blocks.pyView file

•path = mutation/py_blocks.py kind = build_helper sizeBytes = 21226 magicHex = [redacted]

Medium

Ships Build Helper

Package ships non-JavaScript build or shell helper files.

mutation/py_blocks.pyView on unpkg

mutation/gutcheck.mjsView file

•matchType = previous_version_dangerous_delta matchedPackage = gutcheck@0.3.1 matchedIdentity = npm:Z3V0Y2hlY2s:0.3.1 similarity = 0.964 summary = stored previous version shares package body but lacks this dangerous source file

Critical

Previous Version Dangerous Delta

This package version adds a dangerous source file absent from the previous stored version; route for source-aware review.

mutation/gutcheck.mjsView on unpkg

Source & flagged code

5 flagged · loading source

mutation/probe.mjsView file

12// those false positives (a broken SUT makes a real test fail) and confirms the genuinely hollow ones. L13: import { execSync } from 'node:child_process'; L14: import { mkdtempSync, cpSync, readFileSync, writeFileSync, rmSync, existsSync, symlinkSync } from 'node:fs';

High

Child Process

Package source references child process execution.

mutation/probe.mjsView on unpkg · L12

mutation/lock.mjsView file

23const path = lockPathFor(dir); L24: const handle = { path, release() { try { if (JSON.parse(readFileSync(path, 'utf8')).pid === process.pid) unlinkSync(path); } catch {} } }; L25: for (let attempt = 0; attempt < 2; attempt++) {

Low

Weak Crypto

Package source references weak cryptographic algorithms.

mutation/lock.mjsView on unpkg · L23

mutation/gate.mjsView file

12Cross-file remote execution chain: mutation/gate.mjs spawns mutation/gutcheck.mjs; helper contains network access plus dynamic code execution. L12: // hook built). Every error path fails OPEN: null means "print nothing", same as the bash hook's exit 0. L13: import { execFileSync } from 'node:child_process'; L14: import { existsSync, readFileSync, writeFileSync, statSync, realpathSync } from 'node:fs'; ... L29: try { L30: const parsed = JSON.parse(stdinText); L31: return { gate: true, loopActive: !!parsed && parsed.stop_hook_active === true }; ... L326: L327: // runGate({ harnessName, dir, stdinText, env }) -> string|null (the stdout payload, null = silence) L328: export function runGate({ harnessName, dir, stdinText, env = {} }) {

High

Cross File Remote Execution Context

Source spawns a local helper that also contains network and dynamic execution context; review data flow before blocking.

mutation/gate.mjsView on unpkg · L12

mutation/py_blocks.pyView file

•path = mutation/py_blocks.py kind = build_helper sizeBytes = 21226 magicHex = [redacted]

Medium

Ships Build Helper

Package ships non-JavaScript build or shell helper files.

mutation/py_blocks.pyView on unpkg

mutation/gutcheck.mjsView file

Critical

Previous Version Dangerous Delta

This package version adds a dangerous source file absent from the previous stored version; route for source-aware review.

mutation/gutcheck.mjsView on unpkg

Findings

1 Critical3 High3 Medium5 Low

CriticalPrevious Version Dangerous Deltamutation/gutcheck.mjs

HighChild Processmutation/probe.mjs

HighShell

HighCross File Remote Execution Contextmutation/gate.mjs

MediumEnvironment Vars

MediumShips Build Helpermutation/py_blocks.py

MediumStructural Risk Force Deep Review

LowScripts Present

LowWeak Cryptomutation/lock.mjs

LowFilesystem

LowHigh Entropy Strings

LowUrl Strings