Open-source IP/CIDR allowlist and blocklist publishing for firewall automation.
ListIPs lets operators create validated plain-text IP lists, optionally sync approved upstream sources, and serve raw public or tokenized private URLs for tools such as firewalls, HestiaCP, iptables, UFW, Nginx, scripts, and monitoring systems.
- Website: listips.com
- Source: VIWEB-TECHNOLOGY/ListIPs
- License: MIT
- Frontend: Astro
- API and raw delivery: Cloudflare Workers
- Database: Cloudflare D1
- Compiled artifacts: Cloudflare R2
- Background sync: Cloudflare Queues
- Rate limiting: Durable Objects, with KV fallback
- Auth: GitHub OAuth
Use Node.js 24.18.0 from .nvmrc; the minimum supported version is 22.23.4.
Install dependencies:
npm ciRun the Astro frontend:
npm run devRun the Worker locally:
cp worker/wrangler.example.toml worker/wrangler.toml
cp worker/.dev.vars.example worker/.dev.vars
npm run worker:devThe local Worker needs Cloudflare-compatible bindings. For real deployments, create your own D1 database, R2 bucket, Queue, KV namespace, Durable Object binding, and GitHub OAuth app, then update your local worker/wrangler.toml.
npm test
npm run build
npm run worker:typecheck
npm audit --omit=dev
npm auditProduction-style raw delivery smoke checks are available once you have configured Cloudflare resources:
npm run smoke:provision
npm run smoke:rawBy default, smoke fixtures use the reserved viweb-technology username. Override LISTIPS_SMOKE_USERNAME for your own deployment.
- System design
- Project context and product rules
- Deploy to Cloudflare guide
- Performance and quota notes
- Release checklist
You can start with the Deploy to Cloudflare button above to provision the Worker API and raw delivery stack in your own Cloudflare account. The button uses the root wrangler.toml template and can provision the Worker bindings for D1, R2, KV, Queues, and Durable Objects. After deployment, configure a GitHub OAuth app and set the required Worker secrets.
The Astro frontend is still deployed separately as a static site. For a full self-hosted deployment, deploy the frontend to Cloudflare Pages or another static host and set APP_ORIGIN plus GITHUB_OAUTH_REDIRECT_URI to match that public origin.
See the Deploy to Cloudflare guide for button setup, GitHub OAuth configuration, frontend deployment, and verification steps.
Start from the example config:
cp worker/wrangler.example.toml worker/wrangler.tomlCreate the required resources in your Cloudflare account:
- D1 database for user/list metadata
- R2 bucket for compiled raw list artifacts
- Queue for external source sync jobs
- KV namespace for rate-limit fallback
- Durable Object binding for atomic rate limits
- GitHub OAuth application
Apply migrations:
npx wrangler d1 migrations apply <database-name> --remote --config worker/wrangler.tomlSet Worker secrets:
npx wrangler secret put SESSION_SECRET --config worker/wrangler.toml
npx wrangler secret put GITHUB_CLIENT_ID --config worker/wrangler.toml
npx wrangler secret put GITHUB_CLIENT_SECRET --config worker/wrangler.tomlCreate the sync queue if needed:
npx wrangler queues create listips-external-syncDeploy:
npm run worker:deploy
npm run build
npx wrangler pages deploy dist --project-name <pages-project-name>Please do not open public issues for vulnerabilities. See SECURITY.md.
Pull requests are welcome. See CONTRIBUTING.md.