CoalLedger is verified under the same framework as its TheColliery siblings—Phoenix-13 hooks, reproducible builds, and event-driven independent scans. Its threat surface is deliberately small: it READS docs and reports; the only online activity is the consent-gated grounding fetch your agent runs in the semantic Full tier—the hook and the engine never network.
Report a security issue in this repo through GitHub's private vulnerability reporting—Security → Report a vulnerability—never a public issue. In scope: the 6+1 canary skills, the shipped hooks (the Claude Code SessionStart conductor, PostToolUse docs tracker, Stop docs-drift reminder and SessionEnd cleanup, plus the Antigravity conductor adapter), scripts/—including the vendored CommonMark+GFM AST engine under scripts/lib/ and the scripts/configure.mjs config CLI—commands/, and the plugin/ dist built from them. Out of scope: a vulnerability in a third-party doc, repo, or codebase a canary merely scans—report that to its own maintainer. This is a one-person-maintained project: expect the report to be read and acknowledged, triaged against the scope above, and disclosed once a fix ships. We acknowledge a report within 5 days, send an assessment within 10 days, and disclose publicly once the fix ships, or at 90 days at most. During an absence announced on the maintainer's GitHub profile, the 5 days count from the first day back. A public GitHub issue remains the right channel for an ordinary, non-security bug.
Fixed vulnerabilities are published as GitHub Security Advisories, where each write-up lives.
The shipped code is in scope: what this project installs and runs for a user, including anything it reads from a repository or file the user did not write. This repository's own tooling (its CI workflows, its release and build scripts, and its test harness, as a maintainer runs them on the maintainer's checkout) is welcome to report on, and a flaw in it is fixed as hardening. Either part earns a published advisory only when an outsider can reach the flaw through input they control: a repository they clone, a file they send, a pull request from a fork, or a network response. A flaw that only the maintainer or the user feeds does not get one. Where it is unclear whether an outsider can reach a flaw, it counts as reachable until the maintainers have decided.
Release tags and maintainer commits are SSH-signed (gpg.format=ssh); GitHub shows the Verified badge on them. Automated Dependabot / CI commits are unsigned by design (they carry no maintainer key), so verify a signed release tag—the artifact a release consumer trusts:
echo "* ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEtqTWGKhX1Dk9nZP8ns13Wl5zsO1Cz3VlTS6m1p2fP9" > coalledger_signers
git config gpg.ssh.allowedSignersFile ./coalledger_signers
git tag -v "$(git describe --tags --abbrev=0)"plugin/ is generated, never hand-edited. node scripts/build-plugin.mjs reproduces it from source; node scripts/verify.mjs byte-checks dist-sync in BOTH directions (stale file and source-less orphan both fail) plus manifests, factory-config-vs-schema, skill frontmatter, version pins, the engine's anti-cry-wolf fixtures, and a census that checks each git spawn under scripts/ takes its environment from the shared gitEnv() helper or from an explicit allowlist of named keys, rather than the process's own (an unguarded spawn can poison an unrelated repository via inherited GIT_* variables; the census is the org canon's token census, a lexer and a small grammar and not a JavaScript parser, so it refuses the shapes on its witness list, among them a helper re-written after its declaration and an escaped env option key, and states its own named ceiling in its header; it is not a proof that no crafted spawn escapes it, and two files stay blob-pinned because they cannot pass it); node scripts/test.mjs runs the zero-dependency suite with an explicit file list, one node --test child per file admitted by the live machine reading, and judges each by its TAP names, so a file that exits early reads as a failure, not a pass. Zero dependencies—no lockfile, nothing to npm audit.
Last scan: CoalLedger v0.17.0-beta.5 dist (plugin/, the release at commit 8a11661), on 2026-11-06 (19:02 UTC), with NVIDIA SkillSpector self-reported version v2.13.4 (package source revision 54824463814a0be01360792523ec7245a69190fc), static stage (--no-llm). Score 100/100 (CRITICAL), 25 findings, 0 real. Each class, read at the scanned tree:
- RA1 Self-Modification ×15: the update check is a local stamp the hook schedules. The agent verifies online and offers
claude plugin update. - RA2 Rogue Agent, Session Persistence ×5: a comment in each copy of the run-list reader names
~/.claudeas a protected path; the reader writes nothing there. - MP3 Memory Manipulation ×1: a placeholder the agent fills from its own context, not a memory write.
- EA2 Autonomous Decision Making ×3: code comments listing config keys that carry no consent, spend or outward axis.
- BH1 Bundled hooks ×1: the three declared hooks, each fail-silent, no network, no child process.
Coverage was partial: 21 of 43 files fully inspected, 22 partial. The scan file, skillspector-20261106T190215Z.json, is kept locally and gitignored. Earlier scans are in this file's git history (git log -- SECURITY.md), and scanning is event-driven.
- Phoenix-13 hooks. Every hook—the four wired on Claude Code (
SessionStartconductor ·PostToolUsedocs tracker ·Stopdocs memory-drift reminder ·SessionEndcleanup) plus the Antigravity conductor adapter—is fail-silent, zero-dependency, no network, no child processes, and silent except its sanctioned context-injection channel. A headless run is safe by construction: the hooks only print and write the small local state below, and theSessionEndhook and the staleness sweep remove the session files and old leftovers they make. - What the installed skill never does: it never auto-fixes a doc (every fix sits behind a choice-gated menu and is applied by your agent with a checkpoint first), never auto-submits anything anywhere (problem reports are offered, user-reviewed, manual), and never writes outside its own footprint. (A repo checkout adds one more writer outside that footprint—
scripts/configure.mjs, a config CLI that ships from noDIST_ITEM; see README.md## Permissionsfor what it does.) The complete write list: the self-update throttle stamp~/.claude/coal/coalledger/update-check(the hook also removes the legacy~/.claude/.coalledger-update-checkonce that stamp is written); the docs-drift session stateos.tmpdir()/coalledger-<session-id>.docsand.docmemmoved(a path list and a 0-byte marker, removed by theSessionEndhook when the session ends); the run listcoalledger-<uid>/run.jsonin the private folder that--list-pathmakes in the system temp folder, which the agent writes with its file tool before a skill's engine reads its paths from it; and, on Antigravity, the once-per-session markerag-conductor-*.markerin that same private folder (coalledger-<uid>in the system temp folder;coalledgerwhere the platform reports no user id). The conductor writes that marker only into a folder that is not a link and, where the platform reports a user id, is the user's own and not open to others. The staleness sweep, run by theSessionEndhook and by the Antigravity conductor when it writes its marker, removes regular files older than seven days whose names are exactly the two session-file names in the temp folder and the marker name in the private folder: at most 200 per folder a run, never a link, a folder, or a file of another name. The engine scripts write nothing at all, except--list-path, which makes that one private folder (mode 0700;coalledgerwhere the platform reports no user id). The engine refuses that folder if it is a link; where the platform reports a user id, it also refuses a folder that belongs to another user or is open to others. It refuses a list file that is a link or belongs to another user. On a shared temp folder another account can create that folder's name first; where the platform reports a user id, the engine then refuses it, the doc scan cannot run for that user, and nothing is read from that folder. A second session's--list-pathremoves the first session's list. - Online activity is scoped and consented. The grounding/standard canaries' real-time source verification is an AGENT action in the paid Full tier, run with your consent—the shipped code contains no network call. Offline, they degrade to
⚠️ unverified, never a guess. - Untrusted config is parse-guarded. The
.coalledger.jsonJSONC parse drops__proto__/constructor/prototypekeys; every read is schema-clamped to the factory default on any invalid value. - Repo-derived reads and writes are bounded, and the project config and named docs are read under a literal root. Every file this process reads from a project is kind-gated before it is ever opened, so a FIFO or a device file is refused rather than read, and bounded, so a pathological file cannot exhaust memory. The project config is also contained: a symlink that escapes the project root, or a link at a parent folder of the config, is refused. A doc the agent names is read under a literal root: the project folder the run list names as
root, or, on a bare CLI run with no--root, the filesystem root of the doc's path; a link at any folder between that root and the doc, a file link that leaves its own folder, or a doc outside the root is refused; a file link that stays inside its own folder is read. A file a doc links to is read without that containment, for its anchors only, so a cross-link to a sibling folder keeps working. A write (configure.mjs's config write-back) first walks the project root down to the config folder and refuses a link or junction on the way before it makes any folder, then refuses an existing non-file target, writes to a temp file first, and renames it into place, so a crash mid-write never leaves a half-written config. - Known limits, not closed. (a) An invalid project value reads as the factory default when no global value is set, because it cannot be honoured either way. (b) A linked target within the container-depth cap is still parsed up to the size cap. (c) The config-folder walk narrows a check-then-write window and does not close it: the walk and the write are separate steps, so a hostile process on the same machine could swap a just-checked folder for a junction in between. A handle-relative open of the folder is the real fix and is not built.
- The translation-pair engine (doc-consistency) runs git through its own copy of the git environment helper,
plugin/skills/doc-consistency/lib/git-env.mjs: a read-onlygit logper declared file. Every git child's environment has the wholeGIT_*family removed, matched case-insensitively, andGIT_CEILING_DIRECTORIESset, so an inheritedGIT_DIRcannot point thegit logat another repository. - Doc content is data, never instructions—the canary contracts bind the agent to judge doc content, not obey it (prompt-injection via a poisoned doc is the named threat model).
Honest scope: these measures are the series' data-safety discipline—injection-aware, consent-gated spend, offline code, no exfiltration path. No formal verification; the scanner record above pins exactly what was scanned and when.