Canary Secrets
Plant encrypted canary secrets that detect unexpected machine reads, freeze affected projects, and provide an incident investigation trail.
Canary secrets are encrypted tripwires placed among the secrets available to your machines. When an armed canary is successfully read, SikkerKey records the activity, applies your containment settings, and gives you the context needed to investigate the machine and its access.
Treat every armed canary fire as an incident signal. Place canaries where routine workloads will leave them untouched, then grant them to the machines whose secret access you want to monitor.
#How a canary secret works
You plant a canary in a project. SikkerKey generates and encrypts its value.
You grant the canary to selected machines, alongside the real secrets those machines use.
A machine successfully requests the canary after passing authentication, project membership, secret grant, and access policy checks.
SikkerKey records the read and applies the canary’s configured project-freeze actions.
The triggering request receives the generated value as an ordinary secret response. Subsequent machine requests to frozen projects are locked.
You investigate the audit trail, contain the affected identity, rotate exposed credentials, and unfreeze the project when it is safe.
This sequence preserves the canary’s value as a believable target while containment takes effect for the machine’s next request.
#Plan where to plant canaries
A canary is most useful when its placement and grants mirror the access an attacker or unintended process would explore. Before creating one:
Choose a project that contains meaningful machine-readable secrets.
Use a plausible secret name that fits the project’s naming pattern.
Grant the canary to the same machines whose access you want to monitor.
Review each machine’s project memberships before enabling related-project freezing.
Plan normal application reads so routine workloads request only the secrets they need.
Keep at least one project-freeze trigger enabled for an active containment response.
Access policies still apply. A machine must be allowed to read the canary for it to fire. Place the canary under a policy that reflects the access path you intend to monitor.
#Create a canary secret
Open the project and select Secrets.
Select Create, then choose Canary secret.
Enter a secret name between 1 and 255 characters.
Choose whether to arm the canary immediately.
Choose whether to freeze this project, related projects, or both.
Select Plant canary.
SikkerKey creates version 1 with a server-generated 64-character value and stores it encrypted. The value stays stable for the life of the canary, so a planted canary remains a consistent tripwire.
A project must be active and unfrozen before you can plant a new canary in it.
#Arm and disarm a canary
An armed canary applies its configured response when an authorized machine reads it. A disarmed canary continues to appear in the project and its reads remain visible in the audit log, while its containment response is paused.
Open the canary from the project’s Secrets page.
Select Configure.
Use Arm canary or Disarm canary in the State section.
Disarming is useful for a controlled validation or a planned workflow change. Arm the canary again after the controlled activity is complete.
#Configure containment triggers
Open Configure and use the Triggers section to choose the response. Select Save triggers after making changes.
Setting | Response |
|---|---|
Freeze this project | Freezes the project that contains the canary. |
Freeze related projects | Freezes every active project in the same vault that the triggering machine belongs to, including the canary’s project. |
Both settings | Freezes the canary’s project and the other projects in the same vault that the triggering machine belongs to. |
Related-project freezing follows project membership at the moment the canary fires. Review the machine’s Projects list to understand which projects will be included.
#What happens when a canary fires
A canary fires after an authorized machine successfully reads it. SikkerKey then:
Records the normal secret read with the machine identity and source IP address.
Updates the canary’s Last fired time and Fire count.
Freezes the configured projects before completing the response.
Records a critical Canary triggered event.
Records a critical Project frozen event for each affected project.
Sends matching notifications through your configured alert rules and delivery channels.
The triggering request completes with the canary value. The frozen state protects subsequent requests, keeping the canary response consistent with an ordinary successful read.
#How frozen projects behave
Machine activity | Frozen-project result |
|---|---|
Read a secret directly | The client receives a project locked response. |
Poll watched secrets | Secrets in the project report a locked state. |
Run a bulk export | Projects already frozen when the export starts are excluded. |
Request a managed secret through an agent | The request is locked. |
Request leased credentials | Credential issuance is locked. |
The dashboard remains available so you can inspect the project, the canary configuration, machine access, and the audit trail during the investigation.
When a canary is encountered during a bulk export, the current project batch can complete. The frozen state applies to the next export and other subsequent machine requests.
#Configure alerts
Create alert rules that match Critical events in the Secrets and Projects & Applications categories. Add the delivery channels your response team monitors so Canary triggered and Project frozen events reach the right people.
Run a controlled test after setup to confirm the rule, delivery channel, project scope, and response procedure. Use a dedicated test machine and project so the expected freeze does not interrupt a production workload.
#Respond to a canary incident
Open the frozen-project banner and note the triggering canary.
Review the Secret read, Canary triggered, and Project frozen events in the Audit Log.
Identify the machine, source IP address, time, and every project included in the response.
Block or revoke the affected machine identity. Re-enroll it only after the host and workload are trusted.
Rotate the real credentials the machine could access, including credentials for affected external services.
Review the machine’s secret grants, project memberships, and access policies.
When the investigation and credential rotation are complete, select Unfreeze on the project banner.
Unfreezing restores machine access immediately. The canary remains armed. If the affected machine can still read it, another request can freeze the project again.
#Canary lifecycle
The generated value is held as version 1 for the life of the canary. Manage the tripwire through its state, trigger settings, grants, name, and project placement.
Deleting a canary removes its grants and ends its trigger behavior. Its Trash entry follows the project’s retention process and can be permanently deleted; canary restoration creates a fresh tripwire by planting a new canary.
#Troubleshooting
The canary has never fired
Confirm the canary is Armed.
Confirm the machine belongs to the project.
Confirm the machine has an explicit grant for the canary.
Confirm the attached access policy allows the request.
Confirm the machine requested the canary by its exact name or ID.
A project froze during expected activity
Use the audit events to identify the workload that requested the canary. Remove the canary from broad discovery or export patterns, narrow its grants where appropriate, and update the application to request only its required secrets before unfreezing the project.
Related projects were frozen
Review the triggering machine’s project memberships. Related-project containment includes active projects in the same vault that the machine belongs to at trigger time.
The project freezes again after recovery
The canary remains armed after an unfreeze. Review the latest trigger event, block the requesting identity, complete credential rotation and access cleanup, then unfreeze again when the request path is trusted.