Sensu Cloudflare DNS Monitor

A Sensu check plugin that monitors Cloudflare DNS records for unauthorized or unexpected changes. Automatically discovers all zones for your API tokens and alerts when any DNS record is added, removed, or modified.

How It Works

1. First run - Fetches all DNS records and saves them as a baseline
2. Subsequent runs - Compares current records against the baseline
3. Changes detected - Returns WARNING (exit code 1) with details
4. API errors - Returns CRITICAL (exit code 2)

Quick Start

Step 1: Install the Asset

On your Sensu backend:

sensuctl asset add SaladStik/cloudflare-dns-monitor

Step 2: Install Python on Sensu Agents

The plugin requires Python 3.7+ and the requests library on each agent that will run the check.

Debian/Ubuntu:

sudo apt-get update && sudo apt-get install -y python3 python3-requests

RHEL/CentOS/Rocky:

sudo yum install -y python3 python3-requests
# or
sudo dnf install -y python3 python3-requests

Alpine:

apk add --no-cache python3 py3-requests

Step 3: Create a Cloudflare API Token

1. Log in to Cloudflare Dashboard
2. Click your profile icon (top right) → My Profile
3. Select API Tokens from the left sidebar
4. Click Create Token
5. Find Edit zone DNS and click Use template
6. Change permissions from Edit to Read
7. Under Zone Resources, select your zones (or All zones)
8. Click Continue to summary → Create Token
9. Copy the token

Step 4: Create the Config File

On each Sensu agent that will run this check:

sudo mkdir -p /etc/sensu
sudo tee /etc/sensu/cloudflare.json << 'EOF'
{
  "tokens": ["YOUR_CLOUDFLARE_API_TOKEN_HERE"]
}
EOF
sudo chmod 600 /etc/sensu/cloudflare.json

Replace YOUR_CLOUDFLARE_API_TOKEN_HERE with the token you copied.

Step 5: Create the Sensu Check

On your Sensu backend, create the check definition:

cat << 'EOF' | sensuctl create -f -
type: CheckConfig
api_version: core/v2
metadata:
  name: cloudflare-dns
  namespace: default
spec:
  command: check-cloudflare /etc/sensu/cloudflare.json
  subscriptions:
    - cloudflare
  interval: 3600
  timeout: 300
  publish: true
  runtime_assets:
    - SaladStik/cloudflare-dns-monitor
EOF

Step 6: Verify It's Working

# Check the asset is registered
sensuctl asset list

# After a few minutes, check events
sensuctl event list

# View detailed output
sensuctl event info <AGENT_NAME> cloudflare-dns

Adding More API Tokens

To monitor additional Cloudflare accounts or zones, add more tokens to your config:

{
  "tokens": [
    "token-for-main-account",
    "token-for-client-account",
    "token-for-another-account"
  ]
}

Each token automatically discovers all zones it has access to.

Resetting Baselines

After making intentional DNS changes, reset the baseline so the plugin accepts the new state:

Option 1: Run Reset Command

# Reset all zones
check-cloudflare /etc/sensu/cloudflare.json reset

# Reset specific zone only
check-cloudflare /etc/sensu/cloudflare.json reset ZONE_ID

Option 2: Create a Reset Check (Manual Trigger)

type: CheckConfig
api_version: core/v2
metadata:
  name: cloudflare-reset
  namespace: default
spec:
  command: check-cloudflare /etc/sensu/cloudflare.json reset
  subscriptions:
    - cloudflare
  publish: false
  timeout: 120
  runtime_assets:
    - SaladStik/cloudflare-dns-monitor

Then trigger manually when needed:

sensuctl check execute cloudflare-reset

Config Options

Full Example

{
  "tokens": ["token-1", "token-2"],
  "state_dir": "/var/cache/sensu/cloudflare",
  "max_workers": 20
}

Output Examples

No Changes

OK: 2 zones - 0 with changes, 0 errors

[example.com] No changes (15 records)

[example.org] No changes (8 records)

Changes Detected

WARNING: 2 zones - 1 with changes, 0 errors

[example.com] 2 added, 1 removed, 1 modified
  + A staging.example.com → 1.2.3.4 (proxied)
  + CNAME api.example.com → backend.example.com
  - A old.example.com → 10.0.0.1
  ~ A www.example.com → 10.0.0.2 (proxied)
      content: 10.0.0.1 → 10.0.0.2

[example.org] No changes (8 records)

API Error

CRITICAL: [zone-id] API error 401

Exit Codes

Troubleshooting

"check-cloudflare: not found"

Make sure the asset is listed in runtime_assets in your check definition and Python is installed on the agent.

"API error 401"

Your Cloudflare token is invalid or expired. Create a new token.

"API error 403"

Your token doesn't have the required permissions. Ensure it has Zone:Read and DNS:Read.

Debug: List zones a token can access

check-cloudflare list YOUR_TOKEN

License

MIT - Or/bit Solutions