{"id":30190811,"url":"https://github.com/lambertse/sandbox_cpp","last_synced_at":"2025-08-12T20:09:00.672Z","repository":{"id":308573202,"uuid":"1032473379","full_name":"lambertse/sandbox_cpp","owner":"lambertse","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-06T17:27:49.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-06T18:12:27.162Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lambertse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-05T11:04:17.000Z","updated_at":"2025-08-06T17:27:52.000Z","dependencies_parsed_at":"2025-08-06T18:12:43.067Z","dependency_job_id":"f1a4f70d-f76e-4934-9087-c88886329c6d","html_url":"https://github.com/lambertse/sandbox_cpp","commit_stats":null,"previous_names":["lambertse/sandbox_cpp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lambertse/sandbox_cpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fsandbox_cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fsandbox_cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fsandbox_cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fsandbox_cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambertse","download_url":"https://codeload.github.com/lambertse/sandbox_cpp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fsandbox_cpp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270127392,"owners_count":24531793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-12T20:08:55.638Z","updated_at":"2025-08-12T20:09:00.604Z","avatar_url":"https://github.com/lambertse.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# C++ Sandbox - Phase 1 with Examples and Tests\n\nA beginner-friendly C++ sandbox implementation for secure program execution on Linux x86_64, complete with comprehensive examples and Google Test-based testing.\n\n## Project Structure\n\n```\ncpp-sandbox/\n├── CMakeLists.txt                    # Main build configuration\n├── README.md                         # This file\n├── src/                             # Core sandbox implementation\n│   ├── core/\n│   │   ├── sandbox.h/cpp            # Main sandbox execution engine\n│   │   └── logger.h/cpp             # Logging system\n│   ├── config/\n│   │   ├── sandbox_config.h/cpp     # Configuration management\n│   └── main.cpp                     # Command-line interface\n├── examples/                        # Demonstration programs\n│   ├── basic_usage/                 # Simple examples\n│   ├── resource_testing/            # Resource limit demos\n│   └── malicious_simulation/        # Security testing examples\n└── tests/                           # Comprehensive test suite\n    ├── unit_tests/                  # Component testing\n    └── integration_tests/           # Full workflow testing\n```\n\n## Features (Phase 1)\n\n- ✅ **Process Isolation**: Fork-exec model with resource limits\n- ✅ **Resource Limiting**: Memory, CPU time, file descriptor limits\n- ✅ **Comprehensive Logging**: Structured logging with timestamps\n- ✅ **Execution Monitoring**: Resource usage tracking and timing\n- ✅ **Clean Architecture**: Modular design ready for security enhancements\n- ✅ **Example Programs**: Real-world demonstration programs\n- ✅ **Unit Testing**: Google Test-based comprehensive testing\n\n## Building\n\n### Prerequisites\n\n```bash\n# Ubuntu/Debian\nsudo apt update\nsudo apt install build-essential cmake libseccomp-dev libgtest-dev libgmock-dev\n\n# If Google Test is not available via package manager\ngit clone https://github.com/google/googletest.git\ncd googletest\nmkdir build \u0026\u0026 cd build\ncmake ..\nmake\nsudo make install\n```\n\n### Compilation\n\n```bash\nmkdir build \u0026\u0026 cd build\ncmake ..\nmake -j$(nproc)\n```\n\n### Installation (Optional)\n\n```bash\nsudo make install\n```\n\n## Usage\n\n### Running the Sandbox\n\n```bash\n# Basic usage\n./sandbox /bin/echo \"Hello Sandbox\"\n\n# With resource limits\n./sandbox -m 64 -t 5 /bin/sleep 3\n\n# Enable debug logging\n./sandbox -d -l debug.log /usr/bin/whoami\n```\n\n### Command Line Options\n\n```\nUsage: ./sandbox [OPTIONS] \u003cprogram_to_run\u003e [args...]\n\nOptions:\n  -h, --help              Show help message\n  -m, --memory \u003cMB\u003e       Memory limit in MB (default: 128)\n  -t, --time \u003cseconds\u003e    CPU time limit in seconds (default: 10)\n  -w, --wall-time \u003csec\u003e   Wall time limit in seconds (default: 15)\n  -f, --files \u003ccount\u003e     Max open files (default: 64)\n  -d, --debug             Enable debug logging\n  -l, --log \u003cfile\u003e        Log file path (default: sandbox.log)\n  --no-console            Disable console logging\n```\n\n## Examples\n\n### Basic Usage Examples\n\n```bash\n# Simple greeting program\n./sandbox ./examples/hello_world\n\n# Calculator with arguments\n./sandbox ./examples/simple_calculator 10 5\n\n# File operations demonstration\n./sandbox ./examples/file_operations\n```\n\n### Resource Testing Examples\n\n```bash\n# Test memory limits (will be terminated by sandbox)\n./sandbox -m 32 ./examples/memory_allocator\n\n# Test CPU time limits (will timeout)\n./sandbox -t 3 ./examples/cpu_intensive\n\n# Test file descriptor limits\n./sandbox -f 10 ./examples/file_creator\n```\n\n### Security Testing Examples\n\n```bash\n# Safe fork bomb simulation (limited)\n./sandbox -t 5 ./examples/fork_bomb\n\n# Infinite loop (will be terminated)\n./sandbox -t 3 ./examples/infinite_loop\n\n# Memory bomb (will hit memory limit)\n./sandbox -m 16 ./examples/memory_bomb\n```\n\n## Testing\n\n### Running All Tests\n\n```bash\n# Build and run all tests\nmake test\n\n# Or use ctest directly\nctest --verbose\n```\n\n### Running Specific Test Suites\n\n```bash\n# Unit tests only\n./tests/unit_tests\n\n# Integration tests only\n./tests/integration_tests\n\n# Run with Google Test filters\n./tests/unit_tests --gtest_filter=\"LoggerTest.*\"\n./tests/integration_tests --gtest_filter=\"ResourceLimitsTest.*\"\n```\n\n### Test Coverage\n\nThe test suite includes:\n\n#### Unit Tests\n- **Logger Tests**: Log level filtering, file output, macros\n- **Config Tests**: Validation, default values, edge cases\n- **Sandbox Tests**: Status transitions, execution flow, error handling\n\n#### Integration Tests\n- **Resource Limits**: Memory, CPU, and file descriptor enforcement\n- **Execution Flow**: Complete program execution workflows\n- **Error Handling**: Invalid configurations, program crashes, edge cases\n\n## Example Output\n\n### Successful Execution\n```\n[2025-08-05 10:06:48.123] [INFO] === C++ Sandbox Starting ===\n[2025-08-05 10:06:48.124] [INFO] === Sandbox Configuration ===\n[2025-08-05 10:06:48.124] [INFO] Program: ./examples/hello_world\n[2025-08-05 10:06:48.124] [INFO] Memory Limit: 128MB\n[2025-08-05 10:06:48.124] [INFO] CPU Time Limit: 10s\n[2025-08-05 10:06:48.125] [INFO] Child process started with PID: 12345\n[2025-08-05 10:06:48.130] [INFO] Program finished with exit code: 0\n[2025-08-05 10:06:48.131] [INFO] === Execution Result ===\n[2025-08-05 10:06:48.131] [INFO] Status: FINISHED\n[2025-08-05 10:06:48.131] [INFO] Exit Code: 0\n[2025-08-05 10:06:48.131] [INFO] Execution Time: 5ms\n[2025-08-05 10:06:48.131] [INFO] Memory Used: 1024KB\n```\n\n### Memory Limit Enforcement\n```\n[2025-08-05 10:06:50.123] [INFO] Starting sandbox execution\n[2025-08-05 10:06:50.125] [INFO] Child process started with PID: 12346\n[2025-08-05 10:06:51.200] [WARNING] Program was killed by signal: 9\n[2025-08-05 10:06:51.201] [INFO] === Execution Result ===\n[2025-08-05 10:06:51.201] [INFO] Status: KILLED\n[2025-08-05 10:06:51.201] [INFO] Exit Code: 137\n[2025-08-05 10:06:51.201] [INFO] Memory Used: 65536KB\n```\n\n## Development\n\n### Adding New Examples\n\n1. Create your example program in the appropriate `examples/` subdirectory\n2. Add the executable target to `examples/CMakeLists.txt`\n3. Document the example's purpose and expected behavior\n4. Test with various sandbox configurations\n\n### Adding New Tests\n\n1. Create test files in `tests/unit_tests/` or `tests/integration_tests/`\n2. Follow Google Test naming conventions (`TEST_F`, `TEST`)\n3. Include setup and teardown as needed\n4. Add new test executables to `tests/CMakeLists.txt`\n\n### Code Style\n\n- Follow C++17 standards\n- Use RAII principles\n- Include comprehensive error handling\n- Document public interfaces\n- Write descriptive test names\n\n## Architecture\n\n```\n┌─────────────────┐    ┌──────────────────┐\n│   Command Line  │───▶│  SandboxConfig   │\n│   Interface     │    │  Configuration   │\n└─────────────────┘    └──────────────────┘\n         │                       │\n         ▼                       ▼\n┌─────────────────┐    ┌──────────────────┐\n│     Logger      │◀───│     Sandbox      │\n│    System       │    │  Execution Engine│\n└─────────────────┘    └──────────────────┘\n                               │\n                               ▼\n                    ┌──────────────────┐\n                    │  ExecutionResult │\n                    │   \u0026 Statistics   │\n                    └──────────────────┘\n```\n\n## What's Next?\n\n**Phase 2** will add:\n- 🔒 Syscall filtering with seccomp-bpf\n- 🛡️ Basic security policies\n- ⚡ Performance monitoring\n- 🎛️ Enhanced resource controls\n\n**Phase 3** will add:\n- 🔍 System call tracing with ptrace\n- 📁 File system monitoring\n- 🌐 Network activity tracking\n- 📊 Advanced logging and reporting\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Google Test Not Found**: Install `libgtest-dev` or build from source\n2. **Permission Denied**: Ensure programs are executable (`chmod +x`)\n3. **Memory Allocation Failed**: Lower memory limits or check system resources\n4. **Tests Failing**: Check that dependencies are properly installed\n\n### Debug Mode\n\nEnable debug logging to see detailed execution flow:\n\n```bash\n./sandbox -d -l debug.log your_program\ntail -f debug.log\n```\n\n### Running Individual Tests\n\n```bash\n# Test specific functionality\n./tests/unit_tests --gtest_filter=\"LoggerTest.InitializeLogger\"\n./tests/integration_tests --gtest_filter=\"ResourceLimitsTest.MemoryLimitEnforcement\"\n```\n\n## Contributing\n\nThis is a learning project! Contributions welcome:\n- Add more example programs\n- Improve test coverage\n- Enhance error handling\n- Optimize resource management\n- Add performance benchmarks\n\n---\n\n**Phase 1 Complete** ✅  \n**Examples \u0026 Tests Ready** ✅  \n**Ready for Phase 2 Security Enhancements!** 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambertse%2Fsandbox_cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambertse%2Fsandbox_cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambertse%2Fsandbox_cpp/lists"}