1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
//! CLI-based Sandbox Examples
//!
//! This example demonstrates how to use the sandbox-ctl CLI to create and manage sandboxes
//! from the command line. It shows various ways to invoke the sandbox with different options.
//!
//! ## Prerequisites
//!
//! 1. Build the sandbox-ctl CLI:
//! cargo build --bin sandbox-ctl
//!
//! 2. Run with root privileges (required for full isolation):
//! sudo ./target/debug/sandbox-ctl run --id test-1 /bin/echo "hello world"
//!
//! ## Examples shown
//!
//! This file documents the CLI usage patterns. Here are the common invocations:
//!
//! ### 1. Basic execution (no resource limits)
//! ```bash
//! sandbox-ctl run --id my-sandbox /bin/echo "hello"
//! ```
//!
//! ### 2. With memory limit
//! ```bash
//! sandbox-ctl run --id memory-limited \
//! --memory 100M \
//! /bin/bash -c "echo 'Running with 100MB memory limit'"
//! ```
//!
//! ### 3. With CPU limit (50% of one core)
//! ```bash
//! sandbox-ctl run --id cpu-limited \
//! --cpu 50 \
//! /bin/stress-ng --cpu 1 --timeout 5s
//! ```
//!
//! ### 4. With timeout
//! ```bash
//! sandbox-ctl run --id timeout-example \
//! --timeout 2 \
//! /bin/sleep 10 # Will be killed after 2 seconds
//! ```
//!
//! ### 5. With seccomp profile
//! ```bash
//! sandbox-ctl run --id minimal-syscalls \
//! --seccomp minimal \
//! /bin/echo "Only essential syscalls allowed"
//! ```
//!
//! ### 6. Combined: Memory + CPU + Timeout + Seccomp
//! ```bash
//! sandbox-ctl run --id restricted \
//! --memory 256M \
//! --cpu 25 \
//! --timeout 30 \
//! --seccomp io-heavy \
//! /usr/bin/python3 script.py
//! ```
//!
//! ### 7. With custom sandbox root directory
//! ```bash
//! sandbox-ctl run --id custom-root \
//! --root /tmp/my-sandbox-root \
//! /bin/ls -la
//! ```
//!
//! ### 8. List available seccomp profiles
//! ```bash
//! sandbox-ctl profiles
//! ```
//!
//! ### 9. Check system requirements
//! ```bash
//! sandbox-ctl check
//! ```
//!
//! ## Memory limit formats
//!
//! The --memory flag supports multiple formats:
//! - "64M" or "64MB" - megabytes
//! - "1G" or "1GB" - gigabytes
//! - "512K" or "512KB" - kilobytes
//! - Direct bytes as number
//!
//! ## CPU limit (percentage)
//!
//! The --cpu flag accepts 0-100:
//! - 25 = 25% of one CPU core
//! - 50 = 50% of one CPU core (half core)
//! - 100 = One full CPU core
//! - 200 = Two CPU cores (on multi-core systems)
//!
//! ## Seccomp profiles
//!
//! Available profiles (use with --seccomp):
//! - minimal: Only essential syscalls (exit, read, write)
//! - io-heavy: Minimal + file I/O (open, close, seek, stat)
//! - compute: IO-heavy + memory operations (mmap, brk, mprotect)
//! - network: Compute + socket operations (socket, bind, listen)
//! - unrestricted: Most syscalls allowed (for debugging)
//!
//! ## Running with sudo
//!
//! Since full isolation requires root:
//! ```bash
//! # Option 1: Run entire command as root
//! sudo ./target/debug/sandbox-ctl run --id test /bin/echo "hello"
//!
//! # Option 2: Configure sudo to allow without password (advanced)
//! # Add to /etc/sudoers:
//! # user ALL=(ALL) NOPASSWD: /path/to/sandbox-ctl
//! ```
//!
//! ## Exit codes
//!
//! The CLI returns:
//! - Exit code of the sandboxed program (0-255)
//! - 1 if sandbox creation or execution failed
//!
//! ## Performance considerations
//!
//! - Memory limits are enforced at kernel level via Cgroup v2
//! - CPU limits use CFS scheduler quotas
//! - Seccomp filtering happens in kernel BPF
//! - Namespace isolation has minimal overhead