https://github.com/yearn/dns-bot
https://github.com/yearn/dns-bot
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/yearn/dns-bot
- Owner: yearn
- Created: 2025-05-14T18:39:53.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2026-06-11T23:51:32.000Z (about 2 months ago)
- Last Synced: 2026-06-12T01:19:21.383Z (about 2 months ago)
- Language: TypeScript
- Size: 98.6 KB
- Stars: 14
- Watchers: 1
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# DNS Monitor Bot
A simple to configure, pre-built Cloudflare Worker that monitors DNS records for any list of user-specified domains and sends notifications via Telegram when changes are detected.
The project is designed to stay comfortably within Cloudflare's free tier for it's Worker and KV storage services.
Example alert
## Prerequisites
- [Node.js](https://nodejs.org/) (v20 or later)
- [npm](https://www.npmjs.com/) (comes with Node.js)
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) (v4 or later)
## Setup
1. **Clone the repository:**
```bash
git clone https://github.com/wavey0x/dns-bot.git
cd dns-bot
```
2. **Install dependencies:**
```bash
npm install
```
3. **Configure your bot:**
All configuration lives in your repository's Settings > Secrets and variables > Actions.[^1]
- Get your Cloudflare API token[^2]
4. **Deploy the bot:**
Deploys only run via GitHub Actions — push to the `main`/`master` branch (or trigger the workflow manually) and the GitHub Action will deploy the bot.
## Viewing Logs
To view the logs for your deployed worker:
1. Go to the [Cloudflare Dashboard](https://dash.cloudflare.com/).
2. Navigate to **Workers & Pages**.
3. Select your worker (`dns-bot`).
4. Click on **Logs** to view the worker's logs.
## Troubleshooting
- **Wrangler not found:** Ensure Wrangler is installed globally or use `npx wrangler`.
- **Deployment fails:** Check your API token and ensure all environment variables are set correctly.
- **No logs:** Ensure logging is enabled in your `wrangler.toml` file.
- **GitHub Actions fails:** Verify that all required secrets are set in your repository's Settings > Secrets and variables > Actions.
## Footnotes
[^1]: Go to your repository's Settings > Secrets and variables > Actions. Add the sensitive values as **secrets**: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, and `TELEGRAM_BOT_TOKEN`. Add the rest as **variables**: `MONITOR_DOMAINS` (comma-separated domains) and `TELEGRAM_CHAT_ID`, plus optionally `TELEGRAM_THREAD_ID` to post alerts to a specific topic thread in a Telegram group chat and `HEARTBEAT_URL` for Uptime Kuma push monitoring. Optionally add `ALLOWED_IP_RANGES` (e.g. `flexmeow.com=216.150.0.0/16;other.com=76.76.21.0/24,76.76.22.0/24`) so IP changes that stay inside a domain's expected CIDR ranges update state silently instead of alerting - useful for hosts like Vercel that rotate IPs within known pools.
[^2]: To get your Cloudflare API token:
1. Go to the [Cloudflare Dashboard](https://dash.cloudflare.com/)
2. Navigate to **My Profile** > **API Tokens**
3. Click **Create Token**
4. Choose **Create Custom Token**
5. Set the following permissions:
- **Account** > **Workers** > **Edit**
- **Zone** > **DNS** > **Read**
6. Set the **Account Resources** to **All accounts**
7. Set the **Zone Resources** to **All zones**
8. Click **Continue to summary** and then **Create Token**