ListIPs

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

Stack

• 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

Local Development

Install dependencies:

npm install

Run the Astro frontend:

npm run dev

Run the Worker locally:

cp worker/wrangler.example.toml worker/wrangler.toml
cp worker/.dev.vars.example worker/.dev.vars
npm run worker:dev

The 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.

Checks

npm test
npm run build
npx tsc -p worker/tsconfig.json
npm audit --omit=dev

Production-style raw delivery smoke checks are available once you have configured Cloudflare resources:

npm run smoke:provision
npm run smoke:raw

By default, smoke fixtures use the reserved viweb-technology username. Override LISTIPS_SMOKE_USERNAME for your own deployment.

Documentation

• System design
• Project context and product rules
• Deploy to Cloudflare guide
• Performance and quota notes
• Release checklist

Cloudflare Setup

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.toml

Create 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.toml

Set 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.toml

Create the sync queue if needed:

npx wrangler queues create listips-external-sync

Deploy:

npm run worker:deploy
npm run build
npx wrangler pages deploy dist --project-name <pages-project-name>

Security

Please do not open public issues for vulnerabilities. See SECURITY.md.

Contributing

Pull requests are welcome. See CONTRIBUTING.md.