README
¶
CF Scanner
A distributed Cloudflare Anycast IP scanning, ranking, automation, and monitoring platform.
中文文档 · Documentation · Security · Contributing
CF Scanner is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Cloudflare, Inc. Cloudflare is a trademark of Cloudflare, Inc.
What it does
CF Scanner coordinates lightweight regional Agents from a central Go service. Agents probe selected Cloudflare addresses while preserving HTTP Host and TLS SNI, then return TCP, TLS, TTFB, availability, CF-RAY, and colo measurements. The Center stores and ranks results per Agent, runs schedules, and manages temporary blacklist rechecks.
- distributed outbound-only Agents with browser-approved pairing and per-Agent credentials;
- Cloudflare official and ASN prefix sources;
- latest-result ranking and complete history;
- server-side filters, sorting, pagination, and geographic facets;
- configurable scan schedules and source synchronization;
- Agent-scoped temporary blacklist and rechecks;
- administrator/viewer RBAC with secure server sessions;
- responsive React 19 console using shadcn/ui Rhea, Base UI, and Tailwind CSS 4.
| Results | Automation |
|---|---|
 |
 |
Quick start
Requirements: Docker with Compose support.
cp .env.example .env
docker compose up -d --build
Open http://localhost:18081 and sign in with the bootstrap administrator configured in .env.
The Web console, management API, and Agent API share this single public origin.
Start the optional local Agent, then open the pairing URL printed in its logs:
docker compose --profile agent up -d local-agent
docker compose logs -f local-agent
Approve the request in the Web console. The Agent saves a per-Agent identity in the agent-data volume and reuses it after restarts. Local example values must not be reused in production.
Architecture
Single HTTPS origin / Ingress
├── /api/* → Go Center ─── PostgreSQL
└── /* → React management console
▲
per-Agent HTTPS Bearer connections
Asia Agent Europe Agent North America Agent
See docs/architecture.md for task leases, result semantics, automation, authentication boundaries, and database behavior. Agent pairing and migration are documented in docs/agent-enrollment.md.
Container images
Release tags publish multi-architecture images:
ghcr.io/3011/cfscan-server
ghcr.io/3011/cfscan-agent
ghcr.io/3011/cfscan-web
Use immutable release tags in production. See docs/operations.md for configuration, health checks, backup, release, and rollback guidance.
Development
make check
This validates documentation, Go tests and builds, UI architecture boundaries, linting, TypeScript, Vitest, and the production web build. See docs/development.md for split-process development and browser regression testing.
Security and responsible use
CF Scanner performs active network measurements. Only scan systems and address ranges you own or are explicitly authorized to test. Read RESPONSIBLE_USE.md before deployment.
Report vulnerabilities privately according to SECURITY.md. Never include credentials or production data in public issues.
Project status
The project is suitable for self-hosted use, but operators should review retention, backup, rate limits, and network policy for their environment. The current maintenance backlog is documented in docs/maintenance-audit.md.
Directories