Network isolation for networks that cannot segment themselves — with optional privacy-preserving device verification on the Midnight blockchain.
VLANs require managed switches and someone who knows how to configure them. Most homes, clinics, workshops and small offices have neither, so a compromised smart plug ends up sharing a flat broadcast domain with a NAS full of personal data.
IronGate enforces device separation on ordinary, unmanaged network hardware. It classifies every device on the LAN into a security zone and enforces that classification at the protocol level — using ARP, nftables and DHCP — with no changes to the existing switching infrastructure. It runs on a Raspberry Pi 4.
It optionally verifies device identity against the Midnight blockchain, so a network can prove a device is registered and correctly zoned without publishing what the device is. That property is the reason for choosing a privacy chain rather than a transparent one: a device registry on a public ledger is a permanent map of the hardware inside someone's home.
Implemented and active:
| Layer | What it does |
|---|---|
| nftables firewall | Zone-based rules generated from the device database; drops cross-zone traffic |
| Gateway takeover | ARP-level interception so isolated devices route through IronGate |
| ARP defense | Answers and counters ARP traffic to keep isolated devices from resolving each other |
| DHCP segmentation | dnsmasq assigns addresses and notifies the engine on every lease event |
Optional:
| Layer | Status |
|---|---|
| Layer 8 — Midnight verification | Read path implemented, write path not. Disabled by default. See below. |
Configured but NOT implemented — do not rely on these:
| Layer | Reality |
|---|---|
| IPv6 RA Guard | The ipv6_ra config flag is read and reported, but no router-advertisement guarding is performed anywhere in the engine. |
| Bypass Detection | The bypass_detection flag is reported only. No active probing is performed. |
Both flags exist in config.yaml and appear in the startup log, which previously printed ACTIVE
for them. That was misleading, so they now report ENABLED IN CONFIG, NOT IMPLEMENTED. They are
listed here rather than quietly dropped because an operator needs to know which protections are
real.
Devices are classified into one of three zones, plus optional custom device groups:
trusted— full access, never spoofed, exempt from isolation in both directions.servers— protected: IronGate actively poisons other devices' ARP caches to shield them, and firewall rules restrict their reach into the general LAN.isolated— the default for unknown devices. Cannot reach other devices on the LAN.
Custom device groups allow finer-grained policies with their own LAN-access rules.
There is no quarantine zone. Earlier documentation claimed one; the engine has never implemented
it.
The read path is implemented and tested. It queries the public Midnight indexer over HTTPS GraphQL using nothing but the Python standard library. There is no Python SDK for Midnight, and consequently no dependency, no wallet, and no key material of any kind stored on the device — which matters a great deal for software installed at a network's chokepoint.
blockchain:
enabled: false # off by default; isolation works with no blockchain at all
network: "preprod" # preprod | preview | mainnet | undeployed
contract_address: null # required when enabled
indexer_url: null # null uses the preset for the chosen network
cache_ttl: 60
fallback_allow: true # true = undecided, defer to the other layers
audit_logging: false
allow_rogue_devices: falseindexer_url is restricted. A custom value must be https:// on port 443 on one of the public Midnight
indexer hosts (indexer.preprod.midnight.network, indexer.preview.midnight.network,
indexer.mainnet.midnight.network), with no credentials, and redirects are never followed; the selected
network's own preset (for example the local undeployed node) is also accepted. Any other value is
refused by the dashboard (HTTP 400). If one is written into config.yaml by hand the engine logs a
warning and makes no Layer 8 queries at all; it does not fall back to the preset, so the misconfiguration
is visible instead of silently querying another host. With the default fallback_allow: true the layer then
reports undecided and enforcement falls through to Layers 1-7; with fallback_allow: false it fails closed
and blocks devices it cannot verify. The scheme is compared exactly (https, not HTTPS), and the dashboard
stores the trimmed value it validated.
The write path is not implemented. Registering a device on-chain requires a funded wallet and a
ZK proof server, and the published proof-server image has no confirmed aarch64 build, so it
cannot run on a Raspberry Pi. register_device, revoke_device and log_access raise
NotImplementedError with an explanatory message rather than returning a fake success.
Failure behaviour matters here. Verification is three-valued: allow, block, or undecided. When the chain cannot be reached the result is undecided and enforcement falls through to the other layers. An unreachable chain is never treated as proof that a device is trustworthy. Verification runs inside a per-packet ARP callback, so calls are bounded by a timeout and a circuit breaker.
Layer 8 targeted Algorand until July 2026. The legacy Algorand contract is retained at
src/smart_contract.py for reference and is not used by the engine; its optional build
dependencies live in requirements-legacy.txt.
IronGate went through a structured security audit in July 2026. 50 candidate findings were raised; each was then put through an adversarial verification pass that tried to refute it, which rejected 9 as unreachable or duplicated. 41 findings survived verification — 13 critical, 15 high, 10 medium, 3 low.
Disposition of those 41:
| Count | |
|---|---|
| Fixed and verified | 22 |
| Partially fixed | 2 |
| Deferred with a stated reason | 17 |
15 code changes closed those 22 findings, because several changes each closed more than one: a single YAML-escaping helper closed 7 injection findings, and rewriting the blockchain module closed 6 at once. Nothing was rolled back.
One finding is worth calling out because it cuts against the process: the verification pass rejected the blockchain fail-open, judging it unreachable. It was fixed anyway, because a reproduction test demonstrated the failure on the pre-fix code — an unreachable chain really did return "verified" and skip every other layer. Evidence outranked the judgement call.
- Command injection into shell commands from unauthenticated, user-settable values — the two entry points are now argument-escaped.
- Source and database disclosure — PHP source backups and the SQLite device database were served in full over HTTP; now blocked at the web server.
- Credential storage path removed entirely rather than guarded. A wallet recovery phrase could previously be persisted and written in plaintext into a world-readable config file. The field is gone, and secret-bearing keys are now refused on write.
- Blockchain fail-open — an unreachable chain returned "verified", silently bypassing the other layers. Verification is now three-valued, and an unreachable chain yields undecided.
- YAML injection into the generated engine config from stored settings (7 findings) — all interpolated values now go through an escaping emitter.
- Root code execution reachable by a plain GET — the update action now requires POST.
- Blockchain module hardening (6 findings) — request timeouts, a circuit breaker, a bounded and lock-protected cache, and removal of exception-swallowing bare handlers. Relevant because verification is called from inside a per-packet callback.
- Silent ARP callback failures — a bare handler hid
sendp()errors, so isolation could break with nothing in the log. - Shutdown ARP restoration aborted entirely on the first failure, leaving later devices holding a forged MAC after the daemon exited. Each device is now restored independently.
- Database lock handling — no busy timeout, so concurrent writes silently lost settings.
| Component | Finding | What was done, what remains |
|---|---|---|
| Updater / web API | Root code execution through the update path | The method restriction is in place, closing drive-by triggering. The downloaded installer is still executed without signature verification — see D6. |
| Web API | Full configuration returned without authentication | The credential field was removed entirely, so it can no longer be disclosed. The remainder of the configuration is still returned unauthenticated — see D1. |
These were identified and verified, then deliberately deferred — not missed. Each carries the specific reason. They are described by category and component; exact locations are omitted deliberately, since this repository is public and several remain live.
Critical
| # | Component | Finding | Why deferred |
|---|---|---|---|
| D1 | Web API | No authentication of any kind. Every action, including privileged ones, is accepted from any requester. | Architectural — needs a session/token system and a matching dashboard rework. Not patchable in isolation. Mitigated by binding the service to localhost and a private management interface rather than the LAN. |
| D2 | Web API | State-changing operations are reachable by simple request with no CSRF protection. | Architectural — depends on D1; tokens are meaningless without an identity to bind them to. |
| D3 | Web API | User-controlled settings are embedded into DHCP server configuration without escaping, allowing injected directives. | DHCP risk — the generator writes the config for the DHCP service the network depends on. A validation bug here takes DHCP down for every device. Requires a staged rollout with rollback. |
| D4 | Web API | The generated DHCP configuration is written with no pre-write syntax check or rollback path. | DHCP risk — same blast radius as D3, and out of the audit's permitted change surface. |
| D5 | Host configuration | The web user holds passwordless sudo for service control, so an unauthenticated request can restart services as root. | Out of scope — system-level privilege configuration was outside the audit's change surface, and the grant is load-bearing for normal operation. Meaningful only once D1 exists. |
| D6 | Updater | The installer is downloaded and executed as root with no checksum or signature verification. A repository compromise is a root compromise on every deployment. | Requires external dependency — needs a signing key, a publishing process and verification logic. Cannot be fixed by a code change alone. |
High
| # | Component | Finding | Why deferred |
|---|---|---|---|
| D7 | Web API | The automatic repair routine can forcibly kill the DHCP service, with no rate limiting. | DHCP risk — already partially mitigated by a guard that only kills a service that is not running. Removing the kill path entirely needs testing against real failure modes. |
| D8 | Web API | The service restart is backgrounded and success is reported before it has completed or been validated. | Operator decision required — changes the apply semantics the dashboard depends on; a synchronous restart alters timeout behaviour visible to users. |
| D9 | Web API | Settings writes are not error-checked, so a failed write is silently ignored. | Architectural — a correct fix is a transactional settings layer with surfaced errors, not a return-value check bolted onto the loop. |
| D10 | Engine | Shutdown ARP restoration is O(protected × LAN devices) and can exceed the service stop timeout on a large network. | Operator decision required — the fix is either a tuned stop timeout or a reduced restoration burst, and both are deployment-specific trade-offs against restoration completeness. |
| D11 | Engine | Firewall rules are staged through a predictable path in a world-writable directory before being applied, giving a time-of-check/time-of-use window. | Out of scope — the firewall application path was frozen during the audit; changing where rules are staged risks the enforcement path itself. |
| D12 | Engine | In dual-NIC mode the DHCP service is launched without any success check, so the mode can run believing DHCP is up when it is not. | Not deployed — dual-NIC mode is not in use; single-NIC is the deployed configuration. Fix alongside any dual-NIC work. |
Medium
| # | Component | Finding | Why deferred |
|---|---|---|---|
| D13 | Engine | Duplicate of D12 — the same unchecked DHCP launch, reported independently by a second reviewer. Listed rather than silently dropped, so the count reconciles. | Duplicate — resolved by D12. |
| D14 | Engine | The DHCP grace-period file is parsed without validating MAC address format; malformed entries are accepted. | Operator decision required — rejecting malformed entries changes which devices receive grace-period treatment, and a too-strict rule could isolate legitimate devices mid-DHCP. |
| D15 | Engine | Device MAC addresses from configuration are used without format validation. Command execution uses argument lists, so this is not injection, but invalid values propagate. | Operator decision required — same policy question as D14: validation strictness determines which real devices stop being protected. |
Low
| # | Component | Finding | Why deferred |
|---|---|---|---|
| D16 | Web API | The installed version identifier is returned without authentication, allowing deployed patch levels to be enumerated. | Low risk — next cycle. Depends on D1; the repository is public, so the value discloses little that is not already inferable. |
| D17 | CLI | The registration command accepts unvalidated MAC and IP input. | Now largely moot — the on-chain write path raises NotImplementedError, so no invalid data can reach a chain. Worth fixing whenever writes are implemented. |
Found after the audit concluded, so outside the 41 above:
| Severity | Component | Finding |
|---|---|---|
| High | Dashboard | The Layer 8 panel still presents a wallet recovery-phrase field and submits it over unauthenticated plain HTTP. The API now refuses to store it, so a real phrase entered here is silently discarded after already being transmitted. Do not enter a real recovery phrase. The field is stale UI from the pre-migration integration and should be removed. |
| Medium | Dashboard | The Layer 8 panel still describes the previous Algorand integration — application ID, SDK installation, funding a wallet — none of which apply to the current Midnight integration. Misleading to anyone configuring it. |
| Low | Installer | The Algorand SDK is still installed at setup. The Midnight layer needs no third-party package; only the retained legacy contract does. |
If you find something not listed here, please open an issue. Known gaps are documented rather than hidden — a security tool that misrepresents its own coverage is worse than one that does less.
Requires a Debian-based system (tested on Armbian and Debian Bookworm) with root access:
sudo bash irongate-install.shThe installer provisions dnsmasq, nginx, php-fpm, nftables, a Python virtualenv, the systemd units and the web dashboard.
Do not rename irongate-install.sh. The updater and the web UI's update action both fetch it
from this repository by that exact name.
The updater (irongate-updater.sh, run by the daily timer and by the dashboard's Update now)
installs only the commit named in a root-owned pin file and refuses to run if the downloaded
irongate-install.sh does not hash to the pinned value. It never follows main. Create
/etc/irongate/updater-pin.conf (owner root:root, mode 0644 or 0600):
PINNED_COMMIT=<40-hex commit sha you reviewed>
PINNED_INSTALLER_SHA256=<sha256 of irongate-install.sh at that commit>
Compute the hash from the reviewed commit, e.g.
git show <commit>:irongate-install.sh | sha256sum. With no pin file (or a wrong owner, mode or
hash) the updater logs the reason to /var/log/irongate-update.log and exits 1 without installing.
After merging a new release, review it and update the pin; until then the host stays on the
previously pinned commit. auto_update_enabled=false still disables scheduled runs entirely.
The installer leaves the pin file alone: it is excluded from the recursive chown of /etc/irongate, so a
genuine root:root pin keeps its owner and mode across re-installs (which the updater itself triggers),
and a file or symlink that the web tier managed to put in its place (it can write that directory) is never
promoted to root:root; the updater refuses it.
The installer also never follows a link in /etc/irongate (the web tier can write that directory, also while
the installer runs): the recursive chown -h runs with find -execdir, and config.yaml, access-control.json
and auth.json are written to a root-only staging directory (/etc/.irongate-stage) and renamed into place,
or have their owner and mode set through a hard-link pin of the existing file. A symlink, directory or other
non-regular file found at one of those names is renamed to <name>.refused.<time>.<pid> (never deleted), reported,
and treated as absent; a genuine regular file ends up with exactly the owner and mode it had before
(root:www-data, 0664 for config.yaml, 0660 for the two JSON files). find -execdir refuses to run when
PATH contains . or an empty or relative entry, so the installer sets its own fixed absolute PATH before it
does anything else.
The web tree, /var/www/irongate, belongs to www-data and gets the same care: the installer hands it over
with a small helper that opens every entry with O_NOFOLLOW and changes owner and mode of the open file, never
of a name, so a link planted there is not followed (a link, FIFO or hard-linked file inside the tree is left
alone and listed; a link, directory or extra hard link at dhcp.db stops the installer). dhcp.db is www-data:www-data 0664 (it was 0666, writable by every local user); only the web
API and root's sqlite3 (installer, updater) use it. A dhcp.db that is a symlink (for example to another
disk) is therefore no longer supported; use a bind mount.
dnsmasq runs as root and honours dhcp-script= (and conf-script=, dhcp-luascript=, conf-file=, ...) in any
file it reads, so /etc/dnsmasq.conf, /etc/dnsmasq.d and everything in it belong to root (0644/0755), not
to www-data. The web API stores the DHCP settings and reservations in the database as before; to apply them it
writes a request (data, not config) to /var/lib/irongate/dnsmasq-staged/request.json and runs
sudo /opt/irongate/dnsmasq-apply with no arguments (/etc/sudoers.d/irongate-dnsmasq-apply). The helper accepts
only the ten settings the dashboard sets (dhcp_enabled interface cidr range_start range_end gateway dns_primary dns_secondary lease_time domain) and reservations (mac ip hostname), checks every value (IPv4 literals, MAC,
RFC 1123 names, interface name, lease-time format), refuses a request that holds anything else - an unknown key, a
directive that runs a program or reads or writes a file, a newline, a NUL, an = - as a whole, renders both files
from a template in which the dhcp-script and conf-dir lines are constants, runs dnsmasq --test, replaces the
live files atomically and restarts dnsmasq, putting the previous files back if it does not start. It runs dnsmasq --test (which executes conf-script=) only after its own audit found nothing, and keeps a root-only snapshot of the last
good rendering. The installer puts the helper, its sudoers drop-in and the staging directory in place before its
permission step (which, kept as it was for the O1 tests, hands the tree to www-data for a moment) and runs
dnsmasq-apply --lockdown right after it: the directory is taken first, every file www-data could have written is read
once and scanned the way dnsmasq's own parser reads it (quotes, a directive hidden behind a 1023-character comment, CR, NUL),
and only what is clean is written back as a new root-owned file. Anything else is never re-created: its bytes go to
/var/lib/irongate/dnsmasq-quarantine (root only) and the main file and reservations.conf come back from the snapshot (or,
without one, a safe default: DHCP off, until Save & Apply renders it again). Links and special files are renamed to
.refused.*. dnsmasq-apply --audit then reads every file in /etc/dnsmasq.d, root-owned ones included (a Debian dnsmasq
reads them all), and a finding stops the installer; the EXIT trap and the installer's tail start or test dnsmasq only when
that audit passes. A root-owned operator file in /etc/dnsmasq.d is kept as it is, and audited like the rest.
What the lockdown accepts in a file www-data could have written is an allowlist, not only a list of refusals: the main
file may hold only what the helper renders, reservations.conf only dhcp-host, any other file only options dnsmasq
has. The refused directives are derived from dnsmasq's own option table (embedded in the helper, and compared with the
dnsmasq binary by the tests) by option value, so an alias that dnsmasq --help does not list - dhcp-lease, the old
name of dhcp-leasefile - is refused with it. An entry the lockdown cannot process (a read or write error, a name of 255
characters) is put aside like a link and the lockdown goes on with the others and the main file; it exits 5 if anything
could not be locked.
The updater records installed_commit only after the installer exited 0, so a failed update is tried again by
the next scheduled run instead of being reported as "Already up to date".
The installer itself stamps installed_commit only as its last step, and only with a hex commit id (or local): the
value it falls back to when GitHub cannot be reached is read from dhcp.db, which the web tier can write, so
anything else there is ignored (neither shown nor written back) instead of being pasted into a root sqlite3 statement.
The web API accepts only well-formed irongate_* settings: true/false for the layer switches, single or
dual for the mode, IPv4 addresses for the bridge address and DHCP range, and interface names of 1-15
characters from [A-Za-z0-9_.-] that do not start with - or . (the empty string means "not set"). Any other
value, and any unknown irongate_* key, is refused with HTTP 400 and nothing of that request is stored. The
engine checks the same values again before it builds the dual-NIC bridge and runs its commands without a shell.
The dashboard's Check for updates (update_check) still compares the installed commit with the newest
commit on main, so it reports "update available" whenever main is ahead of the pin. Update now and the
timer only ever install the pinned commit, so they change nothing until the pin is advanced.
- Debian-based Linux, root access
- Python 3.11+ with
venv dnsmasq,nginx,php-fpm,php-sqlite3,nftables,sqlite3- Python packages: see requirements.txt —
PyYAML,scapy,netifaces - Hardware: developed and running on a Raspberry Pi 4 (aarch64, 4 GB)
The engine reads /etc/irongate/config.yaml. That file is generated from the device database by
the web API — a hand edit is overwritten the next time configuration is applied. Manage devices and
zones through the dashboard, or via the API, not by editing YAML.
The templates the installer expands are committed under templates/ for review.
A web dashboard provides device management, zone assignment, DHCP lease inspection and diagnostics.
It is served over plain HTTP, not HTTPS, and has no authentication. The installer binds it to localhost and a private management interface rather than the LAN. Do not expose it to an untrusted network.
Unit and regression tests (24 tests, standard library unittest — no pytest required):
IRONGATE_DIR=/opt/irongate /opt/irongate/venv/bin/python tests/test_blockchain.pyEnd-to-end tests run in Docker on a network created with internal: true, so the test DHCP server
has no path to any real network:
bash docker/run-e2e.shSee docker/README.md for what the harness covers and how isolation is verified before dnsmasq is allowed to start.
irongate-install.sh Self-contained installer; source of truth (carries all code in heredocs)
src/ Engine, Midnight module, CLI, helper scripts
web/ Dashboard and management API
config/ Literal config files
templates/ Installer templates containing shell variables (not directly usable)
tests/ Unit tests and E2E checks
docker/ Isolated end-to-end test harness
tools/ heredoc_sync.py / check-sync.sh - keep src/ and the installer in agreement
docs/ Architecture notes
The installer and the extracted tree are two copies of the same code. bash tools/check-sync.sh
fails if they drift, so the duplication is checkable rather than assumed.
See CONTRIBUTING.md. The important rule: edit the heredoc in
irongate-install.sh, then run python3 tools/heredoc_sync.py --extract, so both copies stay in
agreement.
Apache License 2.0 — see LICENSE.