Skip to content

Commit 0be3560

Browse files
blink-so[bot]bcpeinhardt
blink-so[bot]
and
bcpeinhardt
committed
Add PlantUML sequence diagrams for Linux and macOS implementations
Adds comprehensive sequence diagrams showing: - Linux: Network namespace isolation with iptables redirection - macOS: Process group isolation with PF rules - Complete request flow from process execution to cleanup - Platform-specific implementation details and differences Co-authored-by: bcpeinhardt <[email protected]>
1 parent 30a5d7e commit 0be3560

File tree

3 files changed

+213
-0
lines changed

3 files changed

+213
-0
lines changed

‎diagrams/README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Jail Architecture Diagrams
2+
3+
This directory contains PlantUML sequence diagrams that illustrate how the jail network isolation tool works on different platforms.
4+
5+
## Diagrams
6+
7+
### Linux Implementation (`linux-sequence.puml`)
8+
9+
Shows the complete flow of process isolation and proxy communication on Linux using:
10+
- **Network Namespaces**: Complete network isolation for the target process
11+
- **veth pairs**: Virtual ethernet interfaces connecting host and namespace (192.168.100.1/24 ↔ 192.168.100.2/24)
12+
- **iptables**: DNAT rules to redirect HTTP/HTTPS traffic to proxy ports
13+
- **DNS Configuration**: Namespace-specific `/etc/netns/{namespace}/resolv.conf` with public DNS servers
14+
15+
### macOS Implementation (`macos-sequence.puml`)
16+
17+
Shows the complete flow of process isolation and proxy communication on macOS using:
18+
- **Process Groups**: Target process runs with specific group membership
19+
- **PF (Packet Filter)**: Rules to route traffic from specific group through loopback interface
20+
- **Traffic Redirection**: PF redirect rules on loopback send traffic to proxy ports
21+
- **Group Management**: Uses `dscl`/`dseditgroup` to create and manage network groups
22+
23+
## Key Differences
24+
25+
| Aspect | Linux | macOS |
26+
|--------|-------|-------|
27+
| **Isolation Method** | Network namespaces | Process groups |
28+
| **Traffic Redirection** | iptables DNAT rules | PF route-to + rdr rules |
29+
| **Network Setup** | veth pair with private subnet | Loopback interface routing |
30+
| **Process Execution** | `ip netns exec` | `exec.Command` with group credentials |
31+
| **DNS Configuration** | Namespace-specific resolv.conf | Inherits host DNS |
32+
| **Cleanup** | Remove namespace + iptables rules | Flush PF anchor + remove temp files |
33+
34+
## Common Components
35+
36+
Both implementations share:
37+
- **Proxy Server**: HTTP/HTTPS proxy that intercepts and evaluates requests
38+
- **Rule Engine**: Wildcard pattern matching for allow/deny decisions
39+
- **TLS Manager**: Dynamic certificate generation for HTTPS interception
40+
- **Request Flow**: Rule evaluation → Allow/Deny → Forward/Block response
41+
42+
## Viewing the Diagrams
43+
44+
To render these PlantUML diagrams:
45+
46+
1. **Online**: Copy the content to [PlantUML Online Server](http://www.plantuml.com/plantuml/uml/)
47+
2. **VS Code**: Install the PlantUML extension
48+
3. **Command Line**: Use `plantuml` command with Java
49+
4. **IntelliJ/PyCharm**: Built-in PlantUML support
50+
51+
## Architecture Flow
52+
53+
Both diagrams show the complete lifecycle:
54+
1. **Setup Phase**: Create isolation environment and start proxy
55+
2. **Execution Phase**: Run target process with network redirection
56+
3. **Request Interception**: Capture HTTP/HTTPS traffic through proxy
57+
4. **Rule Evaluation**: Apply allow/deny rules to requests
58+
5. **Response Handling**: Forward allowed requests, block denied ones
59+
6. **Cleanup Phase**: Remove isolation environment and proxy
60+
61+
The diagrams demonstrate how jail provides secure, auditable network access control for arbitrary processes across different operating systems.

‎diagrams/linux-sequence.puml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
@startuml Linux Process Isolation and Proxy Communication
2+
3+
title Linux Network Isolation with Network Namespaces
4+
5+
participant "User" as User
6+
participant "jail main" as Main
7+
participant "LinuxJail" as Linux
8+
participant "ProxyServer" as Proxy
9+
participant "RuleEngine" as Rules
10+
participant "TLS Manager" as TLS
11+
participant "Network Namespace" as NetNS
12+
participant "iptables" as IPTables
13+
participant "Target Process" as Process
14+
participant "External Server" as Server
15+
16+
User -> Main: jail --allow "github.com" -- curl https://github.com
17+
Main -> Rules: ParseAllowSpecs(["github.com"])
18+
Rules -> Main: Return allow rules
19+
Main -> TLS: NewCertificateManager()
20+
TLS -> Main: Return cert manager + CA cert
21+
Main -> Linux: NewJail(config, logger)
22+
Linux -> Main: Return LinuxJail instance
23+
24+
Main -> Linux: Setup(httpPort=8040, httpsPort=8043)
25+
Linux -> Linux: setupDNS()
26+
note right: Creates /etc/netns/{namespace}/resolv.conf\nwith public DNS servers (8.8.8.8, etc.)
27+
Linux -> Linux: createNamespace()
28+
Linux -> NetNS: ip netns add {namespace}
29+
NetNS -> Linux: Namespace created
30+
Linux -> Linux: setupNetworking()
31+
Linux -> NetNS: ip link add veth_h_{id} type veth peer name veth_n_{id}
32+
Linux -> NetNS: ip link set veth_n_{id} netns {namespace}
33+
Linux -> NetNS: ip addr add 192.168.100.1/24 dev veth_h_{id}
34+
Linux -> NetNS: ip netns exec {namespace} ip addr add 192.168.100.2/24 dev veth_n_{id}
35+
Linux -> NetNS: ip netns exec {namespace} ip route add default via 192.168.100.1
36+
Linux -> Linux: setupIptables()
37+
Linux -> IPTables: iptables -t nat -A POSTROUTING -s 192.168.100.0/24 -j MASQUERADE
38+
Linux -> IPTables: ip netns exec {namespace} iptables -t nat -A OUTPUT -p tcp --dport 80 -j DNAT --to-destination 192.168.100.1:8040
39+
Linux -> IPTables: ip netns exec {namespace} iptables -t nat -A OUTPUT -p tcp --dport 443 -j DNAT --to-destination 192.168.100.1:8043
40+
Linux -> Main: Setup complete
41+
42+
Main -> Proxy: NewProxyServer(config)
43+
Proxy -> Main: Return proxy instance
44+
Main -> Proxy: Start(ctx)
45+
Proxy -> Proxy: Start HTTP server on :8040
46+
Proxy -> Proxy: Start HTTPS server on :8043 with TLS config
47+
48+
Main -> Linux: Execute(["curl", "https://github.com"], extraEnv)
49+
Linux -> Process: ip netns exec {namespace} curl https://github.com
50+
note right: Process runs inside network namespace\nwith CA cert environment variables
51+
52+
Process -> NetNS: Connect to github.com:443
53+
NetNS -> IPTables: Traffic hits OUTPUT chain
54+
IPTables -> IPTables: DNAT rule redirects to 192.168.100.1:8043
55+
NetNS -> Proxy: HTTPS request to 192.168.100.1:8043
56+
Proxy -> TLS: Generate certificate for github.com
57+
TLS -> Proxy: Return certificate
58+
Proxy -> Process: TLS handshake with generated cert
59+
Process -> Proxy: HTTPS request (decrypted)
60+
Proxy -> Rules: Evaluate("GET", "https://github.com")
61+
Rules -> Proxy: Allow (matches "github.com" rule)
62+
Proxy -> Server: Forward HTTPS request to real github.com
63+
Server -> Proxy: HTTPS response
64+
Proxy -> Process: Forward response (re-encrypted)
65+
Process -> Linux: Exit with status code
66+
Linux -> Main: Command completed
67+
68+
Main -> Linux: Cleanup()
69+
Linux -> IPTables: Remove iptables rules
70+
Linux -> NetNS: ip netns del {namespace}
71+
Linux -> Linux: Remove /etc/netns/{namespace}
72+
Linux -> Main: Cleanup complete
73+
74+
@enduml

‎diagrams/macos-sequence.puml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
@startuml macOS Process Isolation and Proxy Communication
2+
3+
title macOS Network Isolation with PF Rules and Process Groups
4+
5+
participant "User" as User
6+
participant "jail main" as Main
7+
participant "MacOSJail" as MacOS
8+
participant "ProxyServer" as Proxy
9+
participant "RuleEngine" as Rules
10+
participant "TLS Manager" as TLS
11+
participant "dscl/dseditgroup" as Groups
12+
participant "PF (Packet Filter)" as PF
13+
participant "Target Process" as Process
14+
participant "External Server" as Server
15+
16+
User -> Main: jail --allow "github.com" -- curl https://github.com
17+
Main -> Rules: ParseAllowSpecs(["github.com"])
18+
Rules -> Main: Return allow rules
19+
Main -> TLS: NewCertificateManager()
20+
TLS -> Main: Return cert manager + CA cert
21+
Main -> MacOS: NewJail(config, logger)
22+
MacOS -> Main: Return MacOSJail instance
23+
24+
Main -> MacOS: Setup(httpPort=8040, httpsPort=8043)
25+
MacOS -> MacOS: ensureGroup()
26+
MacOS -> Groups: dscl . -read /Groups/network PrimaryGroupID
27+
alt Group exists
28+
Groups -> MacOS: Return existing GID
29+
else Group doesn't exist
30+
MacOS -> Groups: dseditgroup -o create network
31+
Groups -> MacOS: Group created
32+
MacOS -> Groups: dscl . -read /Groups/network PrimaryGroupID
33+
Groups -> MacOS: Return new GID
34+
end
35+
MacOS -> MacOS: setupPFRules()
36+
MacOS -> MacOS: getDefaultInterface()
37+
MacOS -> MacOS: route -n get default
38+
MacOS -> MacOS: createPFRules() - Generate PF rules for group
39+
note right: Creates rules to redirect traffic from group {GID}\nto loopback interface, then to proxy ports
40+
MacOS -> PF: Write rules to /tmp/{name}.pf
41+
MacOS -> PF: pfctl -a network -f /tmp/{name}.pf
42+
MacOS -> PF: pfctl -E (enable PF)
43+
MacOS -> PF: pfctl -f /tmp/{name}_main.pf (load main ruleset)
44+
MacOS -> Main: Setup complete
45+
46+
Main -> Proxy: NewProxyServer(config)
47+
Proxy -> Main: Return proxy instance
48+
Main -> Proxy: Start(ctx)
49+
Proxy -> Proxy: Start HTTP server on :8040
50+
Proxy -> Proxy: Start HTTPS server on :8043 with TLS config
51+
52+
Main -> MacOS: Execute(["curl", "https://github.com"], extraEnv)
53+
MacOS -> Process: exec.Command with SysProcAttr.Credential.Gid = {groupID}
54+
note right: Process runs with network group membership\nand CA cert environment variables
55+
56+
Process -> PF: Connect to github.com:443
57+
PF -> PF: Match group {GID} traffic rule
58+
PF -> PF: route-to (lo0 127.0.0.1) for port 443
59+
PF -> PF: rdr pass on lo0 port 443 -> 127.0.0.1:8043
60+
Process -> Proxy: HTTPS request to 127.0.0.1:8043
61+
Proxy -> TLS: Generate certificate for github.com
62+
TLS -> Proxy: Return certificate
63+
Proxy -> Process: TLS handshake with generated cert
64+
Process -> Proxy: HTTPS request (decrypted)
65+
Proxy -> Rules: Evaluate("GET", "https://github.com")
66+
Rules -> Proxy: Allow (matches "github.com" rule)
67+
Proxy -> Server: Forward HTTPS request to real github.com
68+
Server -> Proxy: HTTPS response
69+
Proxy -> Process: Forward response (re-encrypted)
70+
Process -> MacOS: Exit with status code
71+
MacOS -> Main: Command completed
72+
73+
Main -> MacOS: Cleanup()
74+
MacOS -> PF: pfctl -a network -F all (flush anchor)
75+
MacOS -> MacOS: Remove /tmp/{name}.pf and /tmp/{name}_main.pf
76+
MacOS -> Main: Cleanup complete
77+
78+
@enduml

0 commit comments

Comments
 (0)