Shpbl Canary Chain

Mints canary markers into synthetic data this package generates itself, then proves — with a payload-free, hash-linked evidence chain — when one of those markers reappears in text you control.

MIT licensed · zero runtime dependencies · MCP stdio server · TypeScript

The security problem

You share an evaluation corpus with a vendor, a model provider, or an internal team. Later you want to know whether that data spread beyond where you released it — into a retrieval index, a model context, a support export, a leaked dump. Ordinary logging cannot answer it, and the answer needs to survive scrutiny: an evidence record that has not been quietly edited after the fact.

What this product does

You generate a synthetic dataset inside this package, mint a canary marker bound to one of its records and one recipient label, hand that marker to exactly one recipient, and later scan text you already control. If the marker comes back, you have evidence that data released to one recipient reached a place you did not release it to — recorded as a payload-free, hash-linked evidence entry whose export verifies as a pure function of its own bytes.

Major capabilities

• Deterministic synthetic datasets. Generated from a fixed 32-bit seed, so a dataset is reproducible and never clock-derived.
• Bound canary markers. Each marker binds one generated record to one recipient label. The marker value is returned to the caller exactly once and is not retrievable afterwards through any public operation.
• Streaming detection. scan_for_canaries scans caller-supplied text or an async chunk stream for known markers.
• Hash-linked evidence. Entries store digests, never payloads or marker values; export verification is pure and offline.
• Session-local containment. A trip sets a containment flag reported to the caller — never an action taken against a person or a third-party system.
• Honeypot record registration. Register a generated record as a honeypot and report access observations against it, on the same evidence chain.

The synthetic-test-data-only boundary

This is a deliberate product boundary, technically enforced, not a disclaimer:

• Canaries can only be minted against datasets this package generated itself. There is no constructor or cast path that accepts caller-supplied "real" records.
• Recipient labels that look like real-world identifiers (e-mail, URL, hostname, IP address, phone number, IBAN, payment card, cloud ARN or access key) are rejected by shape, naming the class that matched.
• Seeds must be fixed 32-bit integers.
• Evidence entries store digests only; a marker value is never re-exposed.
• The package has no network, filesystem-write, or process-execution capability, verified by a build-failing symbol scan.

Honest limitation, preserved from the specification: an operator could manually copy a synthetic canary marker into production data or into somebody else's dataset. This package cannot prevent that. It constrains what the software does, not what a human chooses to do with a string it handed them.

Install and run

Prerequisites: Bun 1.1+ (or Node 22+ with a TypeScript loader). No runtime dependencies to install.

git clone https://github.com/SweetKenneth/shpbl-canary-chain.git
cd shpbl-canary-chain
bun install                    # dev types only
bun test                       # conformance suite
bun run scripts/symbol-scan.ts # build-failing forbidden-capability scan
bun src/mcp-server.ts          # MCP server: newline-delimited JSON-RPC 2.0 on stdin/stdout

MCP configuration

{
  "mcpServers": {
    "canary-chain": {
      "command": "bun",
      "args": ["/absolute/path/to/shpbl-canary-chain/src/mcp-server.ts"]
    }
  }
}

Tool surface

Tool	Purpose
generate_synthetic_dataset	deterministically generate a package-owned synthetic dataset
mint_canary	mint a marker bound to one generated record and one recipient label
register_honeypot	register a generated record as a honeypot
report_access	record an access observation against a honeypot
scan_for_canaries	scan caller-supplied text or an async chunk stream for known markers
export_evidence	export the payload-free, hash-linked evidence chain and verify it
get_stats	per-dataset and per-recipient canary and trip counts
describe_policy	seed rules, limits, identifier-shape classes, hash algorithm
reset_state	clear session state; previously exported evidence is unaffected

Worked example

examples/worked-example.ts generates a dataset, mints a canary for one recipient, scans clean text, then scans text containing the marker, and exports and verifies the resulting evidence chain.

bun examples/worked-example.ts

Verification results

25 conformance tests, 72 assertions: specification properties P1–P13, every §7 failure mode, the export allowlist, and the MCP JSON-RPC surface. Forbidden-symbol scan covers 8 source files with 0 findings. Strict typecheck is clean. Runtime dependencies: zero.

Security boundaries

Protects against: a synthetic evaluation dataset released to one recipient turning up in text you control but never released it to. The evidence chain makes the recurrence provable after the fact and resistant to quiet editing.

Does not protect against: the leak itself, or attribution of blame. A trip proves the marker reappeared in text you scanned. It does not prove who moved it.

Refused capabilities: network access of any kind, filesystem writes, process execution, foreign closure references. Evidence persistence happens only through a sink the caller supplies; if that sink rejects a write, the entry is discarded and the chain head is left unchanged.

See SECURITY.md for the full threat model and misuse boundary.

Known limitations

• An operator can manually copy a synthetic marker into production data. The package cannot prevent that, and does not claim to.
• A trip is evidence of recurrence, not of who caused it.
• Scanning covers only text the caller supplies; the package never discovers or fetches content.

Provenance

Discovered with SHPBL. This product originated through cross-capability composition in the SHPBL capability library. Its public implementation was independently built from a published behavioural specification. SHPBL's proprietary capability library, discovery system, harvested implementation bodies, and private provenance machinery are not included.

• Public behavioural specification: https://github.com/SweetKenneth/shpbl-spec-canary-chain (a copy ships here as SPEC-canary-evidence-chain.md)
• SHPBL: https://shpbl.com
• Details: PROVENANCE.md

Tenable status

Submitted to the Tenable CyberAgents Exchange for review on September 11, 2026. Submission does not imply review, approval, certification, validation, endorsement, or acceptance by Tenable.

SHPBL Agent Evidence series

Independently installable, interoperable at the evidence-record boundary:

• shpbl-action-ledger — agent action evidence ledger
• shpbl-handoff-attestor — cross-agent handoff attestation
• shpbl-drift-sentinel — agent behaviour drift detection
• shpbl-retrieval-auditor — retrieval context provenance
• shpbl-canary-chain — synthetic canary evidence chain

Licence

MIT — Copyright (c) 2026 Kenneth E. Sweet Jr. See LICENSE.