ghaziwali/hulios

Purpose and entry points

Hulios is a Linux-only, eBPF-powered transparent Tor gateway. It redirects outbound TCP and DNS through embedded Arti Tor and a local Hickory resolver while enforcing leak-resistant routing at kernel boundaries. The workspace root is Cargo.toml; the primary executable is hulios/src/main.rs, with build-time eBPF integration in hulios/build.rs. Operational commands include start, stop, status, diagnose, and recovery.

Supervisor, configuration, and privilege boundary

The privileged supervisor initializes configuration, validates required privileges, manages lifecycle signals, installs kernel controls, and spawns the restricted worker process. It is the boundary between host-root operations and the unprivileged runtime.

• hulios/src/main.rs

• hulios/src/config.rs

• hulios/src/privileges.rs

• hulios/src/signals.rs

Persistent state and lifecycle orchestration

hulios-state owns the durable model of whether Hulios is active, snapshots preexisting system state, executes lifecycle transitions, and supports recovery after crashes. Start establishes protection before service operation; stop restores captured state; recover handles unclean or interrupted runs. Diagnostics, watchdog, time synchronization, and status expose and validate operational health.

• hulios-state/src/operations/start.rs

• hulios-state/src/operations/stop.rs

• hulios-state/src/operations/recover.rs

• hulios-state/src/snapshot.rs

• hulios-state/src/watchdog.rs

Kernel enforcement and routing boundary

The eBPF subsystem provides the non-bypassable traffic boundary: cgroup socket hooks steer traffic, DNS filtering handles query interception, socket marks support policy routing, and an LSM-oriented AF_PACKET blocker prevents raw packet socket bypasses. The privileged process loads these programs; policy routing and blackhole defaults remain fail-secure if the daemon dies.

• hulios-ebpf/src/main.rs

• hulios-ebpf/src/dns_filter.rs

• hulios-ebpf/src/sock_mark.rs

• hulios-ebpf/src/af_packet_block.rs

• hulios/src/ebpf.rs

DNS interception and resolver path

DNS traffic is detected and redirected to a localized resolver rather than relying on runtime resolv.conf changes. The DNS crate contains resolver behavior plus rebinding protections, making DNS a dedicated security boundary alongside TCP interception.

• hulios-dns/src/resolver.rs

• hulios-dns/src/detect.rs

• hulios-dns/src/rebinding.rs

Tor transport and worker-facing network services

The onion networking layer hosts the local SOCKS-facing path over embedded Arti. Isolation controls separate Tor stream behavior, while MSS handling adapts tunneled traffic. This layer receives traffic after kernel interception and provides the outbound Tor transport rather than delegating to an external Tor daemon.

• hulios-onionmasq/src/lib.rs

• hulios-onionmasq/src/socks.rs

• hulios-onionmasq/src/isolation.rs

• hulios-onionmasq/src/mss.rs

Host integration and runtime dependencies

Hulios targets Linux kernel 5.10+ with BPF syscall, BPF LSM, and cgroups v2 support; eBPF compilation requires clang/libelf and is wired through hulios-ebpf/build.rs. Network compatibility code integrates with systemd, NetworkManager, and IWD and detects conflicts. Tunnel and sysctl functionality support host network setup.

• hulios-netcompat/src/systemd.rs

• hulios-netcompat/src/network_manager.rs

• hulios-netcompat/src/iwd.rs

• hulios-tun/src/lib.rs

• packaging/hulios.service