tamperward weekly downloads statistics

Tamperward

A ward is the obstruction inside a lock that blocks the wrong key.

Quick start · Docs & guide · See the evidence → — every round, study and correction in one place, each number bound to its committed artifact · The research series — every registered prediction published beside its outcome

What it is

Coding agents can modify both the implementation and the tests, configuration, CI, hooks and verifier used to judge that implementation — and in observed trajectories, some modify or attempt to modify verification in ways that can turn incorrect work into apparent success. Under pressure, the cheaper route to green is sometimes to weaken the checks instead of fixing the failure.

In plain English: Tamperward lets a coding agent change your code, but not the trusted starting point, the rules, or the checks used to judge that code.

Tamperward is a deterministic verification-integrity layer. It blocks known weakening moves as they happen, observes protected-state effects, and independently re-adjudicates apparent success outside the agent's normal completion path. No runtime LLM judge. It fails closed when adjudication is impossible.

Project status: active research release. Tamperward is usable today, but its enforcement architecture and supporting evidence are still being tested and hardened. Use it as one layer of defence in depth alongside protected CI, independent tests and human review. Findings, limitations and corrections are published openly. The 2.0 major marks the Node 18 drop, not a declaration of security maturity; the distance to that is tracked, milestone by milestone, in SPEC §9.1.

Quick start

Requires Node.js 20.19 or later. JavaScript and TypeScript are the fully supported detector surface; the other documented ecosystems get file-level and pattern-based protection.

onboard is the guided first run: it previews the installation, explains each enforcement point, asks before writing anything, runs the canonical init, offers the detected suite command for your explicit acceptance, runs and explains the first verify, offers a safe demonstration of a weakening move on a disposable worktree, checks the GitHub controls, and ends with a READY / READY WITH WARNINGS / BROKEN / INCOMPLETE posture. The deterministic primitive underneath is npx tamperward init — one idempotent command that wires the policy, the agent hooks, the pre-commit hook, a CI workflow running both the diff-time check and pristine verification, and a CODEOWNERS requirement on the paths that decide whether the gate runs. It never overwrites anything you wrote; --dry-run prints the plan.

A real deployment needs a verify command configured — the generated CI verify step fails closed (exit 2) without one. In .tamperward.yml:

That block is itself a guarded surface: changing the command, lowering the budget, narrowing inputs, removing backend: container, or changing its pinned image is flagged as policy weakening. The four primitives:

Full flags, exit codes, verifier configuration and the trace-verify advisory tool are in the getting-started guide.

Choose your path

| Goal | Destination |

| Install TamperWard | Quick start (this README) | | Configure authoritative CI | Enforcement guide | | Understand the architecture | Architecture reference | | Browse detectors and rules | Rules guide | | Evaluate a model | Research guide | | Inspect published evidence | Research overview | | Contribute code | Development |

Architecture

The agent may produce the work, but it must not control how that work is judged. Tamperward separates steering from adjudication. In-loop hooks steer the agent while it works — denying known weakening operations and detecting protected-tree drift — but they are not the final authority. After the agent exits, tamperward run independently judges the tree it left behind: "visible" verification runs the candidate as it stands; "pristine" verification restores the protected verification state from the trusted base and runs the checks again. Visible green followed by pristine red is a masked failure.

Core invariant: the agent may author the candidate tree, but it must not choose the trusted baseline, the governing policy, the verifier, or the final verdict.

The complete component map, trust boundaries, data flows, the run-envelope lifecycle, platform support and the version-by-version history that earned each layer are on the architecture reference. tamperward verify materialises two temporary copies that both execute agent-controlled code — they are not sandboxes; the pristine-run bounding of runner-configuration inheritance is documented in the threat model.

Production deployment

init is not sufficient on its own, and it says so. Authoritative enforcement needs all of:

1. A configured verify command in .tamperward.yml — CI fails closed without one. 2. The required tamperward status check on the protected branch. 3. Require review from Code Owners — init writes CODEOWNERS over the gate-critical paths; branch protection is the half it cannot set for you. 4. Dismiss stale pull request approvals when new commits are pushed — load-bearing: an approval for an older gate-critical diff must not authorize a later push. A pull_request workflow runs from the PR's own head and a required check is matched by job name, so without this human boundary a PR can keep the job name, replace the gate with true, and present a green required check over a blocked change. That is reproduced on this project's own CI, not a theoretical concern. 5. A pinned Tamperward version and label permissions restricted to trusted humans. 6. Optionally, backend: container for a digest-pinned, network-isolated final verifier — execution-domain isolation, not a semantic-correctness oracle.…