monadical/greywall
Archived
13
0
Fork 0
Code Issues Pull Requests 1 Actions 2 Packages Projects Releases Wiki Activity

Improve docs organization

Browse Source
This commit is contained in:
JY Tan
2026-01-17 16:11:48 -08:00
parent 20fa647ccc
commit 5ef2ce5719
3 changed files with 377 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
README.md
View File

@@ -2,60 +2,37 @@
![GitHub Release](https://img.shields.io/github/v/release/Use-Tusk/fence)
A Go implementation of process sandboxing with network and filesystem restrictions.
Fence wraps commands in a sandbox that blocks network access by default and restricts filesystem operations based on configurable rules. It's most useful for running semi-trusted code (package installs, build scripts, CI jobs, unfamiliar repos) with controlled side effects, and it can also complement AI coding agents as defense-in-depth.
You can also think of Fence as a permission manager for your CLI coding agents.
You can also think of Fence as a permission manager for your CLI agents.
## Features
```bash
# Block all network access (default)
fence curl https://example.com # → 403 Forbidden
- **Network Isolation**: All network access blocked by default
- **Domain Allowlisting**: Configure which domains are allowed
- **Filesystem Restrictions**: Control read/write access to paths
- **Command Blocking**: Block dangerous commands (e.g., `shutdown`, `rm -rf`) with configurable deny/allow lists
- **SSH Command Filtering**: Control which hosts and commands are allowed over SSH
- **Violation Monitoring**: Real-time logging of blocked requests and sandbox denials
- **Cross-Platform**: macOS (sandbox-exec) and Linux (bubblewrap)
- **HTTP/SOCKS5 Proxies**: Built-in filtering proxies for domain control
- **Permission Import**: Using Claude Code? Import your Claude permissions as Fence configs with `fence import --claude -o ~/.fence.json`
# Allow specific domains
fence -t code npm install # → uses 'code' template with npm/pypi/etc allowed
Fence can be used as a Go package or CLI tool.
# Block dangerous commands
fence -c "rm -rf /" # → blocked by command deny rules
```
## Documentation
- [Documentation index](docs/)
- [Configuration](docs/configuration.md)
- [Security model](docs/security-model.md)
- [Architecture](ARCHITECTURE.md)
- [Examples](examples/)
## Installation
At the moment, we only support macOS and Linux. For Windows users, we recommend using WSL.
### Quick Install (Recommended)
## Install
```bash
curl -fsSL https://raw.githubusercontent.com/Use-Tusk/fence/main/install.sh | sh
```
To install a specific version:
<details>
<summary>Other installation methods</summary>
```bash
curl -fsSL https://raw.githubusercontent.com/Use-Tusk/fence/main/install.sh | sh -s -- v0.1.0
```
### Install via Go
If you have Go installed:
**Go install:**
```bash
go install github.com/Use-Tusk/fence/cmd/fence@latest
```
<details>
<summary>Build from source</summary>
**Build from source:**
```bash
git clone https://github.com/Use-Tusk/fence
@@ -69,12 +46,14 @@ go build -o fence ./cmd/fence
- `bubblewrap` (for sandboxing)
- `socat` (for network bridging)
- `bpftrace` (optional, for filesystem violation visibility with when monitoring with `-m`)
- `bpftrace` (optional, for filesystem violation visibility when monitoring with `-m`)
## Quick Start
## Usage
### Basic
```bash
# This will be blocked (no domains allowed by default)
# Run command with all network blocked (no domains allowed by default)
fence curl https://example.com
# Run with shell expansion
@@ -82,116 +61,60 @@ fence -c "echo hello && ls"
# Enable debug logging
fence -d curl https://example.com
```
For a more detailed introduction, see the [Quickstart Guide](docs/quickstart.md).
# Use a template
fence -t code -- claude # Runs Claude Code using `code` template config
## CLI Usage
```text
fence [flags] -- [command...]
Flags:
-c string Run command string directly (like sh -c)
-d, --debug Enable debug logging (shows sandbox command, proxy activity, filter rules)
-m, --monitor Monitor mode (shows blocked requests and violations only)
-p, --port Expose port for inbound connections (can be repeated)
-s, --settings Path to settings file (default: ~/.fence.json)
-t, --template Use built-in template (e.g., code, local-dev-server)
-v, --version Show version information
-h, --help Help for fence
Subcommands:
import Import settings from other tools (e.g., --claude for Claude Code)
```
### Examples
```bash
# Block all network (default behavior)
fence curl https://example.com
# Output: curl: (56) CONNECT tunnel failed, response 403
# Use a built-in template
fence -t code -- claude
# Extend a template in your config (adds private registry to 'code' template)
# ~/.fence.json: {"extends": "code", "network": {"allowedDomains": ["private.company.com"]}}
fence npm install
# Use a custom config
fence --settings ./my-config.json npm install
# Block specific commands (via config file)
# ~/.fence.json: {"command": {"deny": ["git push", "npm publish"]}}
fence -c "git push" # blocked
fence -c "git status" # allowed
# Run a shell command
fence -c "git clone https://github.com/user/repo && cd repo && npm install"
# Debug mode shows proxy activity
fence -d wget https://example.com
# Monitor mode shows violations/blocked requests only
# Monitor mode (shows violations)
fence -m npm install
# Expose a port for inbound connections
fence -p 3000 -c "npm run dev"
# Import settings from Claude Code
fence import --claude -o .fence.json
# Show all commands and options
fence --help
```
## Library Usage
### Configuration
```go
package main
Fence reads from `~/.fence.json` by default:
import (
"fmt"
"github.com/Use-Tusk/fence/pkg/fence"
)
func main() {
// Check if platform supports sandboxing (macOS/Linux)
if !fence.IsSupported() {
fmt.Println("Sandboxing not supported on this platform")
return
}
// Create config
cfg := &fence.Config{
Network: fence.NetworkConfig{
AllowedDomains: []string{"api.example.com"},
},
Filesystem: fence.FilesystemConfig{
AllowWrite: []string{"."},
},
Command: fence.CommandConfig{
Deny: []string{"git push", "npm publish"},
},
}
// Create manager (debug=false, monitor=false)
manager := fence.NewManager(cfg, false, false)
defer manager.Cleanup()
// Initialize (starts proxies)
if err := manager.Initialize(); err != nil {
panic(err)
}
// Wrap a command
wrapped, err := manager.WrapCommand("curl https://api.example.com/data")
if err != nil {
panic(err)
}
fmt.Println("Sandboxed command:", wrapped)
```json
{
"extends": "code",
"network": { "allowedDomains": ["private.company.com"] },
"filesystem": { "allowWrite": ["."] },
"command": { "deny": ["git push", "npm publish"] }
}
```
Use `fence --settings ./custom.json` to specify a different config.
### Import from Claude Code
```bash
fence import --claude -o ~/.fence.json
```
## Features
- **Network isolation** - All outbound blocked by default; allowlist domains via config
- **Filesystem restrictions** - Control read/write access paths
- **Command blocking** - Deny dangerous commands like `rm -rf /`, `git push`
- **SSH Command Filtering** - Control which hosts and commands are allowed over SSH
- **Built-in templates** - Pre-configured rulesets for common workflows
- **Violation monitoring** - Real-time logging of blocked requests (`-m`)
- **Cross-platform** - macOS (sandbox-exec) + Linux (bubblewrap)
Fence can be used as a Go package or CLI tool.
## Documentation
- [Index](/docs/README.md)
- [Quickstart Guide](docs/quickstart.md)
- [Configuration Reference](docs/configuration.md)
- [Security Model](docs/security-model.md)
- [Architecture](ARCHITECTURE.md)
- [Library Usage (Go)](docs/library.md)
- [Examples](examples/)
## Attribution
This project was inspired by Anthropic's [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime).
Inspired by Anthropic's [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime).