- Notifications
You must be signed in to change notification settings - Fork1
coder/boundary
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Network isolation tool for monitoring and restricting HTTP/HTTPS requests from processes.
boundary creates an isolated network environment for target processes, intercepting HTTP/HTTPS traffic through a transparent proxy that enforces user-defined allow rules.
- Process-level network isolation (Linux namespaces)
- HTTP/HTTPS interception with transparent proxy and TLS certificate injection
- Wildcard pattern matching for URL patterns
- Request logging and monitoring
- Linux support
- Default deny-all security model
curl -fsSL https://raw.githubusercontent.com/coder/boundary/main/install.sh| bashFor installation options, manual installation, and release details, seeRELEASES.md.
Buildboundary from source:
# Clone the repositorygit clone https://github.com/coder/boundary.gitcd boundary# Build the binarymake build# Install binary and wrapper script (optional)sudo cp boundary /usr/local/bin/sudo cp scripts/boundary-wrapper.sh /usr/local/bin/boundary-runsudo chmod +x /usr/local/bin/boundary-run
Requirements:
- Go 1.24 or later
- Linux
The recommended way to runboundary is using theboundary-run shortcut, which handles privilege escalation automatically. Theboundary-run wrapper is installed automatically when you use the installation script:
# After installation, use the shortcut:boundary-run --allow"domain=github.com" -- curl https://github.comboundary-run -- bash
Note: If you installed
boundarymanually, you can install the wrapper script separately:sudo cp scripts/boundary-wrapper.sh /usr/local/bin/boundary-runsudo chmod +x /usr/local/bin/boundary-run
If you prefer to runboundary directly, you'll need to handle privilege escalation:
# Note: sys_admin is only needed in restricted environments (e.g., Docker with seccomp).# If boundary works without it on your system, you can remove +sys_admin from both flags.sudo -E env PATH=$PATH setpriv \ --reuid=$(id -u) \ --regid=$(id -g) \ --clear-groups \ --inh-caps=+net_admin,+sys_admin \ --ambient-caps=+net_admin,+sys_admin \ boundary --allow"domain=github.com" -- curl https://github.com
# Allow only requests to github.comboundary-run --allow"domain=github.com" -- curl https://github.com# Allow full access to GitHub issues API, but only GET/HEAD elsewhere on GitHubboundary-run \ --allow"domain=github.com path=/api/issues/*" \ --allow"method=GET,HEAD domain=github.com" \ -- npm install# Default deny-all: everything is blocked unless explicitly allowedboundary-run -- curl https://example.com
--allow "key=value [key=value ...]"Keys:
method- HTTP method(s), comma-separated (GET, POST, etc.)domain- Domain/hostname patternpath- URL path pattern(s), comma-separated
boundary-run --allow"domain=github.com" -- git pullboundary-run --allow"domain=*.github.com" -- npm install# GitHub subdomainsboundary-run --allow"method=GET,HEAD domain=api.github.com" -- curl https://api.github.comboundary-run --allow"method=POST domain=api.example.com path=/users,/posts" -- ./app# Multiple pathsboundary-run --allow"path=/api/v1/*,/api/v2/*" -- curl https://api.example.com/api/v1/users
Wildcards:* matches any characters. All traffic is denied unless explicitly allowed.
boundary-run --log-level warn --allow"domain=github.com" -- git pull# Default: only logs denied requestsboundary-run --log-level info --allow"method=*" -- npm install# Show all requestsboundary-run --log-level debug --allow"domain=github.com" -- git pull# Debug info
Log Levels:error,warn (default),info,debug
| Platform | Implementation | Privileges |
|---|---|---|
| Linux | Network namespaces + iptables | CAP_NET_ADMIN (or root) |
| macOS | Not supported | - |
| Windows | Not supported | - |
All processes are expected to run as non-root users for security best practices:
- boundary-parent: The main boundary process that sets up network isolation
- boundary-child: The child process created within the network namespace
- target/agent process: The command you're running (e.g.,
curl,npm,bash)
Theboundary-run wrapper script handles privilege escalation automatically usingsetpriv to drop privileges before launching boundary. This ensures all processes run with the minimum required capabilities (CAP_NET_ADMIN and optionallyCAP_SYS_ADMIN for restricted environments) while executing as your regular user account.
If you runboundary directly withsudo (withoutsetpriv), all processes will run as root, which isnot recommended for security reasons. Always useboundary-run or the equivalentsetpriv command shown in theDirect Usage section.
boundary-run [flags] -- command [args...] --config <PATH> Path to YAML config file (default: ~/.config/coder_boundary/config.yaml) --allow <SPEC> Allow rule (repeatable). Merged with allowlist from config file --log-level <LEVEL> Set log level (error, warn, info, debug). Default: warn --log-dir <DIR> Directory to write logs to (default: stderr) --proxy-port <PORT> HTTP proxy port (default: 8080) --pprof Enable pprof profiling server --pprof-port <PORT> pprof server port (default: 6060) -h, --help Print helpEnvironment variables:BOUNDARY_CONFIG,BOUNDARY_ALLOW,BOUNDARY_LOG_LEVEL,BOUNDARY_LOG_DIR,PROXY_PORT,BOUNDARY_PPROF,BOUNDARY_PPROF_PORT
make build# Build for current platformmake build-all# Build for all platformsmaketest# Run testsmake test-coverage# Run tests with coveragemake clean# Clean build artifactsmake fmt# Format codemake lint# Lint code
For detailed information about howboundary works internally, seeARCHITECTURE.md.
MIT License - see LICENSE file for details.
About
Resources
Code of conduct
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Contributors6
Uh oh!
There was an error while loading.Please reload this page.