KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #cli #codex #claude-code #dsh-plugin #mcp #react #agent #dsh #deepseek-harness

fugl

★ 30 Open GitHub ↗

A warrant canary system

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Build Status](https://travis-ci.org/rot256/fugl.svg?branch=master)](https://travis-ci.org/rot256/fugl)

# Fugl

Fugl ("bird" in Danish) is a [warrant canary](https://en.wikipedia.org/wiki/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 existing 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

## The format

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-----
```

## Metadata

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

### Termination

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 server

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](https://en.wikipedia.org/wiki/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, the client is the essential part of Fugl.

## Getting started

You can start using Fugl, by setting up a [go environment](https://golang.org/doc/install) 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).

## Todo

- Further documentation
- JSON input/output option for client

## Contributing

Fugl is still a work in progress,
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 library.

fugl

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README