# devhoodit/candbox architecture

> Architecture diagram of the GitHub repository devhoodit/candbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devhoodit/candbox
- Repository: https://github.com/devhoodit/candbox

## Overview

##### 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()

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    Client["Client Application"]:::client

    %% Candbox Library Modules
    subgraph "candbox Library"
        direction TB
        CandboxCore["Candbox Core\n(execve & ptrace orchestration)"]:::core
        SandboxRule["SandboxRule\n(collection of SyscallRule)"]:::rule
        SyscallRule["SyscallRule\n(ALLOW/DISALLOW/CALLBACK)"]:::rule
        SyscallMapper["SyscallMapper\n(TBL parser & lookup)"]:::mapper
        StringUtil["string_util"]:::util
    end

    %% External Resources
    TBLFile["Syscall Table File (.tbl)"]:::external

    %% Kernel Boundary
    Kernel["Linux Kernel\n(execve, ptrace, syscalls)"]:::kernel

    %% Build Configuration
    subgraph "Build Configuration"
        CMake["CMakeLists.txt"]:::config
        CMakeIn["cmake/candboxConfig.cmake.in"]:::config
    end

    %% Interactions
    Client -->|"candbox.execve() API"| CandboxCore
    CandboxCore -->|"fork() & execve()"| Kernel
    CandboxCore -->|"ptrace options & loop"| Kernel
    CandboxCore -->|"lookup(syscall_num)"| SyscallMapper
    SyscallMapper -->|file read| TBLFile
    TBLFile -.->|.tbl| SyscallMapper
    CandboxCore -->|"applyRule(syscall_num)"| SandboxRule
    SandboxRule -->|"decision lookup"| SyscallRule
    SyscallRule -->|"callback? invoke"| Client
    StringUtil -->|"string conversions"| CandboxCore
    CMake -->|"configures build"| CandboxCore

    %% Click Events
    click CandboxCore "https://github.com/devhoodit/candbox/blob/main/include/candbox/candbox.h"
    click CandboxCore "https://github.com/devhoodit/candbox/blob/main/src/candbox.cpp"
    click SandboxRule "https://github.com/devhoodit/candbox/blob/main/include/candbox/sandbox_rule.h"
    click SyscallRule "https://github.com/devhoodit/candbox/blob/main/src/syscall_rule.cpp"
    click SyscallMapper "https://github.com/devhoodit/candbox/blob/main/include/candbox/syscall_mapper.h"
    click SyscallMapper "https://github.com/devhoodit/candbox/blob/main/src/syscall_mapper.cpp"
    click StringUtil "https://github.com/devhoodit/candbox/blob/main/include/candbox/string_util.h"
    click CMake "https://github.com/devhoodit/candbox/blob/main/CMakeLists.txt"
    click CMakeIn "https://github.com/devhoodit/candbox/blob/main/cmake/candboxConfig.cmake.in"

    %% Styles
    classDef client fill:#FFF1A8,stroke:#333,stroke-width:1px
    classDef core fill:#A8CFFD,stroke:#333,stroke-width:1px
    classDef rule fill:#C8FAD0,stroke:#333,stroke-width:1px
    classDef mapper fill:#FAD8FA,stroke:#333,stroke-width:1px
    classDef util fill:#FFE4A8,stroke:#333,stroke-width:1px
    classDef external fill:#C8E7FF,stroke:#333,stroke-dasharray:5 5
    classDef kernel fill:#F8A8A8,stroke:#900,stroke-width:2px
    classDef config fill:#D0FAD8,stroke:#070,stroke-width:1px
```
