ZeroIngress

Remote administration. Zero inbound exposure.

ZeroIngress is an open-source, self-hosted remote administration control plane.

Managed Nodes establish restricted outbound SSH tunnels to a Relay. Operators connect through a separately authenticated Controller path.

No inbound SSH port on the managed Node. No public per-device Relay port. No shared fleet credential. No trust-on-first-use host keys.

Built on OpenSSH, HTTPS enrollment, explicit device identity, and revocable per-device authorization.

ZeroIngress is intended only for administration of systems you own or are explicitly authorized to manage.

Why ZeroIngress

Remote administration often starts with a simple SSH port and ends with firewall exceptions, shared keys, stale access, or unclear device identity. ZeroIngress keeps managed machines off the public internet: each Node initiates an outbound reverse SSH connection to a self-hosted Relay, while the Controller renders desired authorization and verifies observed state.

The design principles are visible, constrained, revocable, and self-hosted.

Architecture

flowchart TB
  Operator[Operator] -->|zeroingress ssh office-pc| Controller[Controller]
  Controller -->|authenticated admin path| Relay[Relay]
  Node[Node] -->|Outbound Relay Tunnel| Relay
  Broker[Enrollment Broker] -->|One-Time Enrollment| Node
  Controller -->|Desired-State Authorization| Relay
  Relay -->|loopback Relay Slot| Controller

Loading

The Node initiates the connection. Relay listeners are loopback-only. Operators reach a Node through a separately authenticated Controller and Relay path.

Security Model

ZeroIngress assumes the Controller, Relay, and Node each have distinct trust boundaries. The Controller owns desired state, the Relay enforces constrained SSH capabilities, and the Node pins Relay host identity before maintaining its outbound tunnel.

Core properties:

• One-Time Enrollment over HTTPS.
• Verified Node Identity through submitted Node host and tunnel public keys.
• Strict Relay host-key verification.
• Per-Node Relay Slot authorization.
• Explicit revocation that removes desired authorization and regenerated access config.
• Health & Trust Diagnostics and an End-to-End Canary for deterministic checks.

Read THREAT_MODEL.md and docs/SECURITY-ARCHITECTURE.md before production use.

Features

• Controller registry backed by local SQLite state.
• Enrollment Broker for one-time claim receipts.
• Relay Reconciler for desired-state authorization.
• OpenSSH reverse tunnel transport.
• Windows Node bootstrap script.
• Host-key pinning for Relay and Node identity checks.
• Revocation workflow and relay-slot quarantine support.
• Deterministic public tests separated from live Relay integration tests.

Quickstart

Install from a local checkout:

python3 -m pip install .
zeroingress --help

Initialize Controller state:

zeroingress sync
zeroingress nodes

Issue a one-time enrollment:

zeroingress enroll issue --name office-pc

Windows Node Bootstrap

Configure your own trusted enrollment URL, then run PowerShell as Administrator on the Node:

$env:ZEROINGRESS_ENROLLMENT_URL = "https://enroll.example.com/zeroingress/v1/claim"
.\bootstrap\Install-ZeroIngress.ps1 -EnrollmentToken "<one-time-token>"

The bootstrap validates HTTPS, generates or validates ED25519 keys, pins the Relay host key returned by the Broker, configures OpenSSH, and maintains an outbound reverse SSH tunnel.

Controller / Relay Setup

Use examples/ as safe starting points:

• examples/controller.env.example
• examples/relay.env.example
• examples/nginx-zeroingress.example.conf
• examples/sshd-zeroingress.example.conf

Do not reuse the documentation domains or IP addresses. Replace them with Relay infrastructure you own.

One-Time Enrollment

Enrollment tokens are created by the Controller, projected to the Relay, and claimed once by a Node. Retries are accepted only for the same token and same submitted key material within the retry window.

Revocation

zeroingress revoke office-pc
zeroingress sync

Revocation removes the Node from generated access configuration and desired Relay authorization. Existing sessions should be terminated only when attribution to the target Relay Slot is safe.

Threat Model Summary

ZeroIngress reduces public exposure of managed SSH and narrows per-device relay authorization. It does not claim protection against a compromised Controller root account, compromised Relay root account, compromised Node administrator, malicious kernel, or endpoint malware.

Project Status

v0.1.0 is a Public Preview. Windows Node bootstrap is the best-tested Node path. Linux Node support is planned but not yet claimed production-ready.

Roadmap

See ROADMAP.md.

Documentation

• Quickstart
• Installation
• Architecture
• Controller
• Relay
• Node
• Enrollment
• Revocation
• Operations
• Troubleshooting
• Security Architecture
• Brand Guide

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, keep tests deterministic, and document any change to a trust boundary.

Security Reporting

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

License

Apache-2.0. See LICENSE.