Fugl ("bird" in Danish) is a warrant canary solution/system. The project attempts to mitigate problems with existing canary solutions:
We have seen canaries that are updated on a daily basis and canaries which are updated once per year. We have seen canaries that were created once and then never updated again. Again, the fact that canaries are non-standard makes it difficult to automatically monitor them for changes or takedowns.
- EFF (Canary Watch – One Year Later)
The goal is to provide canaries which are:
- Readable for humans
- Easy to parse for machines
- Simple to update and validate systematically
Unlike exiting canaries this allows for:
- Automatic creation and submission of new canaries
- Automatic validation of canaries from hundreds of different organizations
- The creation of central services which verify canaries and notifies subscribed users
Canaries are PGP (clear) signed messages, with a metadata header. The metadata is stored as JSON and is used for automation, the remaining content is free text. Within the project we call a signed canary a proof: Here is an example of such a proof:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
# Test canary
You can:
* Explain the purpose of the canary
* Maintain a human readable canary
* Win peoples heart
* Or just, Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
The description should be valid markdown, to please your fellow humans.
The machines should have no problem understanding it regardless
(just avoid using the "Metadata" header)
# Metadata
{
"version": 0,
"author": "Test author",
"creation": "2017-02-11T11:27:54+01:00",
"expiry": "2017-02-21T11:27:54+01:00",
"promises": null,
"nonce": "EujmfYMdYu32Uw-F1LCy-dJjWXmsS2Rm",
"final": false
}
-----BEGIN PGP SIGNATURE-----
wsBcBAEBCAAQBQJYnucqCRB2OicLdup5+QAAAuQIAFplK8DbIxy1WeasCmuGBYpK
9xSHFLHB8zulHZ65zpf2sSDQcFWlF3AXfPsP2GpxDyqY16CaUlxYfdJJt1oN4Vzj
h7SrxsRf8/TdimFB6hpc88KOrQp4VfnECJQOpoC/Aqphmp6ZlcM4TPKrxLNv4zYw
neycggHjqp8Od/PwY8tg26H6FJ0waREE6PfKenac2xp4oWVRGlDQyW6tmWN0Zkb5
RcVToAwQi3FgOhrwZfsJhbFZQ3jUZqUSDrSnGOpbXTjXelVzrCmigBjB41MN8U6/
4/rk1r3HuZGrpHrAZt1T5oADCzMpXAOgYHIr7Zd7yuaOCkVCBv+F7kzKY8QkI9k=
=B3uj
-----END PGP SIGNATURE-----
The following fields are found in the current version:
| Name | Description |
|---|---|
| Version | Canary structure version |
| Author | The purported author of the proof |
| Creation | Time of creation for the canary |
| Expiry | Time of expiry, a new canary must be submitted before this time |
| Promises | A set of statements, if a statement is removed from the set users are notified |
| Final | Flag used for graceful termination of the canary service (see below) |
| Nonce | Random nonce |
An organization no longer wishing to supply canaries can set the "Final" flag, which will indicate to all followers that this canary is the last and users should expect no further canaries from this source.
Proofs are generated by the client (see cmd/client) and saved to a file. This file can then be directly submitted to the server or moved across an air-gap and submitted from another machine. The submission process is a simply HTTP post request (see next section).
The canary server is a simple self-contained HTTP server and does not rely on a database server. All proofs are verified upon submission (using a specified public key) and saved in a directory on the server (sorted by expiry date). The server serves the proofs and the public key, allowing a client to start tracking the proofs.
In addition the Fugl canary server can be used as digital Dead man's switch, by specifying an action (system command) which should be executed by the server if a canary has not been submitted before the expiry time.
Fugl was explicitly designed so that it does not rely on a single model of distribution. If you want to save and store the proofs on e.g. an FTP server this is also possible -- as long as clients know how to retrieve the proofs. The server is included to simplify distribution and automation.
You can start using Fugl, by setting up a go environment and running make in the cmd/client and cmd/server directories.
If there is interest I will provide pre-compiled binaries (but given the setting I would advise against it).
- Further documentation
- JSON input/output option for client
Fugl is still a work in progress (but close to being production ready), if you want to contribute the best way to do so is by:
- Read the code (it is short and quite readable)
- Provide suggestions for Canary format/API changes
Simplicity is prioritized over new features!
This repo WILL NOT contain an automatic system for tracking the canaries, such a system should be easy to implement using the client (and I encourage people to do so). Alternatively this repository can be used as a go library.