# ghaziwali/hulios architecture

> Architecture diagram of the GitHub repository ghaziwali/hulios, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ghaziwali/hulios
- Repository: https://github.com/ghaziwali/hulios

## Overview

#### 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`

Main entry points: [`hulios/src/main.rs`](https://github.com/ghaziwali/hulios/blob/main/hulios/src/main.rs) (Hulios supervisor), [`hulios-state/src/operations/start.rs`](https://github.com/ghaziwali/hulios/blob/main/hulios-state/src/operations/start.rs) (Start / stop / recover), [`hulios-ebpf/src/main.rs`](https://github.com/ghaziwali/hulios/blob/main/hulios-ebpf/src/main.rs) (eBPF programs), [`hulios-dns/src/resolver.rs`](https://github.com/ghaziwali/hulios/blob/main/hulios-dns/src/resolver.rs) (Local DNS resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_supervisor["Privileged Supervisor"]
  node_main["Hulios supervisor<br/>Rust executable<br/>[main.rs]"]
  node_config["Configuration<br/>Rust module<br/>[config.rs]"]
  node_privileges["Privilege checks<br/>Rust module<br/>[privileges.rs]"]
  node_signals["Lifecycle signals<br/>Rust module<br/>[signals.rs]"]
  node_ebpf_loader["eBPF loader<br/>Rust module<br/>[ebpf.rs]"]
end

subgraph group_state["Lifecycle State"]
  node_lifecycle["Start / stop / recover<br/>lifecycle operations<br/>[start.rs]"]
  node_snapshot[("System snapshot<br/>durable state<br/>[snapshot.rs]")]
  node_watchdog["Watchdog and status<br/>operational health<br/>[watchdog.rs]"]
end

subgraph group_kernel["Kernel Enforcement"]
  node_ebpf_programs{{"eBPF programs<br/>kernel programs<br/>[main.rs]"}}
  node_dns_filter["DNS filter<br/>eBPF program<br/>[dns_filter.rs]"]
  node_sock_mark["Socket marking<br/>eBPF program<br/>[sock_mark.rs]"]
  node_af_packet["AF_PACKET blocker<br/>BPF LSM program<br/>[af_packet_block.rs]"]
  node_policy_routing{{"Fail-secure policy routing<br/>host routing policy"}}
end

subgraph group_worker["Restricted Network Worker"]
  node_dns_resolver["Local DNS resolver<br/>Hickory resolver<br/>[resolver.rs]"]
  node_dns_detection["DNS detection<br/>DNS interception logic<br/>[detect.rs]"]
  node_rebinding["Rebinding protection<br/>DNS security policy<br/>[rebinding.rs]"]
  node_onionmasq["Embedded Arti transport<br/>Tor network service<br/>[lib.rs]"]
  node_socks["SOCKS ingress<br/>local proxy<br/>[socks.rs]"]
  node_isolation["Stream isolation<br/>Tor policy<br/>[isolation.rs]"]
end

subgraph group_host["Host Integration"]
  node_netcompat["Network compatibility<br/>host integration<br/>[systemd.rs]"]
  node_tunnel["Tunnel setup<br/>host networking<br/>[lib.rs]"]
  node_systemd_service["systemd service<br/>service unit<br/>[hulios.service]"]
end

node_main -->|"loads"| node_config
node_main -->|"validates"| node_privileges
node_main -->|"handles"| node_signals
node_main -->|"orchestrates"| node_lifecycle
node_lifecycle -->|"captures / restores"| node_snapshot
node_lifecycle -->|"reports health"| node_watchdog
node_main -->|"loads via"| node_ebpf_loader
node_ebpf_loader -->|"attaches"| node_ebpf_programs
node_ebpf_programs -->|"includes"| node_dns_filter
node_ebpf_programs -->|"includes"| node_sock_mark
node_ebpf_programs -->|"includes"| node_af_packet
node_sock_mark -->|"drives"| node_policy_routing
node_lifecycle -->|"installs"| node_policy_routing
node_dns_filter -->|"redirects DNS to"| node_dns_resolver
node_dns_resolver -->|"uses"| node_dns_detection
node_dns_resolver -->|"enforces"| node_rebinding
node_policy_routing -->|"steers TCP to"| node_socks
node_socks -->|"forwards to"| node_onionmasq
node_onionmasq -->|"applies"| node_isolation
node_main -->|"coordinates"| node_netcompat
node_lifecycle -->|"configures"| node_tunnel
node_systemd_service -->|"starts"| node_main

click node_main "https://github.com/ghaziwali/hulios/blob/main/hulios/src/main.rs"
click node_config "https://github.com/ghaziwali/hulios/blob/main/hulios/src/config.rs"
click node_privileges "https://github.com/ghaziwali/hulios/blob/main/hulios/src/privileges.rs"
click node_signals "https://github.com/ghaziwali/hulios/blob/main/hulios/src/signals.rs"
click node_ebpf_loader "https://github.com/ghaziwali/hulios/blob/main/hulios/src/ebpf.rs"
click node_lifecycle "https://github.com/ghaziwali/hulios/blob/main/hulios-state/src/operations/start.rs"
click node_snapshot "https://github.com/ghaziwali/hulios/blob/main/hulios-state/src/snapshot.rs"
click node_watchdog "https://github.com/ghaziwali/hulios/blob/main/hulios-state/src/watchdog.rs"
click node_ebpf_programs "https://github.com/ghaziwali/hulios/blob/main/hulios-ebpf/src/main.rs"
click node_dns_filter "https://github.com/ghaziwali/hulios/blob/main/hulios-ebpf/src/dns_filter.rs"
click node_sock_mark "https://github.com/ghaziwali/hulios/blob/main/hulios-ebpf/src/sock_mark.rs"
click node_af_packet "https://github.com/ghaziwali/hulios/blob/main/hulios-ebpf/src/af_packet_block.rs"
click node_dns_resolver "https://github.com/ghaziwali/hulios/blob/main/hulios-dns/src/resolver.rs"
click node_dns_detection "https://github.com/ghaziwali/hulios/blob/main/hulios-dns/src/detect.rs"
click node_rebinding "https://github.com/ghaziwali/hulios/blob/main/hulios-dns/src/rebinding.rs"
click node_onionmasq "https://github.com/ghaziwali/hulios/blob/main/hulios-onionmasq/src/lib.rs"
click node_socks "https://github.com/ghaziwali/hulios/blob/main/hulios-onionmasq/src/socks.rs"
click node_isolation "https://github.com/ghaziwali/hulios/blob/main/hulios-onionmasq/src/isolation.rs"
click node_netcompat "https://github.com/ghaziwali/hulios/blob/main/hulios-netcompat/src/systemd.rs"
click node_tunnel "https://github.com/ghaziwali/hulios/blob/main/hulios-tun/src/lib.rs"
click node_systemd_service "https://github.com/ghaziwali/hulios/blob/main/packaging/hulios.service"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config,node_privileges,node_signals,node_ebpf_loader toneBlue
class node_lifecycle,node_snapshot,node_watchdog toneAmber
class node_ebpf_programs,node_dns_filter,node_sock_mark,node_af_packet,node_policy_routing toneMint
class node_dns_resolver,node_dns_detection,node_rebinding,node_onionmasq,node_socks,node_isolation toneRose
class node_netcompat,node_tunnel,node_systemd_service toneIndigo
```

## Components

### Privileged Supervisor

Host-root control plane.

- [Hulios supervisor](https://github.com/ghaziwali/hulios/blob/main/hulios/src/main.rs): Rust executable · Validates host readiness and manages the restricted worker. · `hulios/src/main.rs`
- [Configuration](https://github.com/ghaziwali/hulios/blob/main/hulios/src/config.rs): Rust module · `hulios/src/config.rs`
- [Privilege checks](https://github.com/ghaziwali/hulios/blob/main/hulios/src/privileges.rs): Rust module · `hulios/src/privileges.rs`
- [Lifecycle signals](https://github.com/ghaziwali/hulios/blob/main/hulios/src/signals.rs): Rust module · `hulios/src/signals.rs`
- [eBPF loader](https://github.com/ghaziwali/hulios/blob/main/hulios/src/ebpf.rs): Rust module · Loads kernel programs from the privileged boundary. · `hulios/src/ebpf.rs`

### Lifecycle State

Durable activation and recovery.

- [Start / stop / recover](https://github.com/ghaziwali/hulios/blob/main/hulios-state/src/operations/start.rs): lifecycle operations · Establishes protection before service operation and restores host state. · `hulios-state/src/operations/start.rs`
- [System snapshot](https://github.com/ghaziwali/hulios/blob/main/hulios-state/src/snapshot.rs): durable state · Captures preexisting host state for restoration. · `hulios-state/src/snapshot.rs`
- [Watchdog and status](https://github.com/ghaziwali/hulios/blob/main/hulios-state/src/watchdog.rs): operational health · `hulios-state/src/watchdog.rs`

### Kernel Enforcement

Fail-secure traffic boundary.

- [eBPF programs](https://github.com/ghaziwali/hulios/blob/main/hulios-ebpf/src/main.rs): kernel programs · Cgroup hooks, DNS interception, socket marks, and AF_PACKET blocking. · `hulios-ebpf/src/main.rs`
- [DNS filter](https://github.com/ghaziwali/hulios/blob/main/hulios-ebpf/src/dns_filter.rs): eBPF program · `hulios-ebpf/src/dns_filter.rs`
- [Socket marking](https://github.com/ghaziwali/hulios/blob/main/hulios-ebpf/src/sock_mark.rs): eBPF program · Marks sockets for policy routing. · `hulios-ebpf/src/sock_mark.rs`
- [AF_PACKET blocker](https://github.com/ghaziwali/hulios/blob/main/hulios-ebpf/src/af_packet_block.rs): BPF LSM program · Prevents raw packet socket bypasses. · `hulios-ebpf/src/af_packet_block.rs`
- **Fail-secure policy routing**: host routing policy · Blackhole defaults remain active if the daemon fails.

### Restricted Network Worker

Local DNS and Tor services.

- [Local DNS resolver](https://github.com/ghaziwali/hulios/blob/main/hulios-dns/src/resolver.rs): Hickory resolver · Applies DNS detection and rebinding protections. · `hulios-dns/src/resolver.rs`
- [DNS detection](https://github.com/ghaziwali/hulios/blob/main/hulios-dns/src/detect.rs): DNS interception logic · `hulios-dns/src/detect.rs`
- [Rebinding protection](https://github.com/ghaziwali/hulios/blob/main/hulios-dns/src/rebinding.rs): DNS security policy · `hulios-dns/src/rebinding.rs`
- [Embedded Arti transport](https://github.com/ghaziwali/hulios/blob/main/hulios-onionmasq/src/lib.rs): Tor network service · Provides local SOCKS-facing outbound Tor transport. · `hulios-onionmasq/src/lib.rs`
- [SOCKS ingress](https://github.com/ghaziwali/hulios/blob/main/hulios-onionmasq/src/socks.rs): local proxy · `hulios-onionmasq/src/socks.rs`
- [Stream isolation](https://github.com/ghaziwali/hulios/blob/main/hulios-onionmasq/src/isolation.rs): Tor policy · `hulios-onionmasq/src/isolation.rs`

### Host Integration

Linux and network-manager integration.

- [Network compatibility](https://github.com/ghaziwali/hulios/blob/main/hulios-netcompat/src/systemd.rs): host integration · Coordinates systemd, NetworkManager, and IWD. · `hulios-netcompat/src/systemd.rs`
- [Tunnel setup](https://github.com/ghaziwali/hulios/blob/main/hulios-tun/src/lib.rs): host networking · `hulios-tun/src/lib.rs`
- [systemd service](https://github.com/ghaziwali/hulios/blob/main/packaging/hulios.service): service unit · `packaging/hulios.service`

## Connections

- Hulios supervisor → Configuration: loads
- Hulios supervisor → Privilege checks: validates
- Hulios supervisor → Lifecycle signals: handles
- Hulios supervisor → Start / stop / recover: orchestrates
- Start / stop / recover → System snapshot: captures / restores
- Start / stop / recover → Watchdog and status: reports health
- Hulios supervisor → eBPF loader: loads via
- eBPF loader → eBPF programs: attaches
- eBPF programs → DNS filter: includes
- eBPF programs → Socket marking: includes
- eBPF programs → AF_PACKET blocker: includes
- Socket marking → Fail-secure policy routing: drives
- Start / stop / recover → Fail-secure policy routing: installs
- DNS filter → Local DNS resolver: redirects DNS to
- Local DNS resolver → DNS detection: uses
- Local DNS resolver → Rebinding protection: enforces
- Fail-secure policy routing → SOCKS ingress: steers TCP to
- SOCKS ingress → Embedded Arti transport: forwards to
- Embedded Arti transport → Stream isolation: applies
- Hulios supervisor → Network compatibility: coordinates
- Start / stop / recover → Tunnel setup: configures
- systemd service → Hulios supervisor: starts