Skip to content
githubhjsPublic

About

OS-enforced network restrictions for command trees. Strict on Linux, macOS, and OpenBSD; best-effort on Windows and FreeBSD.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

18 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

netless

Run a command with OS-enforced restrictions on network access. Network access is denied by default; this program has no option to turn it back on.

make
./build/netless -- curl https://example.com

For an additional Linux network-stack boundary, place netless inside a fresh Bubblewrap network namespace:

bwrap --unshare-net --bind / / --die-with-parent -- ./build/netless -- COMMAND ARGUMENTS

This requires bwrap and permission to create a network namespace. If the host or an outer container disallows namespaces, Bubblewrap fails before the target starts. The ordinary Linux backend still denies direct network syscalls in the full descendant process tree.

The command still runs. curl will fail when it tries to create a socket. Ordinary file, process, and terminal operations remain available.

On Linux, additional syscalls from the built-in table can be denied by name:

./build/netless --deny-syscall ptrace --deny-syscall mount -- COMMAND ARGUMENTS

The launcher needs the platform's native compiler and sandbox support. On Linux and macOS build with make; install with sudo make install (default /usr/local/bin). On Windows, run scripts/build-windows.ps1 from a Visual Studio Developer PowerShell.

Platform support

Platform Enforcement Architectures Status
Linux seccomp-BPF; blocks socket and io_uring syscalls x86-64, AArch64 Dynamic binaries plus static musl binaries; strict when kernel seccomp-filter support is available
macOS Seatbelt sandbox via sandbox-exec; denies network* and system-socket; descendants inherit policy Intel x86-64, Apple Silicon arm64 Implemented and CI-tested; binaries published in releases
OpenBSD pledge without inet, dns, or unix; same promises applied to exec descendants x86-64 release; other native architectures may build Implemented and tested in an OpenBSD VM; release binary available
FreeBSD Jail with IPv4/IPv6 disabled and raw sockets denied x86-64 release Best effort; requires root, leaves AF_LOCAL available, and uses the host filesystem as the jail root
Solaris / illumos, NetBSD, other Unix — — Not supported yet; no verified kernel enforcement adapter
Windows 10/11 AppContainer with no network capabilities; descendant processes inherit the container identity x86-64 and ARM64 releases; tested on Windows Server 2022 x64 and Windows 11 ARM64 Best effort; API baseline supports Windows 10/11, but Windows 10 is not yet a CI image; AppContainer also restricts filesystem, registry, and IPC access

“Unix-like” is not one portable security API. Linux, macOS, and OpenBSD use inherited kernel policies to deny network operations. FreeBSD and Windows use platform sandboxes with additional limitations; see the table above. Unsupported systems fail at build selection instead of silently falling back to an unconfined launch.

CentOS 6, 7, and 8 compatibility

Use the netless-linux-*-musl-static.tar.gz assets for CentOS and other older glibc systems. These binaries have no glibc runtime dependency, so one artifact covers the glibc versions shipped with CentOS 6/7/8 instead of publishing separate glibc builds. CI runs their network-syscall and child-inheritance probe in CentOS 6, 7, and 8 userlands.

Userspace compatibility does not override the kernel requirement. Linux seccomp filter mode and no_new_privs require a kernel with those features (upstream Linux 3.5 or newer). The stock CentOS 6 kernel is 2.6.32, so netless fails closed there and does not support network isolation on a stock CentOS 6 host. CentOS 7's 3.10 and CentOS 8's 4.18 kernel lines are new enough, subject to the kernel having seccomp filter support enabled. Container CI shares its host kernel; it verifies CentOS userland/glibc compatibility but is not evidence that a stock CentOS 6 kernel can enforce the filter.

What it enforces

  • Linux installs a seccomp-BPF filter before exec. The filter returns EPERM for socket creation and use syscalls, covering IPv4, IPv6, raw, packet, Unix-domain, and other socket families alike.
  • On x86-64, the Linux filter rejects tagged x32 calls and the legacy syscall-number range 512–547. The untagged range check is needed because kernels before Linux 5.4 incorrectly treated those numbers as x32 calls even without __X32_SYSCALL_BIT.
  • Denies io_uring setup, entry, and registration, so it cannot be used to submit socket operations through the asynchronous interface.
  • Denies pidfd_getfd and ptrace; closes inherited file descriptors above stderr; refuses to start if stdin, stdout, or stderr is a socket.
  • Sets no_new_privs before installing the filter. If setting the flag or installing the filter fails, the target command is never executed.
  • Linux filters are inherited by forked/cloned children and survive exec, as enforced by the kernel. OpenBSD applies pledge exec promises to descendants. macOS Seatbelt restrictions are inherited by child processes. Windows child processes inherit their AppContainer identity.
  • FreeBSD jails have IPv4 and IPv6 disabled and raw sockets disabled. AF_LOCAL remains available, and the jail sees the host root filesystem, so local Unix-domain sockets can reach host services that may themselves provide network access. Treat this mode as best effort only, especially for untrusted commands.
  • Windows uses a fresh AppContainer identity per launch and grants no network capabilities. The Windows kernel isolates the command and its descendants, but AppContainer also restricts filesystem, registry, and IPC access. The launcher passes only standard handles, refuses socket-backed standard handles, and does not grant loopback exemptions. Windows CI confirmed that AppContainer still allows socket creation, local binds, raw-socket creation, UDP send calls, and TCP/UDP loopback communication. Tests also probe external TCP and DNS responses. This backend therefore cannot promise syscall-level socket denial, loopback isolation, or zero packet egress. It does not install WFP filters or a custom kernel driver. Explicit per-AppContainer WFP filters would require elevated filter-management permission and are not installed by this project.

Linux, macOS, and OpenBSD deny network socket operations in the launched process tree under their OS-enforced policies. Windows AppContainer and FreeBSD jail provide best-effort isolation with the limitations described above. No backend blocks a separate privileged broker/service that independently performs network operations on request. Keep untrusted workloads away from cooperating host services and do not treat this as a full container or VM boundary.

The program does not modify firewall rules, routes, DNS configuration, network namespaces, or host networking. No root privilege is required to run it when the kernel permits an unprivileged process to set no_new_privs and seccomp filters.

Verification

make test

Tests attempt DNS resolution, IPv4/IPv6 loopback binds, outbound TCP connections, UDP sends, raw socket creation, inherited descriptor closure, and descendant process network access. Windows uses a dedicated Winsock probe and tests child-process inheritance. BSD CI runs in native virtual machines; Linux/macOS and Windows CI run on their respective hosted runners. A passing test is evidence for that specific OS image and architecture; review the code and OS configuration before relying on it in a high-assurance deployment.

Windows build and test

From a Visual Studio Developer PowerShell on Windows 10 or 11:

./scripts/build-windows.ps1
./tests/test_windows.ps1

AppContainer requires no administrator rights for the network restriction itself. Programs that need to read or execute files outside locations already accessible to AppContainer identities may need explicit ACL changes; netless does not modify those ACLs automatically. Windows CI grants read/execute access only to its disposable test directory so it can run the adversarial probe.

References

License

MIT. See LICENSE.

About

OS-enforced network restrictions for command trees. Strict on Linux, macOS, and OpenBSD; best-effort on Windows and FreeBSD.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages