Honeytoken

Framework-seeded canary records that trigger an audit alert on read; integrates with sealed columns. The framework generates decoy values (fake api-key shapes, fake admin URLs, fake DB row references) that are NEVER handed to a real client. Their presence in a request, log, or DB lookup means an attacker reached something they shouldn't have. Every positive lookup emits a honeytoken.tripped audit row with the observing actor's 5 W's so a SOC operator can pivot directly to the compromise.

Canary value shapes (kind): - "apiKey" — bk_canary_ (mirrors b.apiKey shape) - "session" — bks_canary_ (mirrors b.session shape) - "url" — /admin/canary- (planted as a clickable link) - "rowId" — ht_canary_ (planted as a fake foreign key)

Audit shape: - honeytoken.issued — outcome=success; metadata { id, kind } - honeytoken.tripped — outcome=failure; metadata { id, kind, metadata, observedAt, observedActor }

b.honeytoken.create(opts) #

{
  audit:  b.audit,   // audit sink for issued / tripped events (optional, recommended)
}

Build an in-process honeytoken registry. Returns a handle exposing issue(spec) to mint a canary, lookup(value, observedActor?) to test an incoming value (audit-emits honeytoken.tripped on hit), revoke(id) to retire a canary, and size() for diagnostics. The registry is per-process — operators running multiple workers wire a shared b.audit sink and reconcile alerts at the audit layer rather than sharing the registry across nodes (a canary's value is what's planted in the trap, not what's known to the framework).

var honey = b.honeytoken.create({ audit: b.audit });

var canary = honey.issue({
  kind:     "apiKey",
  metadata: { plantedAt: "GET /admin/keys/list", linkedTo: "user-42" },
});
// → { id: "ht_", value: "bk_canary_" }

// Plant the canary value somewhere an attacker who's escalated
// privileges might find it (a fake row in an admin listing, a
// dummy env-var leaked into a traceback page, etc.).

// On every incoming credential, check for canary use:
if (honey.lookup(req.headers["x-api-key"], { ip: req.ip })) {
  // tripped — audit already emitted; respond as if invalid.
  return res.writeHead(403).end();
}

Last updated 2026-08-08T16:39:49.652Z by seeder.