{"id":51499989,"url":"https://github.com/ek-mc/mini-firewall","last_synced_at":"2026-07-07T17:01:41.153Z","repository":{"id":355014924,"uuid":"1182045797","full_name":"ek-mc/mini-firewall","owner":"ek-mc","description":"Minimal cron-based anti-flood firewall guard (ipset + iptables) for Linux servers","archived":false,"fork":false,"pushed_at":"2026-06-02T03:49:38.000Z","size":28,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T05:22:11.736Z","etag":null,"topics":["cron","ddos","firewall","ipset","iptables","linux","security"],"latest_commit_sha":null,"homepage":"https://github.com/ek-mc/mini-firewall","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ek-mc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T00:53:55.000Z","updated_at":"2026-06-02T03:49:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ek-mc/mini-firewall","commit_stats":null,"previous_names":["ek-mc/mini-firewall"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ek-mc/mini-firewall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek-mc%2Fmini-firewall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek-mc%2Fmini-firewall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek-mc%2Fmini-firewall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek-mc%2Fmini-firewall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ek-mc","download_url":"https://codeload.github.com/ek-mc/mini-firewall/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ek-mc%2Fmini-firewall/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35235818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cron","ddos","firewall","ipset","iptables","linux","security"],"created_at":"2026-07-07T17:01:40.321Z","updated_at":"2026-07-07T17:01:41.146Z","avatar_url":"https://github.com/ek-mc.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mini-firewall\n\nMinimal cron-based anti-flood firewall guard for Linux servers using **ipset + iptables** (IPv4 and IPv6).\n\n\u003e Designed to block obvious abusive connection bursts with short temporary bans and automatic escalation to persistent blocks for repeat offenders.\n\n## Status\n- Version: **v0.4.0**\n- License: MIT\n- Latest release: https://github.com/ek-mc/mini-firewall/releases/latest\n\n## Features\n- Runs every minute via cron.\n- Scans active TCP connections to protected ports (default: `80,443`).\n- Bans high-connection public IPs via `ipset` + `iptables` (IPv4) and `ip6tables` (IPv6).\n- Uses **native ipset timeout** for auto-unban (default: 15 minutes).\n- **Repeat-offender escalation**: IPs banned `BAN_ESCALATE_THRESHOLD` (default: 3) times within `ESCALATE_WINDOW_SECONDS` (default: 24 h) are moved to a persistent blocklist with no expiry.\n- Supports **whitelist** file to skip trusted IPs.\n- Supports `--dry-run` mode.\n- Supports `--status` mode.\n- Supports `--metrics` mode and writes Prometheus-style snapshot to `/var/lib/ddos-guard/metrics.prom`.\n- Optional webhook alerts on ban events via `ALERT_WEBHOOK_URL` env var.\n- Logs actions to `/var/log/ddos-guard.log`.\n\n## Files\n- `ddos-guard.sh` — main detection/ban script.\n- `install-cron.sh` — install helper script.\n- `uninstall.sh` — uninstall helper script.\n- `CHANGELOG.md` — release notes.\n- `VERSION` — current version.\n\n## Default behavior\n- Protected ports: `80,443`\n- Threshold per IP: `120`\n- Ban time: `900s`\n- Escalation threshold: `3` bans within `86400s` (24 h) → persistent block\n\nYou can change these at the top of `ddos-guard.sh`:\n- `PROTECTED_PORTS`\n- `THRESHOLD_PER_IP`\n- `BAN_SECONDS`\n- `BAN_ESCALATE_THRESHOLD` — number of bans in the window before persistent block (default: `3`)\n- `ESCALATE_WINDOW_SECONDS` — rolling window for repeat-offender counting (default: `86400` = 24 h)\n\n## IPv6 support\nIPv6 blocking is enabled automatically when `ip6tables` is available. Two additional ipsets are created:\n- `ddos_block6` — temporary IPv6 bans (same TTL as IPv4)\n- `ddos_persistent6` — persistent IPv6 bans for repeat offenders\n\nIf `ip6tables` is not installed, IPv6 blocking is silently skipped.\n\n## Whitelist\nFile: `/etc/ddos-guard/whitelist.txt`\n\nAdd one trusted public IP per line (IPv4 or IPv6), for example:\n```txt\n1.2.3.4\n2001:db8::1\n```\n\n## Optional webhook alerts\nSet an environment variable before running script (or in cron wrapper):\n```bash\nexport ALERT_WEBHOOK_URL=\"https://example.com/webhook\"\n```\n\n## Install Guide\n\n### 1) Clone repository\n```bash\ngit clone https://github.com/ek-mc/mini-firewall.git\ncd mini-firewall\n```\n\n### 2) Install dependencies\n- Requires Linux with:\n  - `ipset`\n  - `iptables`\n  - `ip6tables` (optional, for IPv6 blocking)\n  - `ss` (from `iproute2`)\n  - `flock` (from `util-linux`)\n\nOn Debian/Ubuntu:\n```bash\nsudo apt-get update\nsudo apt-get install -y ipset iptables ip6tables iproute2 util-linux\n```\n\n### 3) Configure thresholds (optional)\nEdit `ddos-guard.sh`:\n- `PROTECTED_PORTS`\n- `THRESHOLD_PER_IP`\n- `BAN_SECONDS`\n- `BAN_ESCALATE_THRESHOLD`\n- `ESCALATE_WINDOW_SECONDS`\n\n### 4) Install cron job\n```bash\nsudo bash install-cron.sh\n```\n\n### 5) Verify\n```bash\nsudo crontab -l | grep ddos-guard.sh\nsudo tail -n 50 /var/log/ddos-guard.log\nsudo bash ddos-guard.sh --status\n```\n\n### 6) Dry run test\n```bash\nsudo bash ddos-guard.sh --dry-run\n```\n\n### 7) Metrics snapshot\n```bash\nsudo bash ddos-guard.sh --metrics\ncat /var/lib/ddos-guard/metrics.prom\n```\n\n### 8) Uninstall (if needed)\n```bash\nsudo bash uninstall.sh\n```\n\n## Logs and state\n- Log file: `/var/log/ddos-guard.log`\n- Lock file: `/var/run/ddos-guard.lock`\n- Whitelist: `/etc/ddos-guard/whitelist.txt`\n- Stats file: `/var/lib/ddos-guard/stats.env`\n- Metrics file: `/var/lib/ddos-guard/metrics.prom`\n- Offender records: `/var/lib/ddos-guard/offenders/`\n\n## Notes (important)\n- This is a minimal defensive script, **not** a full DDoS platform.\n- For production WordPress/high traffic setups, pair with:\n  - Nginx `limit_req/limit_conn`\n  - fail2ban\n  - CDN/WAF controls\n- Test carefully to avoid blocking legitimate traffic.\n\n## Changelog\nSee [CHANGELOG.md](CHANGELOG.md).\n\n## License\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fek-mc%2Fmini-firewall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fek-mc%2Fmini-firewall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fek-mc%2Fmini-firewall/lists"}