Skip to content
Merged
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
48 changes: 48 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Binaries for programs and plugins
*.exe
*.exe~
*.dll
*.so
*.dylib
jail
jail.exe

# Test binary, built with `go test -c`
*.test

# Output of the go coverage tool, specifically when used with LiteIDE
*.out

# Dependency directories (remove the comment below to include it)
# vendor/

# Go workspace file
go.work

# IDE files
.vscode/
.idea/
*.swp
*.swo
*~

# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# Temporary files
*.tmp
*.temp

# Log files
*.log

# Certificate files (generated at runtime)
*.pem
*.crt
*.key
180 changes: 180 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
# jail

**Network isolation tool for monitoring and restricting HTTP/HTTPS requests from processes**

jail creates an isolated network environment for target processes, intercepting all HTTP/HTTPS traffic through a transparent proxy that enforces user-defined allow rules.

## Features

- 🔒 **Process-level network isolation** - Linux namespaces, macOS process groups
- 🌐 **HTTP/HTTPS interception** - Transparent proxy with TLS certificate injection
- 🎯 **Wildcard pattern matching** - Simple `*` wildcards for URL patterns
- 📝 **Request logging** - Monitor and log all HTTP/HTTPS requests
- 🖥️ **Cross-platform** - Native support for Linux and macOS
- ⚡ **Zero configuration** - Works out of the box with sensible defaults
- 🛡️ **Default deny-all** - Secure by default, only allow what you explicitly permit

## Quick Start

```bash
# Build the tool
go build -o jail .

# Allow only requests to github.com
./jail --allow "github.com" -- curl https://github.com

# Allow full access to GitHub issues API, but only GET/HEAD elsewhere on GitHub
./jail \
--allow "github.com/api/issues/*" \
--allow "GET,HEAD github.com" \
-- npm install

# Default deny-all: everything is blocked unless explicitly allowed
./jail -- curl https://example.com
```

## Allow Rules

jail uses simple wildcard patterns for URL matching.

### Rule Format

```text
--allow "pattern"
--allow "METHOD[,METHOD] pattern"
```

- If only a pattern is provided, all HTTP methods are allowed
- If methods are provided, only those HTTP methods are allowed (case-insensitive)
- Patterns use wildcards: `*` (matches any characters)

### Examples

```bash
# Basic patterns
jail --allow "github.com" -- git pull

# Wildcard patterns
jail --allow "*.github.com" -- npm install # GitHub subdomains
jail --allow "api.*" -- ./app # Any API domain

# Method-specific rules
jail --allow "GET,HEAD api.github.com" -- curl https://api.github.com
```

**Default Policy:** All traffic is denied unless explicitly allowed.

## Logging

```bash
# Monitor all requests with info logging
jail --log-level info --allow "*" -- npm install

# Debug logging for troubleshooting
jail --log-level debug --allow "github.com" -- git pull

# Error-only logging
jail --log-level error --allow "*" -- ./app
```

**Log Levels:**
- `error`: Shows only errors
- `warn`: Shows blocked requests and errors (default)
- `info`: Shows all requests (allowed and blocked)
- `debug`: Shows detailed information including TLS operations

## Blocked Request Messages

When a request is blocked, jail provides helpful guidance:

```
🚫 Request Blocked by Jail

Request: GET /
Host: google.com
Reason: No matching allow rules (default deny-all policy)

To allow this request, restart jail with:
--allow "google.com" # Allow all methods to this host
--allow "GET google.com" # Allow only GET requests to this host

For more help: https://github.com/coder/jail
```

## Platform Support

| Platform | Implementation | Sudo Required |
|----------|----------------|---------------|
| Linux | Network namespaces + iptables | Yes |
| macOS | Process groups + PF rules | Yes |
| Windows | Not supported | - |

## Installation

### Prerequisites

**Linux:**
- Linux kernel 3.8+ (network namespace support)
- iptables
- Go 1.21+ (for building)
- sudo access

**macOS:**
- macOS 10.15+ (Catalina or later)
- pfctl (included)
- Go 1.21+ (for building)
- sudo access

### Build from Source

```bash
git clone https://github.com/coder/jail
cd jail
go build -o jail .
```

## TLS Interception

jail automatically generates a Certificate Authority (CA) to intercept HTTPS traffic:

- CA stored in `~/.config/jail/` (or `$XDG_CONFIG_HOME/jail/`)
- CA certificate provided via `JAIL_CA_CERT` environment variable
- Certificates generated on-demand for intercepted domains
- CA expires after 1 year

### Disable TLS Interception

```bash
jail --no-tls-intercept --allow "*" -- ./app
```

## Command-Line Options

```text
jail [flags] -- command [args...]

OPTIONS:
--allow <SPEC> Allow rule (repeatable)
Format: "pattern" or "METHOD[,METHOD] pattern"
--log-level <LEVEL> Set log level (error, warn, info, debug)
--no-tls-intercept Disable HTTPS interception
-h, --help Print help
```

## Development

```bash
# Build
go build -o jail .

# Test
go test ./...

# Cross-compile
GOOS=linux GOARCH=amd64 go build -o jail-linux .
GOOS=darwin GOARCH=amd64 go build -o jail-macos .
```

## License

MIT License - see LICENSE file for details.
32 changes: 29 additions & 3 deletions go.mod
Original file line number Diff line number Diff line change
@@ -1,5 +1,31 @@
module github.com/coder/squeeze
module github.com/coder/jail

go 1.25.0
go 1.25

require golang.org/x/sys v0.35.0 // indirect
require github.com/coder/serpent v0.10.0

require (
cdr.dev/slog v1.6.2-0.20240126064726-20367d4aede6 // indirect
github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
github.com/coder/pretty v0.0.0-20230908205945-e89ba86370e0 // indirect
github.com/hashicorp/errwrap v1.1.0 // indirect
github.com/hashicorp/go-multierror v1.1.1 // indirect
github.com/kr/text v0.2.0 // indirect
github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
github.com/mattn/go-isatty v0.0.20 // indirect
github.com/mattn/go-runewidth v0.0.15 // indirect
github.com/mitchellh/go-wordwrap v1.0.1 // indirect
github.com/muesli/termenv v0.15.2 // indirect
github.com/pion/transport/v2 v2.0.0 // indirect
github.com/pion/udp v0.1.4 // indirect
github.com/rivo/uniseg v0.4.4 // indirect
github.com/spf13/pflag v1.0.5 // indirect
go.opentelemetry.io/otel v1.19.0 // indirect
go.opentelemetry.io/otel/trace v1.19.0 // indirect
golang.org/x/crypto v0.19.0 // indirect
golang.org/x/exp v0.0.0-20240213143201-ec583247a57a // indirect
golang.org/x/sys v0.17.0 // indirect
golang.org/x/term v0.17.0 // indirect
golang.org/x/xerrors v0.0.0-20231012003039-104605ab7028 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
)
Loading