Skip to content

Commit b089883

Browse files
ammarioclaude
ammario
and
claude
committed
docs: Reorganize documentation structure for better clarity
- Move CLI options to first-level in User Guide for easier access - Create comprehensive Rule Engines section with overview and trade-offs - Add detailed Line Processor documentation with examples - Update Configuration page to be a holistic overview - Reorganize SUMMARY.md for improved navigation flow The new structure better separates concerns: - CLI reference is immediately accessible - Rule engines have dedicated section explaining all three options - Configuration overview ties everything together 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 2ec1517 commit b089883

4 files changed

Lines changed: 663 additions & 34 deletions

File tree

‎docs/SUMMARY.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,20 @@
66

77
- [Installation](./guide/installation.md)
88
- [Quick Start](./guide/quick-start.md)
9+
- [Command Line Options](./reference/cli.md)
910
- [Configuration](./guide/configuration.md)
11+
- [Rule Engines](./guide/rule-engines.md)
1012
- [JavaScript Rules](./guide/javascript-rules.md)
1113
- [Shell Scripts](./guide/shell-scripts.md)
12-
- [Request Logging](./guide/request-logging.md)
14+
- [Line Processor](./guide/line-processor.md)
15+
- [Request Logging](./guide/request-logging.md)
1316
- [Platform Support](./guide/platform-support.md)
1417
- [Linux](./guide/linux.md)
1518
- [macOS](./guide/macos.md)
1619
- [Security](./guide/security.md)
1720

1821
# Reference
1922

20-
- [Command Line Options](./reference/cli.md)
2123
- [Environment Variables](./reference/environment.md)
2224
- [JavaScript API](./reference/javascript-api.md)
2325
- [Exit Codes](./reference/exit-codes.md)

‎docs/guide/configuration.md‎

Lines changed: 139 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,159 @@
11
# Configuration
22

3-
httpjail can be configured through command-line options and environment variables.
3+
httpjail's behavior can be configured through command-line options, environment variables, and configuration files. This page provides an overview of how these work together.
44

5-
## Command Line Options
5+
## Configuration Hierarchy
66

7-
### Core Options
7+
httpjail follows a simple configuration hierarchy:
88

9-
- `--js <EXPR>` - JavaScript expression to evaluate requests
10-
- `--js-file <PATH>` - JavaScript file to evaluate requests
11-
- `--sh <PATH>` - Shell script to evaluate requests
12-
- `--request-log <PATH>` - Log all requests to file
13-
- `--weak` - Use weak mode (environment variables only, no network isolation)
9+
1. **Command-line options** - Highest priority, override everything
10+
2. **Environment variables** - Set by httpjail for the jailed process
11+
3. **Default behavior** - Deny all requests unless explicitly allowed
1412

15-
### Advanced Options
13+
## Key Configuration Areas
1614

17-
- `--timeout <SECONDS>` - Command timeout (default: no timeout)
18-
- `--server` - Run in server mode
19-
- `--address <ADDR>` - Proxy address (default: 127.0.0.1:0)
20-
- `--no-jail-cleanup` - Don't clean up jail on exit (for debugging)
15+
### Rule Engine Selection
2116

22-
## Rule Evaluation
17+
Choose how requests are evaluated:
2318

24-
Rules are evaluated in the following order:
25-
1. JavaScript expression (`--js`)
26-
2. JavaScript file (`--js-file`)
27-
3. Shell script (`--sh`)
28-
4. Default: deny all
19+
- **JavaScript** (`--js` or `--js-file`) - Fast, sandboxed evaluation
20+
- **Shell Script** (`--sh`) - System integration, external tools
21+
- **Line Processor** (`--proc`) - Stateful, streaming evaluation
2922

30-
Only one rule type can be active at a time.
23+
Only one rule engine can be active at a time. See [Rule Engines](./rule-engines.md) for detailed comparison.
3124

32-
## Logging
25+
### Network Mode
3326

34-
Request logs follow the format:
27+
Control the isolation level:
28+
29+
- **Strong mode** (default on Linux) - Full network namespace isolation
30+
- **Weak mode** (`--weak`) - Environment variables only, no isolation
31+
- **Server mode** (`--server`) - Run as standalone proxy server
32+
33+
### Logging and Monitoring
34+
35+
Track what's happening:
36+
37+
- **Request logging** (`--request-log`) - Log all HTTP requests
38+
- **Debug output** (`RUST_LOG=debug`) - Detailed operational logs
39+
- **Process output** - Captured from the jailed command
40+
41+
See [Request Logging](./request-logging.md) for details.
42+
43+
## Common Configurations
44+
45+
### Development Environment
46+
47+
```bash
48+
# Allow localhost and common dev services
49+
httpjail --js "['localhost', '127.0.0.1'].includes(r.host)" \
50+
--request-log /dev/stdout \
51+
-- npm run dev
3552
```
36-
<timestamp> <+|-> <METHOD> <URL>
53+
54+
### CI/CD Pipeline
55+
56+
```bash
57+
# Strict allow-list for builds
58+
httpjail --js-file ci-rules.js \
59+
--request-log build-network.log \
60+
--timeout 600 \
61+
-- make build
3762
```
3863

39-
Where:
40-
- `+` indicates allowed request
41-
- `-` indicates blocked request
64+
### Production Service
65+
66+
```bash
67+
# Stateful filtering with monitoring
68+
httpjail --proc ./rate-limiter.py \
69+
--request-log /var/log/httpjail/requests.log \
70+
-- ./api-server
71+
```
4272

4373
## Environment Variables
4474

45-
httpjail sets the following environment variables in the jailed process:
75+
### Set by httpjail
76+
77+
These are automatically set in the jailed process:
78+
79+
| Variable | Description | Example |
80+
|----------|-------------|---------|
81+
| `HTTP_PROXY` | HTTP proxy address | `http://127.0.0.1:34567` |
82+
| `HTTPS_PROXY` | HTTPS proxy address | `http://127.0.0.1:34567` |
83+
| `SSL_CERT_FILE` | CA certificate path | `/tmp/httpjail-ca.pem` |
84+
| `SSL_CERT_DIR` | CA certificate directory | `/tmp/httpjail-certs/` |
85+
| `NO_PROXY` | Bypass proxy for these hosts | `localhost,127.0.0.1` |
86+
87+
### Controlling httpjail
88+
89+
These affect httpjail's behavior:
90+
91+
| Variable | Description | Example |
92+
|----------|-------------|---------|
93+
| `RUST_LOG` | Logging level | `debug`, `info`, `warn`, `error` |
94+
| `HTTPJAIL_CA_CERT` | Custom CA certificate path | `/etc/pki/custom-ca.pem` |
95+
96+
## Platform-Specific Configuration
97+
98+
### Linux
99+
100+
- Uses network namespaces for strong isolation
101+
- Requires root/sudo for namespace operations
102+
- iptables rules for traffic redirection
103+
- Supports all network modes
104+
105+
### macOS
106+
107+
- Limited to weak mode (environment variables)
108+
- No root required for standard operation
109+
- Certificate trust via Keychain Access
110+
- Some apps may ignore proxy variables
111+
112+
See [Platform Support](./platform-support.md) for detailed information.
113+
114+
## Configuration Best Practices
115+
116+
1. **Start simple**: Begin with basic JavaScript rules
117+
2. **Log everything in dev**: Use `--request-log /dev/stdout` during development
118+
3. **Test isolation**: Verify no requests leak through
119+
4. **Monitor performance**: Watch for slow rule evaluation
120+
5. **Document rules**: Keep rule logic clear and maintainable
121+
122+
## Troubleshooting Configuration
123+
124+
### Rules not matching
125+
126+
```bash
127+
# Debug rule evaluation
128+
RUST_LOG=debug httpjail --js "r.host === 'example.com'" -- curl https://example.com
129+
130+
# Log all requests to see what's being evaluated
131+
httpjail --request-log /dev/stderr --js "false" -- your-app
132+
```
133+
134+
### Environment variables not working
135+
136+
```bash
137+
# Check what's set in the jail
138+
httpjail --js "true" -- env | grep -E "(HTTP|PROXY|SSL)"
139+
140+
# Verify proxy is listening
141+
httpjail --js "true" -- curl -I http://127.0.0.1:$PROXY_PORT
142+
```
143+
144+
### Certificate issues
145+
146+
```bash
147+
# Trust the CA certificate
148+
httpjail trust --install
149+
150+
# Check certificate details
151+
openssl x509 -in ~/.config/httpjail/ca-cert.pem -text -noout
152+
```
46153

47-
- `HTTP_PROXY` - Proxy address for HTTP requests
48-
- `HTTPS_PROXY` - Proxy address for HTTPS requests
49-
- `SSL_CERT_FILE` - Path to CA certificate for HTTPS interception
50-
- `SSL_CERT_DIR` - Directory containing CA certificate
154+
## Next Steps
51155

52-
These ensure most applications automatically use httpjail's proxy.
156+
- [Command Line Options](../reference/cli.md) - Complete CLI reference
157+
- [Rule Engines](./rule-engines.md) - Choose the right evaluation method
158+
- [Request Logging](./request-logging.md) - Monitor and audit requests
159+
- [Platform Support](./platform-support.md) - Platform-specific details

0 commit comments

Comments
 (0)