{"id":51408805,"url":"https://github.com/unknown0152/nft-firewall-public","last_synced_at":"2026-07-04T13:01:25.317Z","repository":{"id":364852819,"uuid":"1269469381","full_name":"unknown0152/nft-firewall-public","owner":"unknown0152","description":"Secure-by-default nftables firewall and WireGuard killswitch manager for Debian, with Docker isolation, watchdog health checks, and operational tooling.","archived":false,"fork":false,"pushed_at":"2026-06-22T15:40:04.000Z","size":348,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T16:14:41.475Z","etag":null,"topics":["cosmos-cloud","debian","docker","firewall","keybase","killswitch","linux","nftables","python","security","systemd","vpn","wireguard"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unknown0152.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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-06-14T18:50:25.000Z","updated_at":"2026-06-22T15:41:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/unknown0152/nft-firewall-public","commit_stats":null,"previous_names":["unknown0152/nft-firewall-public"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/unknown0152/nft-firewall-public","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown0152%2Fnft-firewall-public","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown0152%2Fnft-firewall-public/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown0152%2Fnft-firewall-public/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown0152%2Fnft-firewall-public/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unknown0152","download_url":"https://codeload.github.com/unknown0152/nft-firewall-public/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown0152%2Fnft-firewall-public/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35122497,"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-04T02:00:05.987Z","response_time":113,"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":["cosmos-cloud","debian","docker","firewall","keybase","killswitch","linux","nftables","python","security","systemd","vpn","wireguard"],"created_at":"2026-07-04T13:01:24.667Z","updated_at":"2026-07-04T13:01:25.299Z","avatar_url":"https://github.com/unknown0152.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nft-firewall\n\n`nft-firewall` is a low-level nftables firewall manager for Debian systems that\nneed a strict WireGuard killswitch, default-drop input policy, Docker isolation,\nhealth checks, and operator tooling.\n\nThis project is intended for experienced Linux operators. It manages nftables\nrules directly and can affect host connectivity. Review generated rules before\napplying them, keep an out-of-band recovery path, and do not deploy it on a\nproduction host without understanding the local network topology.\n\n## Current Status\n\nThis repository is a public-safe source export from a real operational\ndeployment. The code, tests, systemd templates, and operator docs are included,\nbut live host configuration, runtime state, logs, backup artifacts, and private\nhistory are intentionally excluded.\n\nThe curl bootstrap path has been tested on a clean Debian 13 systemd VM. The\ntested path installs the core firewall tooling, deploys systemd units, installs\nCosmos as an optional standalone service, and validates ruleset generation. A\nreal WireGuard interface is still required before applying the production\nkillswitch policy on a real host.\n\n## Features\n\n- nftables ruleset generation with a default-drop input posture.\n- WireGuard-oriented egress controls and killswitch health checks.\n- IPv6 hard-drop killswitch support.\n- Docker isolation when Docker is configured not to manage iptables itself.\n- Dynamic nftables sets for block, trusted, and GeoIP-style source lists.\n- Watchdog, listener, SSH alert, metrics, and report systemd templates.\n- Optional Keybase notification and ChatOps integration.\n- Local developer checks through Ruff, ShellCheck, and pytest.\n\n## Public Repository Scope\n\nThis public repository intentionally excludes live host data. Do not commit:\n\n- `config/firewall.ini`\n- runtime state under `state/` or `/var/lib/nft-firewall/`\n- generated `/etc/nftables.conf` copies\n- audit logs or other logs\n- backup bundles, runtime-state tarballs, and local archives\n- `.venv/`, caches, and test artifacts\n\nUse [config/firewall.ini.example](config/firewall.ini.example) as the starting\npoint for local configuration. Real interface names, LAN ranges, VPN endpoints,\nSSH ports, Keybase identifiers, and service-specific values belong only in a\nprivate deployment config.\n\n## Quick Install\n\nTarget: Debian 13 with systemd and console or out-of-band recovery access.\nRun this only after reviewing whether the default package and service changes\nfit the target host.\n\nGuided install. Paste one command, choose the install type, then the installer\nclones the public Git repository, prints the exact checked-out commit, and runs\n`fw doctor` plus `fw simulate` automatically:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash\n```\n\nThe guided menu offers:\n\n```text\nExisting install detected:\n1) Update only (code, wrappers, units, restart, validate)\n2) Re-run guided install\n\nFresh install:\n1) Core firewall only\n2) Cosmos/media server (Docker + dashboard)\n3) Full server (Cosmos + Docker + dashboard + Keybase package)\n4) Full server + interactive Keybase login\n```\n\nFor automation, skip the menu with a mode flag:\n\n```bash\n# Update existing install only, no config wizard\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --update\n\n# Update existing install and offer/launch Keybase login if needed\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --update --with-keybase-login\n\n# Core firewall only\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --core\n\n# Cosmos/media server\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --cosmos\n\n# Full server\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --full\n\n# Full server with interactive Keybase login\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --full-login\n```\n\nTo apply firewall rules during the same run, choose it in the guided installer\nor add `--safe-apply`. This still uses safe mode and requires typing `CONFIRM`,\nso a bad SSH paste rolls back:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --full-login --safe-apply\n```\n\nThe curl entrypoint prints normally and also writes a root-only install log under\n`/var/log/nft-firewall/install-*.log` for troubleshooting. The raw GitHub file is\nonly a small entrypoint; it clones `https://github.com/unknown0152/nft-firewall-public.git`\nand runs `setup.sh` from that checkout so the installer uses a real Git ref\ninstead of chaining multiple raw GitHub downloads. By default it checks out\n`main`; override with `NFT_FIREWALL_REF`, `NFT_FIREWALL_BRANCH`, or\n`NFT_FIREWALL_REPO_URL` when testing a branch, tag, commit, or fork.\n\nFor a verbose debug install log, keep all flags on the same shell command:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh \\\n  | sudo NFT_FIREWALL_INSTALL_LOG=/root/nft-firewall-install-debug.log NFT_FIREWALL_DEBUG=1 bash -s -- --full-login\n```\n\nAdvanced flags are still available for custom combinations:\n\n```bash\n--with-integrations --with-docker --with-keybase --with-keybase-login --with-webui\n--validate --no-validate --safe-apply --profile cosmos-vpn-secure\n```\n\nManual validation remains available any time:\n\n```bash\nsudo fw doctor cosmos-vpn-secure\nsudo fw simulate cosmos-vpn-secure\nsudo fw safe-apply cosmos-vpn-secure\n```\n\n## Uninstall\n\nNormal uninstall removes nft-firewall/Cosmos files, systemd units, sudo wrappers,\nruntime users, and the live nftables ruleset. It preserves `/etc/wireguard/*.conf`\nand system packages, including Keybase and Docker:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --uninstall\n```\n\nFor scripted reinstall testing, add `--yes`:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --uninstall --yes\n```\n\nKeybase removal is intentionally separate because it deletes the local Keybase\npackage and account state for the configured `[keybase] linux_user`:\n\n```bash\n# Remove nft-firewall/Cosmos and also purge Keybase package/local state\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --uninstall --with-keybase\n\n# Only purge Keybase package/local state\ncurl -fsSL https://raw.githubusercontent.com/unknown0152/nft-firewall-public/main/install.sh | sudo bash -s -- --keybase-only\n```\n\nThe optional integration path installs Cosmos as a standalone service and keeps\nCosmos config/storage under `/srv`. The `--with-docker` path installs Docker\nEngine from Docker's Debian repository only after writing `/etc/docker/daemon.json`\nwith `iptables=false`, `ip6tables=false`, and `data-root=/srv/docker`, so\nnft-firewall remains the firewall authority.\n\nThe `--with-keybase` path installs the Keybase Linux package and detects the\nconfigured Linux user from `[keybase] linux_user`. During install or update, the\ncore installer now tries to start that user's Keybase service with\n`run_keybase -g` before deciding ChatOps units are unavailable. The\n`--with-keybase-login` path additionally launches the interactive\n`keybase login` prompt as that Linux user when a login is still needed. After\nlogging in, re-run the installer with `--update` or run `fw keybase-test` to\nverify notifications.\n\nClean-VM validation covered the installer path without Keybase or a real\nWireGuard provider. Cosmos starts without Docker, but container management\nrequires Docker to be installed and reachable by Cosmos.\n\n## Read-Only Web Dashboard\n\nThe optional `nft-webui.service` listens only on `127.0.0.1:8787` and exposes a\nread-only live dashboard plus `/api/status` and `/api/dashboard`. The dashboard\npolls local health, CPU, memory, disk, network throughput, service states, and\nconfigured open ports. It does not provide firewall mutation buttons or write\nendpoints.\n\nUse Cosmos Cloud as the public access layer: create a Cosmos route/proxy to\n`http://127.0.0.1:8787` and require Cosmos login/authentication on that route.\nDo not expose `nft-webui.service` directly to the public network.\n\n## Repository Structure\n\n- `src/core/` contains ruleset generation, state persistence, and validation.\n- `src/daemons/` contains watchdog, listener, knockd, and SSH alert daemons.\n- `src/integrations/` contains Docker, GeoIP, and threat-feed helpers.\n- `src/utils/` contains shared formatting, metrics, Keybase, and validation\n  utilities.\n- `systemd/` contains service and timer templates.\n- `scripts/` contains local operator and maintenance helpers.\n- `tests/unit/` contains the unit and invariant test suite.\n- `docs/` contains operational maintenance and migration notes.\n\n## Development Checks\n\nThe local check entrypoint is:\n\n```bash\nmake check\n```\n\nIt runs Ruff when available, ShellCheck when available, and the unit test suite.\nRuff is intentionally configured narrowly so it catches high-signal undefined\nname errors without imposing broad style churn.\n\nOptional local tooling can be installed into a project `.venv`:\n\n```bash\nmake venv\nmake check\n```\n\nThe `.venv` is for development checks only. Runtime services do not depend on\nit.\n\n## Operational Notes\n\nThe docs under [docs/](docs/) describe maintenance workflows such as local\nchange tracking, zero-downtime validation, and backup/export handling. They are\noperator guidance, not a substitute for reviewing the generated nftables policy\non the target host.\n\nBefore applying generated firewall changes on a real host, use the project\ndoctor, health, and nftables syntax checks appropriate for that deployment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funknown0152%2Fnft-firewall-public","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funknown0152%2Fnft-firewall-public","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funknown0152%2Fnft-firewall-public/lists"}