https://github.com/varppi/litecanary
Self hostable canary alerts
https://github.com/varppi/litecanary
canary cybersecurity detection-engineering
Last synced: 10 months ago
JSON representation
Self hostable canary alerts
- Host: GitHub
- URL: https://github.com/varppi/litecanary
- Owner: varppi
- License: gpl-3.0
- Created: 2025-01-26T08:08:08.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-09T07:27:46.000Z (10 months ago)
- Last Synced: 2025-08-09T08:51:21.862Z (10 months ago)
- Topics: canary, cybersecurity, detection-engineering
- Language: Go
- Homepage:
- Size: 46.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://img.shields.io/badge/go-%2300ADD8.svg?style=for-the-badge&logo=go&logoColor=white)
[](https://img.shields.io/badge/sqlite-%2307405e.svg?style=for-the-badge&logo=sqlite&logoColor=white)
Light weight self-hostable canary alerts to catch snoopers red-handed.
## What is a canary?
A canary, in the context of this project, is a URL set up so that when someone requests it, an alert is generated and sent to its owner. The URL is usually hidden by linking it to a document with a name like "my passwords" or something similar. Then, when someone comes snooping around and opens the file, you are notified. This provides an effective way to detect hackers during post-exploitation.
## Roadmap
- [x] Basic server & client
- [x] Log file for alerts (could integrate with SIEM)
- [ ] Twilio/email integration?
- [ ] More server response types
More things might appear...
## Installation
You have 2 options: you can either download a precompiled version of both the client and the server from the releases tab. Downloading a precompiled version is recommended.
### Compiling from source:
```bash
git clone https://github.com/Varppi/LiteCanary # Clone the repo
cd LiteCanary # Go into the directory
go build ./cmd/server/server.go # Compile the server (make sure Go is installed)
go build ./cmd/cli/cli.go # Compile the cli
```
## Usage
```
./server & # Starts server
./cli --url http://host:port/basepath # Open CLI
```
## Configuration
You can configure the server in 2 ways, via a config file called "litecanary.conf" in the same directory as the executable or by using the command line parameters.
### Config file
The following settings are currently available:
```env
noregistration= # Disables registration, you will be generated random admin credentials when server is started Default: false
debug= # Shows debug information Default: false
databaselocation= # SQLite server path. Examples: :memory:, ./test.db Default: :memory:
listener= # Host:port to listen on. Default: 127.0.0.1:8080
basepath= # HTTP base path for the api. Default: /api/
publickey= # Path to SSL public key. SSL is disabled by default. Default: ""
privatekey= # Path to SSL private key. SSL is disabled by default. Default: ""
log= # Path to log file. Default: "" (disabled)
```
### Command line parameters
```
-base string
base path for the api (/api/)
-cert string
public key for the rest api
-database string
database location (./test.db, :memory:)
-debug
enables or disables debug information
-key string
private key for the rest api
-listener string
listener (127.0.0.1:8080)
-log string
log file (disabled by default)
-no-req
disables registration
```
## Other
### Cli help
```
help: displays help page
exit: exits the program
user:
reset : resets user password
deleteme: deletes your account and canaries (WARNING: YOU WILL NOT BE PROMPTED FOR A CONFIRMATION)
login : logs in
register : registers a new user. please don't use spaces in your username nor password
acceptable canary types:
image: a 1x1 cyan pixel. (for emails and documents)
text: displays "This is a test page."
redirect: redirects the user to a specific url
canary:
wipe : clears the event history
rm : deletes specific canary.
new : creates a new canary.
update : update a canary. redirect can be anything if you don't use it.
get : gets all the events for a specific canary.
```