How devhoodit/candbox works
Project Type and Purpose
• This is a C++ “sandbox executor” library (not a full application) whose purpose is to let client code spawn a subprocess via execve, trace and optionally block or log its system calls, and map syscall numbers to names.
• Key features (from README):
• Execve-based sandboxing with customizable SyscallRule callbacks
• SyscallMapper to parse a Linux syscall table (TBL file) and convert syscall numbers to human-readable names
File Structure
• Top-level build files:
• CMakeLists.txt, cmake/*.cmake.in → build configuration
• .clang-format, .gitignore
• Public API headers under include/candbox:
• candbox.h – main Candbox class and execve API
• sandbox_rule.h – SandboxRule and SyscallRule definitions
• syscall_mapper.h – SyscallMapper interface to load/parse .tbl file
• string_util.h – auxiliary string conversions
• Source implementations under src:
• candbox.cpp – forks, ptrace loop, dispatch logic
• syscall_rule.cpp – rule-matching and callback invocation
• syscall_mapper.cpp – parsing TBL file into lookup tables
Key Insights from README
• Two main modules:
a. Sandbox: enforces SyscallRule decision per-syscall (ALLOW, DISALLOW, CALLBACK)
b. SyscallMapper: loads Linux syscall table to translate codes to names
• Client usage revolves around constructing SandboxRule + ExecConfig, then calling candbox.execve()