Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 127 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,10 @@ atty = "0.2"
[target.'cfg(target_os = "linux")'.dependencies]
libc = "0.2"
socket2 = "0.5"
rtnetlink = "0.14"
netlink-packet-route = "0.19"
futures = "0.3"
nix = { version = "0.29", features = ["mount", "sched"] }

[dev-dependencies]
tempfile = "3.8"
Expand Down
57 changes: 57 additions & 0 deletions docs/guide/platform-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,9 @@ Full network isolation using namespaces and nftables.
- nftables (`nft` command)
- libssl-dev (for TLS)
- sudo access (for namespace creation)
- CAP_SYS_ADMIN and CAP_NET_ADMIN capabilities (automatically available with sudo, or in privileged containers)

**Note:** httpjail no longer requires the `ip` command from `iproute2`. It uses direct syscalls and netlink for all network namespace operations. This allows it to work in minimal container images (like Alpine) or container runtimes like sysbox that provide the necessary capabilities but don't include the `iproute2` package.

### How It Works

Expand All @@ -60,6 +63,39 @@ sudo httpjail --js "r.host === 'github.com'" -- curl https://api.github.com
httpjail --weak --js "r.host === 'github.com'" -- curl https://api.github.com
```

### Running Inside Containers

httpjail works inside container environments (Docker, sysbox-runc, etc.) with proper capabilities:

```bash
# Docker with privileged mode (full capabilities)
docker run --privileged --rm -it alpine:latest sh -c '
wget https://github.com/coder/httpjail/releases/latest/download/httpjail-linux-amd64 -O /usr/local/bin/httpjail
chmod +x /usr/local/bin/httpjail
apk add --no-cache nftables
httpjail --js "r.host === \"example.com\"" -- wget -qO- https://example.com
'

# sysbox-runc (provides CAP_SYS_ADMIN automatically)
docker run --runtime=sysbox-runc --rm -it alpine:latest sh -c '
wget https://github.com/coder/httpjail/releases/latest/download/httpjail-linux-amd64 -O /usr/local/bin/httpjail
chmod +x /usr/local/bin/httpjail
apk add --no-cache nftables
httpjail --js "r.host === \"example.com\"" -- wget -qO- https://example.com
'

# Or use weak mode if you don't have the necessary capabilities
httpjail --weak --js "r.host === \"example.com\"" -- wget -qO- https://example.com
```

**Requirements for strong mode in containers:**
- CAP_SYS_ADMIN capability (for network namespace operations)
- CAP_NET_ADMIN capability (for network configuration)
- `nft` binary available (nftables)
- NO need for `iproute2` package

**Note:** Weak mode (`--weak`) works in any container but only sets HTTP_PROXY/HTTPS_PROXY environment variables, so applications must respect proxy settings.

## macOS

```
Expand Down Expand Up @@ -140,3 +176,24 @@ httpjail sets these variables for the child process to trust the CA certificate:
- `NODE_EXTRA_CA_CERTS` - Node.js
- `CARGO_HTTP_CAINFO` - Cargo
- `GIT_SSL_CAINFO` - Git

## Weak Mode

Weak mode is available on all platforms and uses environment variables only:

```bash
httpjail --weak --js "r.host === 'allowed.com'" -- your-app
```

**Characteristics:**
- ✅ No root/sudo required
- ✅ Works on all platforms
- ❌ Apps must respect HTTP_PROXY/HTTPS_PROXY
- ❌ Cannot enforce policy on non-compliant apps
- ⚠️ Lower security than strong mode

**Use weak mode when:**
- You don't have root access
- Testing on macOS (default behavior)
- Working with proxy-aware applications
- Running in containers without CAP_SYS_ADMIN
Loading
Loading