|
| 1 | +# jail |
| 2 | + |
| 3 | +**Network isolation tool for monitoring and restricting HTTP/HTTPS requests from processes** |
| 4 | + |
| 5 | +jail creates an isolated network environment for target processes, intercepting all HTTP/HTTPS traffic through a transparent proxy that enforces user-defined allow rules. |
| 6 | + |
| 7 | +## Features |
| 8 | + |
| 9 | +- 🔒 **Process-level network isolation** - Linux namespaces, macOS process groups |
| 10 | +- 🌐 **HTTP/HTTPS interception** - Transparent proxy with TLS certificate injection |
| 11 | +- 🎯 **Wildcard pattern matching** - Simple `*` wildcards for URL patterns |
| 12 | +- 📝 **Request logging** - Monitor and log all HTTP/HTTPS requests |
| 13 | +- 🖥️ **Cross-platform** - Native support for Linux and macOS |
| 14 | +- ⚡ **Zero configuration** - Works out of the box with sensible defaults |
| 15 | +- 🛡️ **Default deny-all** - Secure by default, only allow what you explicitly permit |
| 16 | + |
| 17 | +## Quick Start |
| 18 | + |
| 19 | +```bash |
| 20 | +# Build the tool |
| 21 | +go build -o jail . |
| 22 | + |
| 23 | +# Allow only requests to github.com |
| 24 | +./jail --allow "github.com" -- curl https://github.com |
| 25 | + |
| 26 | +# Allow full access to GitHub issues API, but only GET/HEAD elsewhere on GitHub |
| 27 | +./jail \ |
| 28 | + --allow "github.com/api/issues/*" \ |
| 29 | + --allow "GET,HEAD github.com" \ |
| 30 | + -- npm install |
| 31 | + |
| 32 | +# Default deny-all: everything is blocked unless explicitly allowed |
| 33 | +./jail -- curl https://example.com |
| 34 | +``` |
| 35 | + |
| 36 | +## Allow Rules |
| 37 | + |
| 38 | +jail uses simple wildcard patterns for URL matching. |
| 39 | + |
| 40 | +### Rule Format |
| 41 | + |
| 42 | +```text |
| 43 | +--allow "pattern" |
| 44 | +--allow "METHOD[,METHOD] pattern" |
| 45 | +``` |
| 46 | + |
| 47 | +- If only a pattern is provided, all HTTP methods are allowed |
| 48 | +- If methods are provided, only those HTTP methods are allowed (case-insensitive) |
| 49 | +- Patterns use wildcards: `*` (matches any characters) |
| 50 | + |
| 51 | +### Examples |
| 52 | + |
| 53 | +```bash |
| 54 | +# Basic patterns |
| 55 | +jail --allow "github.com" -- git pull |
| 56 | + |
| 57 | +# Wildcard patterns |
| 58 | +jail --allow "*.github.com" -- npm install # GitHub subdomains |
| 59 | +jail --allow "api.*" -- ./app # Any API domain |
| 60 | + |
| 61 | +# Method-specific rules |
| 62 | +jail --allow "GET,HEAD api.github.com" -- curl https://api.github.com |
| 63 | +``` |
| 64 | + |
| 65 | +**Default Policy:** All traffic is denied unless explicitly allowed. |
| 66 | + |
| 67 | +## Logging |
| 68 | + |
| 69 | +```bash |
| 70 | +# Monitor all requests with info logging |
| 71 | +jail --log-level info --allow "*" -- npm install |
| 72 | + |
| 73 | +# Debug logging for troubleshooting |
| 74 | +jail --log-level debug --allow "github.com" -- git pull |
| 75 | + |
| 76 | +# Error-only logging |
| 77 | +jail --log-level error --allow "*" -- ./app |
| 78 | +``` |
| 79 | + |
| 80 | +**Log Levels:** |
| 81 | +- `error`: Shows only errors |
| 82 | +- `warn`: Shows blocked requests and errors (default) |
| 83 | +- `info`: Shows all requests (allowed and blocked) |
| 84 | +- `debug`: Shows detailed information including TLS operations |
| 85 | + |
| 86 | +## Blocked Request Messages |
| 87 | + |
| 88 | +When a request is blocked, jail provides helpful guidance: |
| 89 | + |
| 90 | +``` |
| 91 | +🚫 Request Blocked by Jail |
| 92 | +
|
| 93 | +Request: GET / |
| 94 | +Host: google.com |
| 95 | +Reason: No matching allow rules (default deny-all policy) |
| 96 | +
|
| 97 | +To allow this request, restart jail with: |
| 98 | + --allow "google.com" # Allow all methods to this host |
| 99 | + --allow "GET google.com" # Allow only GET requests to this host |
| 100 | +
|
| 101 | +For more help: https://github.com/coder/jail |
| 102 | +``` |
| 103 | + |
| 104 | +## Platform Support |
| 105 | + |
| 106 | +| Platform | Implementation | Sudo Required | |
| 107 | +|----------|----------------|---------------| |
| 108 | +| Linux | Network namespaces + iptables | Yes | |
| 109 | +| macOS | Process groups + PF rules | Yes | |
| 110 | +| Windows | Not supported | - | |
| 111 | + |
| 112 | +## Installation |
| 113 | + |
| 114 | +### Prerequisites |
| 115 | + |
| 116 | +**Linux:** |
| 117 | +- Linux kernel 3.8+ (network namespace support) |
| 118 | +- iptables |
| 119 | +- Go 1.21+ (for building) |
| 120 | +- sudo access |
| 121 | + |
| 122 | +**macOS:** |
| 123 | +- macOS 10.15+ (Catalina or later) |
| 124 | +- pfctl (included) |
| 125 | +- Go 1.21+ (for building) |
| 126 | +- sudo access |
| 127 | + |
| 128 | +### Build from Source |
| 129 | + |
| 130 | +```bash |
| 131 | +git clone https://github.com/coder/jail |
| 132 | +cd jail |
| 133 | +go build -o jail . |
| 134 | +``` |
| 135 | + |
| 136 | +## TLS Interception |
| 137 | + |
| 138 | +jail automatically generates a Certificate Authority (CA) to intercept HTTPS traffic: |
| 139 | + |
| 140 | +- CA stored in `~/.config/jail/` (or `$XDG_CONFIG_HOME/jail/`) |
| 141 | +- CA certificate provided via `JAIL_CA_CERT` environment variable |
| 142 | +- Certificates generated on-demand for intercepted domains |
| 143 | +- CA expires after 1 year |
| 144 | + |
| 145 | +### Disable TLS Interception |
| 146 | + |
| 147 | +```bash |
| 148 | +jail --no-tls-intercept --allow "*" -- ./app |
| 149 | +``` |
| 150 | + |
| 151 | +## Command-Line Options |
| 152 | + |
| 153 | +```text |
| 154 | +jail [flags] -- command [args...] |
| 155 | +
|
| 156 | +OPTIONS: |
| 157 | + --allow <SPEC> Allow rule (repeatable) |
| 158 | + Format: "pattern" or "METHOD[,METHOD] pattern" |
| 159 | + --log-level <LEVEL> Set log level (error, warn, info, debug) |
| 160 | + --no-tls-intercept Disable HTTPS interception |
| 161 | + -h, --help Print help |
| 162 | +``` |
| 163 | + |
| 164 | +## Development |
| 165 | + |
| 166 | +```bash |
| 167 | +# Build |
| 168 | +go build -o jail . |
| 169 | + |
| 170 | +# Test |
| 171 | +go test ./... |
| 172 | + |
| 173 | +# Cross-compile |
| 174 | +GOOS=linux GOARCH=amd64 go build -o jail-linux . |
| 175 | +GOOS=darwin GOARCH=amd64 go build -o jail-macos . |
| 176 | +``` |
| 177 | + |
| 178 | +## License |
| 179 | + |
| 180 | +MIT License - see LICENSE file for details. |
0 commit comments