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 (v20 or later)
• npm (comes with Node.js)
• Wrangler CLI (v4 or later)

Setup

1. Clone the repository:

   git clone https://github.com/wavey0x/dns-bot.git
   cd dns-bot

2. Install dependencies:

   npm install

3. Configure your bot:

   All configuration lives in your repository's Settings > Secrets and variables > Actions.¹

   • Get your Cloudflare API token²

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

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