Cloudflare Gateway Log Analyzer 🛡️

A lightweight observability helper for Cloudflare Zero Trust (Free Tier). Using the official GraphQL API within its intended scope. Cloudflare Zero Trust（Free Tier）向けの軽量な可視化補助ツール。公式のGraphQL APIを想定された範囲で利用し、日次の可視化サマリーを生成します。

---

🚀 Overview / プロジェクトの概要

Cloudflare Zero Trust provides world-class security, but the Free Tier has limited log export capabilities for home users and FOSS developers. This project bridges that gap by using the Official GraphQL API within its intended scope to generate structured daily summaries—helping individuals understand their own DNS traffic without the need for Enterprise-grade infrastructure.

Cloudflare Zero Trustは優れたセキュリティを提供しますが、無料版ではログの外部出力に制約があります。 本プロジェクトは、公式のGraphQL APIを想定された範囲で利用し、日次の可視化サマリーを生成します。エンタープライズ級のインフラを必要とせず、個人が自身のDNSトラフィックを把握できるよう支援します。

• 📊 Visualized Insights: Daily trends via Mermaid.js charts. (24時間の推移をグラフ化)
• 📥 Efficient Data Fetching: Smart batching logic (6h x 4) to respect API limits. (API制限に配慮した分割取得ロジック)
• 📍 Basic Breakdown: View DNS traffic summaries by location and device type. (ロケーション・デバイス種別ごとのトラフィックサマリー表示)
• 🔔 Daily Alerts: Instant summary delivery via Discord Webhooks. (Discordへの毎日の解析サマリー通知機能)
• 🔒 Security First: Two-Repo Architecture to protect your private DNS logs. (ログの機密性を守る2リポジトリ構成)

---

👤 Who is this for? / 想定ユーザー

This tool is designed for:

• Individuals and households using Cloudflare Zero Trust (Free Tier)
• Open‑source maintainers securing their own infrastructure
• Developers learning Cloudflare Gateway, DNS security, and GraphQL APIs
• Anyone exploring privacy‑first, self‑hosted observability patterns

本ツールは主に Cloudflare Zero Trust（Free Tier）を実運用している個人・家庭ユーザー、
および 自身の OSS や個人インフラを Cloudflare Gateway で保護している開発者 を想定しています。
DNS セキュリティや GraphQL API の学習用途としても利用できます。

This tool does not make policy decisions or security judgments. It simply summarizes Gateway activity to help users understand their own traffic.

本ツールはポリシーの判断やセキュリティ上の意思決定を行いません。ユーザー自身のトラフィックを把握するために、Gatewayのアクティビティをサマリーとして表示するだけです。

This project is not a commercial alternative to Cloudflare Enterprise products.

---

📊 Live Demo & Alerts / 実行結果と通知のサンプル

Instead of using real private data, this project provides a Live Demo generated by a specialized script.
👉 View the latest Live Demo Report here

📱 Discord Notification Sample

---

🔒 Security First: Two-Repo Architecture / セキュリティ設計

DNS logs contain personal browsing history. Therefore, this tool adopts the following separation architecture: DNSログには個人の閲覧履歴が含まれるため、本ツールは以下の分離アーキテクチャを採用しています。

1. Public Repo (This one): Manages core analysis logic. Contains no personal data. (解析ロジックのみを管理。個人データは一切含まれません。)
2. Private Repo (Yours): For execution and private log storage. (設定を保存し、解析結果を自分だけに保持する実行用リポジトリです。)

---

🗺️ Roadmap / 今後の展望

This project continues to evolve for personal and educational use within the Free Tier.
本プロジェクトは、Free Tierの範囲内での個人・学習用途を目的として継続的に進化しています。

⚠️ Note: This roadmap reflects exploratory ideas for personal and educational use. Features may change or be removed to remain aligned with Cloudflare Zero Trust Free Tier policies.

• 🔔 Alerting System: Instant notifications via Discord Webhooks. (Discordを通じたサマリー通知機能の実装)
• 📦 Cloudflare R2 Integration: Automated backup of CSV logs to R2 storage for personal log retention beyond the default 24-hour window. (Cloudflare R2へのログ自動保存による個人ログの長期保持)
• 📈 Advanced Trends: Weekly and Monthly comparative summaries to help users understand their own traffic patterns. (週次・月次の比較サマリーにより、自身のトラフィック傾向を把握)
• ✅ Robust Testing: Implementation of Pytest to ensure reliability of GraphQL parsing logic. (Pytestの導入による解析ロジックの信頼性向上)

This project intentionally avoids automation that would alter Gateway policies or blocking behavior.

---

🚀 Quick Start / セットアップ手順

1. Prepare Cloudflare / Cloudflareでの準備

• CLOUDFLARE_API_TOKEN: Create a token with Zero Trust > Read permissions. (Zero Trust > Read 権限を持つトークンを作成します。)
• CLOUDFLARE_ACCOUNT_ID: Found in your dashboard. (ダッシュボードから自分のアカウントIDを取得します。)

2. Setup Private Repo / 実行用リポジトリの作成

1. Create a new Private GitHub repository. (新しく「非公開」リポジトリを作成します。)
2. Add secrets to Settings > Secrets and variables > Actions. (Secretsに以下の値を登録します。)
   • CLOUDFLARE_API_TOKEN
   • CLOUDFLARE_ACCOUNT_ID
   • DISCORD_WEBHOOK_URL (Optional / 通知機能を使用する場合)

3. Create Workflow / ワークフローの作成

Create .github/workflows/monitor.yml in your private repo and paste the code below: (非公開リポジトリに .github/workflows/monitor.yml を作成し、以下のコードを貼り付けます)

name: Private DNS Monitor

on:
  schedule:
    - cron: '45 22 * * *' # 07:45 JST
  workflow_dispatch:

permissions:
  contents: read

jobs:
  analyze:
    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:
      - name: Checkout Analyzer Core
        uses: actions/checkout@v6
        with:
          repository: 'yonbaiman/cloudflare-gateway-analyzer'
          ref: 'main'
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.14'

      - name: Run Harvester
        env:
          CF_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CF_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
        run: python scripts/harvester.py

      - name: Save Secure Logs
        uses: actions/upload-artifact@v7
        with:
          name: dns-analytics-csv
          path: dns_logs_summary.csv
          retention-days: 7

4. View Your Reports / 結果の確認方法

1. Go to the Actions tab in your private repository. (作成した非公開リポジトリの Actions タブを開きます。)
2. Click the latest run to view the Step Summary. (最新の実行結果をクリックし、Step Summary を確認します。)
3. Check your Discord channel for the daily summary alert. (通知を設定した場合はDiscordを確認します。)

---

📄 License & Author

• Author: yonbaiman / yonbaiman.cc
• License: Apache License 2.0