Canary secrets

A canary is a fake credential you place next to the real ones. Nobody legitimate ever uses it, so a single use is a high-signal alert: an intruder dumping a container's environment, a .env leaked to a paste site or a public repository, a compromised CI runner replaying secrets, or someone with read access poking around.

What canaries are, and why they work

Most alerting has to guess what normal looks like. A canary does not: its only normal state is never used. One trip is enough to act on, with no agent, scanner or SIEM. You can place one, leak it on purpose and watch the alert arrive in about thirty seconds.

A canary has two halves. The trigger is what Dynv's server can recognise: an opaque id, with no name attached. The label holds the variable name, its value and where it was placed, sealed so that only the account's owners can open it. Keeping the halves apart is what lets a zero-knowledge server alert without learning your variable names.

Kinds

The API kind is token, url or dns. Database URLs are DNS canaries with a postgres, mysql, redis or mongodb shape.

The tripwire token is the flagship. It is fully in Dynv's control and indistinguishable from a real token: an intruder who finds CI_DYNV_TOKEN_OLD beside the live DYNV_TOKEN and tries it gets exactly the 401 a stale token gets, and you get the alert. Answering a canary with fake success would be more convincing for a moment, but it is a second code path an attacker could probe, and comparing it with what the process actually sees would reveal the fake. "Revoked" is the most believable answer anyway.

Where a URL canary points

A URL canary needs a host that reaches a listener. You don't need a Dynv-owned domain: pick a base per canary with --base, or use the server's default, in this order of convenience.

• Public wildcard-IP hostnames. The default base is a wildcard-IP hostname such as http://*.203.0.113.7.sslip.io: * becomes the trigger, and the hostname resolves to the listener's IP through a public service (sslip.io, nip.io or traefik.me). The generated URL looks like http://<trigger>.203.0.113.7.sslip.io/services/T…/B…/<random>.
• One IPv6 address per canary. With http://{ip6}.sslip.io and a DYNV_CANARY_IP6_PREFIX /64, each canary gets its own address in that prefix; the trigger is the 16-hex interface id and the host is the dashed IPv6 address.
• Your own domain. --base https://*.hooks.acme.com puts the trigger in the first host label; CNAME the wildcard to the canary listener. The base is stored in the canary's sealed label, so a rotation keeps using it. The listener must accept the host: set DYNV_CANARY_ANY_HOST=1 or list it in DYNV_CANARY_HOSTS.
• Your own listener. dynv canary listen --addr :8080 runs a listener that reports requests to Dynv with a process token (DYNV_URL and DYNV_TOKEN). Point a canary at it with --base http://127.0.0.1:8080, or at any host that reaches it. The requesting side talks only to your listener; nothing in the URL, DNS, certificate or response points at Dynv.

Hosted modes are plain http:// in phase 1, like Coolify's default; your-domain and listener modes use your own TLS. The public wildcard-IP services are free and have no SLA: if one stops resolving, its canaries stop tripping silently, and some corporate DNS filters block them. In those modes a DNS lookup alone does not trip; only a connection does.

Our-zone DNS canaries remain available (DYNV_CANARY_DNS_ZONE), and their hosts also answer HTTP on the canary listener. A host is recognised as a canary only on the listener, never on the Dynv API host.

What we don't offer, and why

• AWS access keys are not built yet. A convincing decoy needs a Dynv-owned AWS account and CloudTrail, and AWS key ids encode the account id; sts:GetAccessKeyInfo reveals it without signing in. That is ongoing work, not a flag we can switch on honestly.
• GitHub tokens can't alert. GitHub does not report token use to third parties, so there is nothing for us to observe. A format-only decoy that can't alert is noise, so we don't offer one.
• Stripe, Twilio, OpenAI and similar keys can't alert either. Those services tell nobody about a failed authentication but themselves. There is no honest signal to attach to, and we won't sell a decoy that only looks the part.

The rule is simple: a canary is offered only when its use produces a signal Dynv can actually observe.

Where a canary goes

• In a service (--in <service>): the variable is written into the service's env document and delivered to the process like any other, so dumping /proc/<pid>/environ, running env or reading a crash report shows it next to the real values.
• In a shared group (--group <group>): the same, in every service attached to the group.
• Decoy only (--decoy): never injected anywhere. The value exists only in its sealed label. Get it with dynv canary export --decoy-env for a realistic .env to leave on a laptop, a bastion, a backup bucket or a wiki page, with dynv canary env for a CI secret store, or from the dashboard.

A decoy is never in an env document with a "don't inject" flag, because process tokens read env documents: the flag itself would tell an intruder which variable is fake.

Clients suggest realistic names, generated locally and avoiding names that already exist in the target. Examples: CI_DYNV_TOKEN_OLD, SLACK_WEBHOOK_URL_ALERTS, REDIS_HOST_REPLICA, DATABASE_URL_REPLICA. A delivered variable can't use the DYNV_ prefix, which is reserved in env documents; a decoy .env may use any name. The name is a hint, not a requirement: --name accepts any valid variable name.

What Dynv's server can and can't see

The canary key is owner-only. It is derived from the account's signing seed, which only owner keyrings hold, so labels cannot be opened by viewers, recovery masters or process tokens. That is deliberate: a canary has to stay secret from everyone who might snoop, including people with read access to the account.

Residual risks, stated plainly:

• Creation timing. Creating a delivered canary is one canary write plus one ordinary env write a moment later, and the server or a viewer reading the audit log could correlate them. Create canaries in the same change as real edits, or use decoys, which never touch an env document.
• Public wildcard-IP DNS services see the hostname (the listener IP and the trigger), and a shared DNS zone sees every name in it. Your own domain or a per-canary IPv6 address avoids a shared public name; tokens do not have this problem.
• The server knows which token ids are canaries, because it has to. It can't learn names, and it can't fabricate a token trip without the canary's auth key. A compromised server could still refuse to alert.
• Owners can always see canaries. They catch outsiders and readers, not the account's owners.

Alerts

Canary trips reuse the account's existing Security alert channels from vulnerability monitoring; there is no second settings page. Email goes to the verified alert address only. Webhooks use the same signing, SSRF rules, retries and sealed URLs as vulnerability alerts, and a canary trip counts as critical for thresholds.

A webhook limited to a list of services does not receive canary trips. The server doesn't know which service a canary is in, so it can't honour a service scope.

Every alert contains the canary id and kind, the source (api, http, dns, listener or test; overflow, at most once an hour per canary, when it was used so heavily that some uses were only counted, with how many), time, IP, country when a trusted proxy supplies it, the sanitised user agent, the method or DNS query type, and a link to the canary in the dashboard. It never contains the variable's name: the server can't read it. The dashboard and CLI show the name because they decrypt it locally.

• Pause is the per-canary kill switch. Trips are still recorded and shown, but never delivered.
• Dedupe: one delivery per (canary, IP, source) per 10 minutes. Later trips are kept in the feed as suppressed.
• Budgets: 6 deliveries per canary per hour, then 30 per account per hour across all canaries, with separate counters from vulnerability alerts. Over budget stays in the feed, marked suppressed. The next delivered alert says how many trips were held back.
• The first use is always delivered, unless the whole account budget is already spent within that hour.
• Bounded storage: at most 100 trips per canary per hour and 2,000 per account per hour, then a counter is incremented instead. At most 200 canaries per account.

DNS trips have known noise. The lookup comes from the victim's resolver, not the attacker, so the recorded IP is often a public resolver or a corporate one. Resolvers cache, so a second lookup within the TTL may not trip again. Security products that pre-resolve hostnames found in files can cause false positives. These trips are labelled source: dns.

A user agent that looks like a link preview or chat unfurler (Slackbot, Twitterbot, Googlebot and similar) still alerts, with a note that someone probably pasted the canary somewhere. Operators can list their own scanners in DYNV_CANARY_IGNORE_CIDRS: those trips are recorded but never delivered.

Nothing in Dynv dereferences a variable's value, so the canaries do not trip on Dynv's own systems. The one deliberate path is dynv canary test, which records a source: test trip and delivers it as [test].

Not fingerprintable

A canary is only useful if an attacker can't tell it apart from a real secret that no longer works.

• Tokens are ordinary tokens. Same format, same entropy, no marker bits and no special id range. Failed authentication returns the unchanged 401 that unknown and revoked tokens get, through the same layers. The request path doesn't change: the attempt is queued and matched by a background task, so the answer and its timing never depend on whether the id is a canary. A canary id behaves like an unknown id: its failures count against the IP's budget, and after 20 failures per (IP, id) in 5 minutes it gets the same 429. auth.fail is written as for an unknown id; the trip has its own canary.trip audit event.
• The URL host answers the same way for every path. POST, PUT and PATCH get 200 ok; HEAD, GET and the rest get 404 not found. That holds whether or not a trigger matched, whether it is paused or deleted, and whether the request was rate-limited. There are no Dynv headers, JSON errors or CORS: it looks like a webhook receiver, not the Dynv API. The API is never served on a canary host.
• DNS answers are uniform. Every name under the zone gets the same A record and TTL of 60, matched or not.

What links canaries together depends on the mode:

• Tokens and your own listener: nothing.
• Your domain: your domain, which only you know.
• Wildcard-IP host: the server's IPv4 address, shared by every canary on it. It is not the API address, and its reverse DNS is the provider's.
• Per-address IPv6: the /64 prefix.
• Our DNS zone: the zone.

A signed-up user can read the server's bases and zone from GET /v1/canaries; they are never in the public /v1/meta. For hosted modes, the canary IP should not serve the API: put the API behind a CDN or on another address. The public DNS service that answers a wildcard-IP name sees the hostname (the listener IP and the trigger), never the variable or its value.

CLI

Creating, changing and listing canaries and trips need an owner (writer) master token. Any other master token gets an empty list, the same as an account with no canaries. canary listen uses a process token instead.

dynv canary create --kind token|url|dns|db [--in <service> | --group <g> | --decoy]
                   [--name NAME] [--token-kind pt|mt] [--shape webhook|discord|api]
                   [--base <url base>] [--db postgres|mysql|redis|mongodb] [--json]
dynv canary ls [--json]
dynv canary trips [--canary ID|NAME] [--json] [--watch] [--limit N]
dynv canary rotate <ID|NAME>          # new trigger and value; rewrites the variable in place
dynv canary pause|resume <ID|NAME>
dynv canary rm <ID|NAME> [--keep-var]  # also removes the variable from its service or group
dynv canary test <ID|NAME>
dynv canary export --decoy-env         # a realistic .env of every decoy-only canary, to stdout
dynv canary env [ID|NAME…]             # KEY=VALUE lines for CI secret stores
dynv canary listen --addr <addr>       # self-hosted listener; reports trips with DYNV_TOKEN

MCP

An agent doesn't need the fake secret, and an agent transcript is exactly where a value should not leak, so create_canary never returns one. Decoy .env files are a CLI and dashboard feature. MCP writes carry origin: "mcp" and a change id like every other MCP write.

HTTP API

Reads accept any master token; writes need an owner (writer) master token. The HTTP API reference has the full shapes.

• CanaryInfo {canary_id, kind, trigger, label_ct, paused, created_at, updated_at, trips, last_trip_at?, dropped}.
• CanaryConfig {url_bases[], ip6_prefix?, dns_zone?, max_canaries}. url_bases is the server's URL bases, default first (empty if it has none; a client then needs --base). dns_zone is absent when kind dns is unavailable. Creating a dns canary without a zone, or an IPv6-triggered URL canary without a prefix, fails with 400 canary_kind_unavailable.
• CanaryTrip {id, canary_id, kind, source, at, ip, country?, user_agent?, method?, qtype?, bot, ignored, suppressed, held_back?, delivered}. Trips are kept for 90 days.

Self-hosting

Kind token works on any server. URL canaries need a host that reaches a listener (the server's first base, or your own --base); DNS and database-URL canaries need a delegated zone.

The default wildcard-IP mode needs no domain of your own: point the base at the listener's IP and let sslip.io, nip.io or traefik.me resolve it. If you use your own domain, CNAME it to the listener. A delegated DNS zone still needs an NS delegation and UDP 53 published on the container host; per-address IPv6 needs the /64 accepted on the host. Without any of this, token canaries work alone, and URL canaries still work in your-domain and listener modes. The old single DYNV_CANARY_URL_BASE is gone; the first entry in DYNV_CANARY_URL_BASES is the default.

Thirty-second demo

Create a decoy token, use it by mistake, and watch the alert arrive.

# 1. Create a decoy token. It is never injected into any service.
dynv canary create --kind token --decoy --name CI_DYNV_TOKEN_OLD

# 2. Read its value from the decoy .env.
dynv canary export --decoy-env

# 3. Use it as a service token. It fails exactly like a revoked token, and trips.
DYNV_TOKEN=<the decoy token> dynv run -- true

# 4. Watch trips as they arrive.
dynv canary trips --watch --json

The trip appears in dynv canary trips and in the dashboard, and is delivered to your verified alert email and to any webhook that isn't limited to services. The email shows the canary id, kind, source, IP, country, user agent, time and a link; the variable's name is shown only in the dashboard, because Dynv's server can't read it.

Last updated 2026-11-01