🌐 Google IP Monitor

Automated monitoring of Google's IP ranges with real-time alerts, interactive charts, and firewall rule exports

Live Dashboard • Chart Analytics • Export Rules • Roadmap

🎯 Overview

Google IP Monitor is an automated infrastructure monitoring tool that tracks changes in Google Cloud and Google Public IP ranges. Built for DevOps engineers, network administrators, and security teams who need to stay informed about Google's infrastructure changes.

Why Google IP Monitor?

🔔 Real-time Alerts - Get instant Telegram notifications every 3 hours when IP ranges change
📈 Interactive Charts - Visualize IP growth trends with Chart.js (Line, Bar, Pie charts)
🔥 Firewall Export - Download ready-to-use rules for 9+ firewall formats (iptables, AWS, Azure, Cisco, pfSense, MikroTik, etc.)
📊 Visual Dashboard - Beautiful Chrome-inspired dark theme interface
🏗️ Microservices Architecture - Modular, scalable, and maintainable design
🤖 Fully Automated - Runs every 3 hours via GitHub Actions, zero maintenance
💰 100% Free - No servers, no costs, forever
📈 Historical Tracking - All changes stored in Git for audit trails
🔒 Secure - No API keys exposed, runs in isolated GitHub environment

✨ Features

🚀 Core Features

Feature	Description
Every 3 Hours Monitoring	Automatically checks Google's IP ranges 8 times per day
Change Detection	Identifies added and removed IP prefixes with detailed diff reports
Interactive Charts	Line, Bar, and Pie charts showing historical trends and analytics
Telegram Alerts	Instant notifications with formatted summaries of changes
9 Export Formats	Download firewall rules for iptables, AWS, Azure, Cisco, pfSense, MikroTik, CSV, JSON, Plain Text
Chart Data Exports	Export historical metrics in CSV, JSON, and Markdown formats
Web Dashboard	Responsive, dark-themed interface showing current status and history
Microservices Backend	5 independent services for scalability and maintainability
Git-based Storage	All data versioned and tracked in GitHub
Multi-source	Monitors both `cloud.json` and `goog.json` endpoints

🔥 Firewall Export Formats

Cloud Providers

☁️ AWS Security Group JSON
🔷 Azure NSG Rules JSON

Network Equipment

🌐 Cisco IOS ACL
🔧 MikroTik RouterOS Script

Firewalls

🐧 iptables/ip6tables Script
🛡️ pfSense Alias Format

Data Formats

📊 CSV (Excel compatible)
📦 JSON (Structured data)
📄 Plain Text List

📱 Telegram Notifications

📊 Google IP Ranges Report
📅 Date: 2025-10-10 15:00
========================================

🔔 Changes detected!

➕ Added (3):
  • 34.128.0.0/16
  • 35.192.0.0/14
  • 2600:1900::/35

📊 Statistics:
  Previous: 1,234 ranges
  Current: 1,236 ranges
  Net change: +2

🌐 Dashboard Features

Live Statistics - Current vs previous day comparison
Historical Charts - Interactive visualizations with Chart.js
- 📈 Line Chart: IP range growth over time
- 📊 Bar Chart: Daily changes (last 30 days)
- 🥧 Pie Chart: IPv4 vs IPv6 distribution
Change Tracking - Color-coded additions and removals
One-Click Export - Download firewall rules in your preferred format
Chart Data Exports - Export metrics to CSV, JSON, Markdown
Responsive Design - Works on desktop, tablet, and mobile
Fast Navigation - Quick access to exports and historical data

🎯 Use Cases

🏢 For Organizations

1. Security & Compliance

✅ Maintain up-to-date firewall rules for Google services
✅ Audit trail for regulatory compliance (SOC2, ISO 27001)
✅ Detect unauthorized IP range changes
✅ Export rules for automated deployment pipelines

2. Network Administration

✅ Update VPN and proxy configurations automatically
✅ Maintain accurate routing tables
✅ Monitor Google Cloud infrastructure expansion
✅ Generate router configs for Cisco/MikroTik

3. DevOps & SRE

✅ Sync infrastructure-as-code with latest Google IPs
✅ Prevent service disruptions due to IP changes
✅ Automate terraform/ansible configuration updates
✅ Import into AWS/Azure security groups

👤 For Individuals

4. Email Security

✅ Validate Google Workspace sender IPs
✅ Update SPF records for custom domains
✅ Detect email spoofing attempts
✅ Configure mail server whitelists

5. API Integration

✅ Whitelist Google service IPs for API endpoints
✅ Secure webhooks and callbacks
✅ Validate incoming requests
✅ Configure CDN and WAF rules

6. Research & Analytics

✅ Track Google's infrastructure growth
✅ Geographic distribution analysis
✅ Network topology research
✅ Export data for custom analysis

🚀 Quick Start

Prerequisites

GitHub account
Telegram account (optional but recommended)
5 minutes of your time

Step 1: Create Telegram Bot (Optional)

Open Telegram and search for @BotFather
Send: /newbot
Follow the prompts and save your Bot Token
Get your Chat ID from @userinfobot

Step 2: Fork & Configure

Fork this repository

https://github.com/m3hr4nn/googleipmonitor

Add GitHub Secrets (if using Telegram)
- Go to Settings → Secrets and variables → Actions
- Add TELEGRAM_BOT_TOKEN
- Add TELEGRAM_CHAT_ID
Enable GitHub Actions
- Go to Actions tab
- Click "I understand my workflows, go ahead and enable them"
Enable GitHub Pages
- Go to Settings → Pages
- Source: Deploy from branch main → / (root)
- Click Save

Step 3: Run First Monitoring

Actions → Google IP Monitor → Run workflow

🎉 Done! Your dashboard will be live in 2-3 minutes at:

Dashboard: https://YOUR_USERNAME.github.io/googleipmonitor/
Chart Analytics: https://YOUR_USERNAME.github.io/googleipmonitor/exports/charts/
Firewall Exports: https://YOUR_USERNAME.github.io/googleipmonitor/exports/

📊 Architecture

High-Level Overview

┌─────────────────────────────────────────────────────────────────────┐
│                GitHub Actions (Every 3 Hours)                        │
│  ┌─────────────┐   ┌──────────────┐   ┌─────────────────────────┐ │
│  │  Fetch IPs  │──▶│ Compare Data │──▶│ Generate Dashboard      │ │
│  │  from Google│   │  Find Changes│   │  + Charts (via Gateway) │ │
│  └─────────────┘   └──────────────┘   └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
           │                    │                         │
           ▼                    ▼                         ▼
    ┌──────────┐         ┌──────────┐             ┌──────────┐
    │   Git    │         │ Telegram │             │  GitHub  │
    │ History  │         │   Bot    │             │  Pages   │
    │ + Cache  │         │          │             │ Dashboard│
    └──────────┘         └──────────┘             └──────────┘

Microservices Architecture (v1.1.0+)

generate_report.py
    ↓
ChartAPIGateway (Orchestrator)
    ↓
    ├→ [1] DataAggregatorService ────▶ cache/metrics.json
    ↓
    ├→ [2] ChartConfigService ────────▶ cache/chart_configs.json
    ↓
    ├→ [3] ChartRendererService ──────▶ HTML/JavaScript
    ↓
    └→ [4] ChartExportService ─────────▶ exports/charts/*
    ↓
Return to generate_report.py ──▶ Inject into index.html

5 Independent Microservices:

DataAggregatorService - Parse historical data and compute metrics
ChartConfigService - Generate Chart.js configurations
ChartRendererService - Render HTML/JavaScript components
ChartExportService - Export data in multiple formats
ChartAPIGateway - Orchestrate all services with error handling

For detailed architecture documentation, see CLAUDE.md

🔥 Firewall Export Guide

Quick Export

Visit: https://YOUR_USERNAME.github.io/googleipmonitor/exports/
Click on your desired format
Download and deploy!

Format Details

🐧 iptables

# Download and apply
wget https://YOUR_USERNAME.github.io/googleipmonitor/exports/iptables.sh
chmod +x iptables.sh
sudo ./iptables.sh

☁️ AWS Security Group

# Import via AWS CLI
aws ec2 create-security-group \
  --group-name google-ips \
  --description "Google IP Ranges" \
  --cli-input-json file://aws-security-group.json

🔷 Azure NSG

# Import via Azure CLI
az network nsg create \
  --resource-group myResourceGroup \
  --name GoogleIPs
az network nsg rule create \
  --nsg-name GoogleIPs \
  --cli-input-json @azure-nsg.json

🌐 Cisco ACL

! Copy/paste into Cisco IOS config
! File: cisco-acl.txt
configure terminal
[paste contents here]
end
write memory

🛡️ pfSense

1. Go to Firewall > Aliases
2. Click "Import"
3. Upload pfsense-alias.txt
4. Apply changes

🔧 MikroTik

# Upload and execute
/import file=mikrotik.rsc

🛠️ Configuration

Customize Schedule

Edit .github/workflows/monitor.yml:

schedule:
  # Run every 3 hours (default)
  - cron: '0 */3 * * *'
  
  # Or run every hour
  - cron: '0 * * * *'
  
  # Or run twice daily at 9 AM and 9 PM UTC
  - cron: '0 9,21 * * *'

Add More Data Sources

Edit monitor.py:

self.urls = {
    'cloud': 'https://www.gstatic.com/ipranges/cloud.json',
    'goog': 'https://www.gstatic.com/ipranges/goog.json',
    'custom': 'https://your-source.com/ips.json'  # Add your source
}

Customize Charts

Edit config/chart_settings.json:

{
  "enabled": true,
  "days_to_show": 90,
  "charts": {
    "line_chart": {"enabled": true, "height": 400},
    "bar_chart": {"enabled": true, "height": 350},
    "pie_chart": {"enabled": true, "height": 320}
  }
}

Customize Theme

Edit styles.css to change colors:

:root {
    --accent-blue: #8ab4f8;   /* Primary accent */
    --accent-green: #81c995;  /* Success/additions */
    --accent-red: #f28b82;    /* Errors/removals */
}

Disable Telegram (Export Only Mode)

If you just want exports without Telegram notifications:

Don't add the Telegram secrets
The workflow will still run and generate exports
You'll see "Telegram credentials not set" in logs (this is fine)

🔮 Roadmap

See the detailed ROADMAP.md for:

✅ Completed features (v1.0.0 - v1.1.0)
🚧 In-progress development
📋 Planned features with timelines
💡 Feature request process
📅 Release schedule

Want a feature? Create an issue or vote with 👍 on existing requests!

🤝 Contributing

Contributions are what make the open-source community amazing! Any contributions you make are greatly appreciated.

How to Contribute

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

Development Guidelines

Follow PEP 8 style guide for Python code
Add comments for complex logic
Test your changes locally before submitting
Update documentation if you add new features

📝 Development

Local Setup

# Clone the repo
git clone https://github.com/m3hr4nn/googleipmonitor.git
cd googleipmonitor

# Install dependencies
pip install -r requirements.txt

# Set environment variables (optional)
export TELEGRAM_BOT_TOKEN="your-token"
export TELEGRAM_CHAT_ID="your-chat-id"

# Run locally
python monitor.py                    # Fetch and compare IPs
python generate_report.py            # Generate dashboard with charts
python generate_firewall_rules.py    # Generate exports

# Test microservices (v1.1.0+)
python services/chart_api_gateway.py # Test full chart pipeline

# View locally
open index.html                      # Main dashboard
open exports/charts/index.html       # Chart data exports
open exports/index.html              # Firewall exports

Project Structure

googleipmonitor/
├── .github/workflows/
│   └── monitor.yml              # GitHub Actions (every 3 hours)
├── services/                    # 🆕 Microservices (v1.1.0)
│   ├── aggregator_service.py    # Data aggregation
│   ├── chart_config_service.py  # Chart configurations
│   ├── chart_renderer_service.py # HTML rendering
│   ├── chart_export_service.py  # Data exports
│   └── chart_api_gateway.py     # Service orchestrator
├── config/                      # 🆕 Configuration (v1.1.0)
│   └── chart_settings.json      # Chart customization
├── cache/                       # 🆕 Service cache (v1.1.0)
│   ├── metrics.json             # Aggregated metrics
│   └── chart_configs.json       # Chart.js configs
├── data/                        # Historical IP snapshots
│   └── YYYY-MM-DD.json
├── exports/
│   ├── charts/                  # 🆕 Chart data exports (v1.1.0)
│   │   ├── index.html
│   │   ├── historical_metrics.csv
│   │   ├── historical_metrics.json
│   │   └── summary.md
│   ├── index.html               # Firewall export dashboard
│   ├── iptables.sh              # Linux firewall
│   ├── aws-security-group.json  # AWS format
│   ├── azure-nsg.json           # Azure format
│   ├── cisco-acl.txt            # Cisco IOS
│   ├── pfsense-alias.txt        # pfSense
│   ├── mikrotik.rsc             # MikroTik
│   ├── plain-text.txt           # Plain text
│   ├── export.csv               # CSV format
│   └── export.json              # JSON format
├── monitor.py                   # Core monitoring logic
├── generate_report.py           # Dashboard + charts generator
├── generate_firewall_rules.py   # Firewall export generator
├── styles.css                   # Dashboard styling
├── index.html                   # Main dashboard (auto-generated)
├── CLAUDE.md                    # Architecture documentation
├── ROADMAP.md                   # 🆕 Product roadmap (v1.1.0)
├── requirements.txt             # Python dependencies
└── README.md                    # You are here!

Adding a New Export Format

Edit generate_firewall_rules.py
Add your generator method:

def generate_your_format(self, ipv4_prefixes, ipv6_prefixes):
    rules = []
    # Your format logic here
    for ip in ipv4_prefixes:
        rules.append(f"your-format: {ip}")
    return "\n".join(rules)

Add to the formats dictionary in generate_all():

formats = {
    'your-format.txt': self.generate_your_format,
    # ... other formats
}

Update the exports index page to include your format

📊 Dashboard Preview

🌐 Main Dashboard

Beautiful dark-themed interface with real-time statistics, interactive charts, and change tracking.

Features:

📊 Live statistics cards (Previous Day, Current Day, Net Change, IPv4/IPv6)
📈 Interactive charts (Line, Bar, Pie charts with Chart.js)
🎨 Chrome-inspired dark theme
🔥 Integrated exports with 9 formats
📱 Fully responsive design

👉 View Live Dashboard

📈 Chart Analytics Page

Export and analyze historical IP range metrics.

Available Exports:

📊 CSV for Excel analysis
📦 JSON for API consumption
📄 Markdown for documentation

👉 Browse Chart Data

🔥 Firewall Export Page

Download ready-to-use firewall rules in your preferred format.

Available Formats:

🐧 iptables/ip6tables • ☁️ AWS Security Group • 🔷 Azure NSG
🌐 Cisco ACL • 🛡️ pfSense • 🔧 MikroTik RouterOS
📄 Plain Text • 📊 CSV • 📦 JSON

👉 Browse Exports

❓ FAQ

How often does it check for changes?

Every 3 hours (8 times per day). You can customize this in the workflow file.

What firewall formats are supported?

Currently: iptables, AWS Security Group, Azure NSG, Cisco ACL, pfSense, MikroTik, CSV, JSON, and Plain Text. More formats can be added easily!

Do I need Telegram to use this?

No! Telegram is optional. The dashboard and exports work without it. Just don't add the Telegram secrets.

How do I import rules into my firewall?

Check the "Firewall Export Guide" section above for specific instructions for each format.

Can I monitor other IP sources besides Google?

Yes! Add any JSON/text IP source to the `urls` dictionary in `monitor.py`.

Will this use up my GitHub Actions quota?

No. With 2,000 free minutes/month and ~2 minutes per run, you use only 480 minutes/month (24% of quota).

Can I run this on my own server?

Yes! Set up a cron job to run the Python scripts. But GitHub Actions is easier and free!

How do I update to the latest version?

Sync your fork with the upstream repository, or manually copy new files from the main repo.

📄 License

Distributed under the MIT License. See LICENSE for more information.

🌟 Star History

💬 Support

📧 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
🌐 Dashboard: Live Demo
🔥 Exports: Export Page

🙏 Acknowledgments

Google Cloud IP Ranges
GitHub Actions
Telegram Bot API
Roboto Font Family
All contributors and users of this project

📈 Project Stats

Made with ❤️ for the DevOps community

If you find this useful, please consider giving it a ⭐️

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 766 Commits
.github/workflows		.github/workflows
cache		cache
config		config
data		data
exports		exports
services		services
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
generate_firewall_rules.py		generate_firewall_rules.py
generate_report.py		generate_report.py
index.html		index.html
monitor.py		monitor.py
requirements.txt		requirements.txt
styles.css		styles.css

License

m3hr4nn/googleipmonitor

Folders and files

Latest commit

History

Repository files navigation