Mathieu Virbel
c95fca830b
Document three issues encountered during --tmpfs / isolation: symlinked system dirs on merged-usr distros, Landlock denying reads on bind-mounted /dev/null, and mandatory deny paths overriding sensitive file masks.
Greywall Documentation
Greywall is a sandboxing tool that restricts network and filesystem access for arbitrary commands. It's most useful for running semi-trusted code (package installs, build scripts, CI jobs, unfamiliar repos) with controlled side effects.
Getting Started
- Quickstart - Install greywall and run your first sandboxed command in 5 minutes
- Why Greywall - What problem it solves (and what it doesn't)
Guides
- Concepts - Mental model: OS sandbox + local proxies + config
- Troubleshooting - Common failure modes and fixes
- Using Greywall with AI agents - Defense-in-depth and policy standardization
- Recipes - Common workflows (npm/pip/git/CI)
- Templates - Copy/paste templates you can start from
Reference
- README - CLI usage
- Library Usage (Go) - Using Greywall as a Go package
- Configuration - How to configure Greywall
- Architecture - How greywall works under the hood
- Security model - Threat model, guarantees, and limitations
- Linux security features - Landlock, seccomp, eBPF details and fallback behavior
- Testing - How to run tests and write new ones
- Benchmarking - Performance overhead and profiling
Examples
See examples/ for runnable demos.
Quick Reference
Common commands
# Block all network (default)
greywall <command>
# Use custom config
greywall --settings ./greywall.json <command>
# Debug mode (verbose output)
greywall -d <command>
# Monitor mode (show blocked requests)
greywall -m <command>
# Expose port for servers
greywall -p 3000 <command>
# Run shell command
greywall -c "echo hello && ls"