Skip to content
Merged
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
111 changes: 78 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,21 +16,38 @@ jail creates an isolated network environment for target processes, intercepting

## Quick Start

### Installation

**From GitHub Releases (Recommended):**
```bash
# Build the tool
go build -o jail .
# Download the latest release for your platform
wget https://github.com/coder/jail/releases/latest/download/jail-linux-amd64.tar.gz
tar -xzf jail-linux-amd64.tar.gz
chmod +x jail
sudo mv jail /usr/local/bin/
```

**Build from Source:**
```bash
git clone https://github.com/coder/jail
cd jail
make build # or: go build -o jail .
```

### Usage

```bash
# Allow only requests to github.com
./jail --allow "github.com" -- curl https://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 \
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
jail -- curl https://example.com
```

## Allow Rules
Expand Down Expand Up @@ -111,41 +128,41 @@ For more help: https://github.com/coder/jail

## Installation

### Prerequisites
### From GitHub Releases (Recommended)

**Linux:**
- Linux kernel 3.8+ (network namespace support)
- iptables
- Go 1.21+ (for building)
- sudo access
Download pre-built binaries from [GitHub Releases](https://github.com/coder/jail/releases):

**macOS:**
- macOS 10.15+ (Catalina or later)
- pfctl (included)
- Go 1.21+ (for building)
- sudo access
```bash
# Linux x64
wget https://github.com/coder/jail/releases/latest/download/jail-linux-amd64.tar.gz
tar -xzf jail-linux-amd64.tar.gz
chmod +x jail
sudo mv jail /usr/local/bin/

# macOS (Intel)
wget https://github.com/coder/jail/releases/latest/download/jail-darwin-amd64.tar.gz
tar -xzf jail-darwin-amd64.tar.gz
chmod +x jail
sudo mv jail /usr/local/bin/

# macOS (Apple Silicon)
wget https://github.com/coder/jail/releases/latest/download/jail-darwin-arm64.tar.gz
tar -xzf jail-darwin-arm64.tar.gz
chmod +x jail
sudo mv jail /usr/local/bin/
```

### 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:
# Using Makefile (recommended)
make build

- 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
# Or directly with Go
go build -o jail .
```

## Command-Line Options
Expand All @@ -164,15 +181,43 @@ OPTIONS:
## Development

```bash
# Build
# Build for current platform
make build

# Build for all platforms
make build-all

# Run tests
make test

# Run tests with coverage
make test-coverage

# Clean build artifacts
make clean

# Format code
make fmt

# Lint code (requires golangci-lint)
make lint
```

### Manual Commands

```bash
# Build directly with Go
go build -o jail .

# Test
# Run tests
go test ./...

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

# Use build script for all platforms
./scripts/build.sh
```

## License
Expand Down
Loading