WIP

Author: ammario

README.md

@@ -6,40 +6,21 @@
 
 - [Installation](./guide/installation.md)
 - [Quick Start](./guide/quick-start.md)
-- [Command Line Options](./reference/cli.md)
 - [Configuration](./guide/configuration.md)
 - [Rule Engines](./guide/rule-engines/index.md)
   - [JavaScript](./guide/rule-engines/javascript.md)
   - [Shell](./guide/rule-engines/shell.md)
   - [Line Processor](./guide/rule-engines/line-processor.md)
-- [Request Logging](./guide/request-logging.md)
 - [Platform Support](./guide/platform-support.md)
-  - [Linux](./guide/linux.md)
-  - [macOS](./guide/macos.md)
-- [Security](./guide/security.md)
-
-# Reference
-
-- [Environment Variables](./reference/environment.md)
-- [JavaScript API](./reference/javascript-api.md)
-- [Exit Codes](./reference/exit-codes.md)
+- [Request Logging](./guide/request-logging.md)
 
 # Advanced
 
-- [Architecture](./advanced/architecture.md)
 - [TLS Interception](./advanced/tls-interception.md)
-- [Network Namespaces](./advanced/network-namespaces.md)
-- [DNS Protection](./advanced/dns-protection.md)
+- [DNS Exfiltration](./advanced/dns-protection.md)
 - [Server Mode](./advanced/server-mode.md)
 
-# Development
-
-- [Building from Source](./development/building.md)
-- [Testing](./development/testing.md)
-- [Contributing](./development/contributing.md)
-- [CI/CD](./development/ci-cd.md)
-
 ---
 
 [Security Policy](./security-policy.md)
-[License](./license.md)
+[License](./license.md)

docs/SUMMARY.md

@@ -1 +1,66 @@
-# DNS Protection
+# DNS Exfiltration
+
+httpjail prevents DNS exfiltration attacks by intercepting all DNS queries in isolated environments.
+
+## The Attack
+
+Malicious code can exfiltrate sensitive data by encoding it in DNS queries:
+
+- `secret-data.attacker.com`
+- `env-var-contents.evil.com`
+- `api-key-12345.tunnel.io`
+
+These queries reach public DNS servers even when HTTP/HTTPS traffic is blocked.
+
+## How Protection Works
+
+In Linux strong mode, httpjail:
+
+1. **Intercepts all DNS queries** from the jailed process
+2. **Returns dummy response** (6.6.6.6) for every query
+3. **Prevents external DNS access** - queries never reach public resolvers
+4. **Maintains HTTP/HTTPS functionality** through transparent proxy redirection
+
+## Traffic Flow
+
+```mermaid
+sequenceDiagram
+    participant J as Jailed Process
+    participant S as Jail Server
+    participant D as Public DNS Resolvers
+
+    Note over J,D: DNS Exfiltration Attempt
+    J->>S: DNS Query: secret-data.attacker.com
+    S-->>J: Response: 6.6.6.6 (dummy)
+    Note over S,D: ❌ Query never reaches public resolvers
+
+    Note over J,D: Blocked HTTP Flow
+    J->>S: HTTP GET http://blocked.com
+    Note over S: Rule evaluation: denied
+    S-->>J: 403 Forbidden
+    Note over S,D: ❌ No DNS resolution needed
+
+    Note over J,D: Allowed HTTP Flow
+    J->>S: HTTP GET http://example.com
+    Note over S: Rule evaluation: allowed
+    S->>D: DNS Query: example.com (only if needed)
+    D-->>S: Real IP address
+    S->>S: Forward to upstream server
+    S-->>J: HTTP response
+```
+
+The diagram shows three scenarios:
+
+1. **DNS Exfiltration Prevention**: All DNS queries receive dummy response, never reaching public resolvers
+2. **Blocked HTTP Traffic**: Requests denied by rules without any DNS resolution
+3. **Allowed HTTP Traffic**: Only when rules permit, httpjail performs actual DNS resolution
+
+## Platform Support
+
+- **Linux (Strong Mode)**: Full DNS interception and protection
+- **macOS (Weak Mode)**: No DNS interception - applications resolve normally
+- **Windows**: Planned
+
+## Why 6.6.6.6?
+
+The choice of 6.6.6.6 is arbitrary - any non-lookback IP would work.

docs/advanced/dns-protection.md

@@ -1 +1,23 @@
 # Server Mode
+
+Run httpjail as a standalone proxy server without executing any commands. Useful for proxying multiple applications through the same httpjail instance.
+
+The server binds to localhost (127.0.0.1) by default for security.
+
+```bash
+# Start server with default ports (8080 for HTTP, 8443 for HTTPS) on localhost
+httpjail --server --js "true"
+
+# Start server with custom ports using environment variables
+HTTPJAIL_HTTP_BIND=3128 HTTPJAIL_HTTPS_BIND=3129 httpjail --server --js "true"
+
+# Bind to all interfaces (use with caution - exposes proxy to network)
+HTTPJAIL_HTTP_BIND=0.0.0.0:8080 HTTPJAIL_HTTPS_BIND=0.0.0.0:8443 httpjail --server --js "true"
+
+# Configure your applications to use the proxy:
+export HTTP_PROXY=http://localhost:8080
+export HTTPS_PROXY=http://localhost:8443
+curl https://github.com  # This request will go through httpjail
+```
+
+**Note**: In server mode, httpjail does not create network isolation. Applications must be configured to use the proxy via environment variables or application-specific proxy settings.

docs/advanced/server-mode.md

@@ -1 +1,52 @@
 # TLS Interception
+
+httpjail intercepts HTTPS traffic using a locally-generated Certificate Authority (CA) to inspect and filter encrypted requests.
+
+## How It Works
+
+1. **CA Generation**: On first run, httpjail creates a unique CA keypair
+2. **Certificate Storage**: CA files are stored in your config directory:
+   - Linux: `~/.config/httpjail/`
+   - macOS: `~/Library/Application Support/httpjail/`
+   - Windows: `%APPDATA%\httpjail\` (planned)
+3. **Process Trust**: The jailed process trusts the CA via environment variables
+4. **Per-Host Certificates**: Each HTTPS connection gets a certificate signed by the httpjail CA
+5. **No System Changes**: Your system trust store is never modified
+
+## Certificate Trust
+
+httpjail sets these environment variables for the child process:
+
+- `SSL_CERT_FILE` / `SSL_CERT_DIR` - OpenSSL and most tools
+- `CURL_CA_BUNDLE` - curl
+- `REQUESTS_CA_BUNDLE` - Python requests
+- `NODE_EXTRA_CA_CERTS` - Node.js
+- `CARGO_HTTP_CAINFO` - Cargo
+- `GIT_SSL_CAINFO` - Git
+
+## Platform Differences
+
+### Linux (Strong Mode)
+
+- Transparently redirects TCP port 443 to the proxy
+- Extracts SNI from TLS ClientHello
+- No application cooperation needed
+
+### macOS (Weak Mode)
+
+- Uses `HTTP_PROXY`/`HTTPS_PROXY` environment variables
+- HTTPS negotiated via CONNECT method
+- Applications must respect proxy settings
+
+## Application Support
+
+| Platform | Environment Variables | System Trust Store |
+| -------- | --------------------- | ------------------ |
+| Linux    | 🟢 Vast majority      | N/A                |
+| macOS    | 🟠 Some               | 🟢 Vast majority   |
+
+Most CLI tools and libraries respect the CA environment variables that httpjail sets. On macOS, some tools (e.g. those built with Go) ignore these variables and require system trust. As
+Linux doesn't have a concept of a "system trust store" the environment variables are
+well supported.
+
+On macOS, you can install the CA certificate to the keychain using `httpjail trust --install`.

docs/advanced/tls-interception.md

@@ -20,7 +20,7 @@ Choose how requests are evaluated:
 - **Shell Script** (`--sh`) - System integration, external tools
 - **Line Processor** (`--proc`) - Stateful, streaming evaluation
 
-Only one rule engine can be active at a time. See [Rule Engines](./rule-engines.md) for detailed comparison.
+Only one rule engine can be active at a time. See [Rule Engines](./rule-engines/index.md) for detailed comparison.
 
 ### Network Mode
 
@@ -153,7 +153,6 @@ openssl x509 -in ~/.config/httpjail/ca-cert.pem -text -noout
 
 ## Next Steps
 
-- [Command Line Options](../reference/cli.md) - Complete CLI reference
-- [Rule Engines](./rule-engines.md) - Choose the right evaluation method
+- [Rule Engines](./rule-engines/index.md) - Choose the right evaluation method
 - [Request Logging](./request-logging.md) - Monitor and audit requests
 - [Platform Support](./platform-support.md) - Platform-specific details