🍯 CanaryNet

A production-ready canary token honeypot system. Deploy bait files to detect unauthorized access, credential scrapers, and threat actors — with real-time alerts, geo enrichment, risk scoring, and a dark-theme dashboard.

---

⚠️ Legal Disclaimer

This tool is for DEFENSIVE RESEARCH ONLY on infrastructure you OWN or have explicit written authorization to monitor.

All bait credentials generated by this tool are fake and non-functional. You are responsible for ensuring your deployment complies with all applicable laws and regulations. Never deploy honeypots on systems you do not own or control. The authors accept no liability for misuse.

---

✨ Features

• 🪤 Canary tokens — unique trackable URLs embedded in bait files
• 📁 Bait generator — .env, GitHub Actions workflows, config JSON, fake PAT READMEs, and API docs
• 🌐 IP enrichment — geo (ip-api.com), AbuseIPDB, GreyNoise integration
• 🤖 UA fingerprinting — detect scanners, bots, headless browsers
• 📊 Risk scoring — configurable weight rules, 4 severity levels
• 🔔 Multi-channel alerts — Discord, Slack, Email with burst suppression
• 📈 Dark-theme dashboard — live charts, event table, actor profiles, canary management
• 🔗 GitHub webhook receiver — log and analyze webhook events
• 💾 SQLite / PostgreSQL — async SQLAlchemy 2.x, easy to switch
• 🖥️ Rich CLI — full management interface with beautiful terminal output

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                         CanaryNet                           │
│                                                             │
│  ┌──────────┐    ┌─────────────┐    ┌──────────────────┐  │
│  │  Bait    │    │   Canary    │    │  Webhook         │  │
│  │ Generator│    │   Tokens    │    │  Receiver        │  │
│  └────┬─────┘    └──────┬──────┘    └────────┬─────────┘  │
│       │                 │                     │             │
│       └─────────────────▼─────────────────────┘            │
│                    ┌──────────┐                             │
│                    │  Events  │                             │
│                    └────┬─────┘                             │
│              ┌──────────▼──────────┐                       │
│              │     Enrichers       │                        │
│              │  IP Geo · UA · Risk │                        │
│              └──────────┬──────────┘                       │
│         ┌───────────────▼──────────────┐                   │
│         │        Alert Manager         │                    │
│         │  Discord · Slack · Email     │                    │
│         └───────────────┬──────────────┘                   │
│                   ┌─────▼──────┐                           │
│                   │  Database  │                            │
│                   │  SQLite /  │                            │
│                   │ PostgreSQL │                            │
│                   └─────┬──────┘                           │
│                   ┌─────▼──────┐                           │
│                   │ Dashboard  │                            │
│                   │  FastAPI   │                            │
│                   └────────────┘                           │
└─────────────────────────────────────────────────────────────┘

---

🚀 Quick Start

# 1. Clone and enter directory
git clone https://github.com/xdrew87/canarynet.git
cd canarynet

# 2. Create virtual environment
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env
# Edit .env with your values (webhook URLs, API keys, etc.)

# 5. Initialize the database
python main.py db init

# 6. Start the server
python main.py serve

# 7. Open the dashboard
# http://localhost:8000

---

🖥️ CLI Reference

Command	Description
python main.py serve	Start the dashboard server
python main.py serve --reload	Start with auto-reload (dev)
python main.py serve --port 9000	Start on custom port
python main.py db init	Create database tables
python main.py db stats	Show row counts
python main.py canary list	List all canary tokens
python main.py canary create "My Bait"	Create a canary token
python main.py canary deactivate <id>	Deactivate a token
python main.py generate env	Generate .env bait file
python main.py generate workflow	Generate Actions bait file
python main.py generate bundle	Generate full bait bundle
python main.py events list	List recent events
python main.py events list --risk high	Filter by risk level
python main.py events export --format csv	Export events to CSV
python main.py actors list	List actor profiles
python main.py actors blocklist 1.2.3.4	Toggle blocklist

---

🔧 Environment Variables

Variable	Default	Description
DATABASE_URL	sqlite+aiosqlite:///./canarynet.db	Database connection string
ADMIN_SECRET	(required)	API auth key (X-Admin-Key header)
DISCORD_WEBHOOK_URL	—	Discord incoming webhook URL
SLACK_WEBHOOK_URL	—	Slack incoming webhook URL
EMAIL_HOST	smtp.hostinger.com	SMTP host
EMAIL_PORT	465	SMTP port
EMAIL_USER	—	SMTP username
EMAIL_PASS	—	SMTP password
EMAIL_TO	—	Alert recipient address
ABUSEIPDB_API_KEY	—	AbuseIPDB v2 API key (optional)
GREYNOISE_API_KEY	—	GreyNoise community API key (optional)
CANARY_BASE_URL	http://localhost:8000	Public base URL for canary links
WEBHOOK_SECRET	(required)	GitHub webhook HMAC secret
ALERT_BURST_THRESHOLD	5	Max alerts per IP per burst window
ALERT_BURST_WINDOW_SECONDS	60	Burst window in seconds
DAILY_SUMMARY_HOUR	8	Hour for daily summary (UTC)
LOG_LEVEL	INFO	Log verbosity

---

🚢 VPS Deployment

Create a systemd service at /etc/systemd/system/canarynet.service:

[Unit]
Description=CanaryNet Honeypot Monitor
After=network.target

[Service]
Type=simple
User=canarynet
WorkingDirectory=/opt/canarynet
ExecStart=/opt/canarynet/.venv/bin/python main.py serve --host 127.0.0.1 --port 8000
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable canarynet
sudo systemctl start canarynet
sudo systemctl status canarynet

Use nginx as a reverse proxy with TLS termination (Let's Encrypt recommended).

---

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md first.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'Add my feature'
4. Push to the branch: git push origin feature/my-feature
5. Open a Pull Request

---

🔒 Security

To report a security vulnerability, please see SECURITY.md.
Do not open a public GitHub issue for security vulnerabilities.

---

📄 License

Licensed under the Apache License 2.0 — see LICENSE for details.

Remember: Only deploy honeypots on systems you own or have explicit authorization to monitor.

---