tracewatch

Observability, tracking, and root-cause for the Security Wave.

The Security Wave tools (hookcheck, actionpin, injectcheck, mcpvet, depguard, flowcheck) answer "what is wrong right now, in this one scan." tracewatch is the wave's memory and stopwatch. It ingests their JSON reports over time and answers the questions an incident actually turns on:

• What changed since the last scan? Did a pin silently regress to a mutable tag? Did the ref under an already-pinned action move? That move is the tj-actions shape from March 2025: a tag retargeted under every repo that trusted it, invisible to anyone who only ever ran one scan.
• Where did this finding come from? tracewatch blames a finding to the commit that introduced it (git pickaxe on the finding's own content) and to the pull request that carried it, and labels every statement confirmed, inferred, or not established.
• How fast do we notice? Watch mode scans new issues, PRs, files, and tree changes on arrival and records time-to-detect for each one, so "early detection" is a measured number. The comparison point matters: hosted AI firewalls detect at prompt time, after the agent has already read the content. tracewatch detects at rest and on arrival, before any agent session exists.
• Is the estate getting better? Verdict trends, open findings by tool and severity, mean time open for resolved findings, and detection latency stats, per repo, over the whole scan history.

Deterministic, offline-first, local store you can grep. No hosted backend, no account, no telemetry.

Install

npx -y @reneturcios/tracewatch --version
npm install -g @reneturcios/tracewatch
docker run -i --rm ghcr.io/cloudcorprecords/tracewatch mcp

Quick start

# scan a repo with all six tools and start tracking it
tracewatch ingest ~/src/myrepo

# what changed since the previous scan?
tracewatch diff myrepo

# where did this finding come from?
tracewatch blame myrepo --finding tw_0123456789abcdef

# health over time
tracewatch report myrepo

# watch a directory and scan new content on arrival
tracewatch watch ~/src/myrepo --interval 30

What it tracks

Every ingest stores one scan record (timestamp, tool versions, verdicts, git HEAD) plus one observation per finding. Findings carry stable IDs: a hash of tool, rule, normalized location, and a content signature. The same finding keeps its identity across scans and tool versions; a content edit keeps the identity and changes the ID version, which is what diff reports as CHANGED.

Diff groups: NEW, RESOLVED, CHANGED (with field-level old to new), verdict moves, and REF EVENTS. A ref event fires whenever an action's ref or classification moves, with both values spelled out:

• pin-regression: PINNED to MUTABLE or BRANCH
• pin-improvement: MUTABLE or BRANCH to PINNED
• ref-move: the ref changed inside one classification (for a pinned action, the SHA itself moved)

Blame (root cause)

tracewatch blame myrepo --rule CURL-PIPE-SH --file package.json
tracewatch blame myrepo --finding tw_0123456789abcdef --json

Evidence is labeled, never blended:

• CONFIRMED: the introducing commit from git log -S on the finding's needle in your local clone; the current-line commit from git blame; the PR association from the GitHub API (commits/{sha}/pulls) when the clone has a GitHub remote; ref history and first/last seen from the store itself.
• INFERRED: circumstantial statements, written as inferences (for example, when the introducing commit and the current-line commit differ, the line was rewritten later without introducing the content).
• NOT ESTABLISHED: whatever could not be proven, with the reason (no clone recorded, no GitHub remote, API unreachable). Provenance is never guessed to fill the page.

Watch and time-to-detect

tracewatch watch ~/src/myrepo --interval 60 --alerts alerts.jsonl
tracewatch watch owner/repo --path ~/src/myrepo-clone --interval 60

Local mode polls a directory: new or changed text fi

... View full README on GitHub