secure-sandbox 0.0.1__tar.gz

secure_sandbox-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,293 @@
+# Contributing to Secure Sandbox
+
+Thank you for your interest in contributing to Secure Sandbox! This document provides guidelines and instructions for contributing.
+
+## Development Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/yourname/secure-sandbox.git
+cd secure-sandbox
+```
+
+### 2. Create Virtual Environment
+
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+### 3. Install Development Dependencies
+
+```bash
+pip install -e ".[dev]"
+```
+
+This will install:
+- `pytest` - Testing framework
+- `pytest-cov` - Coverage plugin
+- `black` - Code formatter
+- `mypy` - Type checker
+- `flake8` - Linter
+
+## Project Structure
+
+```
+secure-sandbox/
+├── src/
+│   └── secure_sandbox/      # Main package
+│       ├── __init__.py
+│       ├── core.py
+│       ├── whitelist.py
+│       ├── exceptions.py
+│       └── cli.py
+├── tests/                   # Test suite
+│   ├── test_basic.py
+│   ├── test_security.py
+│   └── test_config.py
+├── docs/                    # Documentation
+│   └── README_CN.md
+├── examples/                # Usage examples
+│   ├── basic_usage.py
+│   └── custom_config.py
+├── README.md                # English documentation
+├── CONTRIBUTING.md          # This file
+├── setup.py                 # Setup script
+└── pyproject.toml           # Modern config
+```
+
+## Coding Standards
+
+### Code Style
+
+We use `black` for code formatting:
+
+```bash
+# Format code
+black src/ tests/ examples/
+
+# Check formatting
+black --check src/ tests/ examples/
+```
+
+### Type Hints
+
+We encourage using type hints:
+
+```python
+def safe_execute(
+    code_str: str,
+    max_gas: int = 10000,
+    config: Optional[SecurityConfig] = None
+) -> Dict[str, Any]:
+    ...
+```
+
+### Linting
+
+Use `flake8` for linting:
+
+```bash
+flake8 src/ tests/ examples/
+```
+
+### Type Checking
+
+Use `mypy` for type checking:
+
+```bash
+mypy src/
+```
+
+## Testing
+
+### Run Tests
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=src/secure_sandbox --cov-report=html
+
+# Run specific test file
+pytest tests/test_basic.py
+
+# Run specific test
+pytest tests/test_basic.py::test_safe_execution
+```
+
+### Writing Tests
+
+Follow pytest conventions:
+
+```python
+import pytest
+from secure_sandbox import safe_execute, GasLimitExceeded
+
+def test_infinite_loop():
+    """Test that infinite loops are caught by Gas mechanism"""
+    code = """
+    i = 0
+    while True:
+        i += 1
+    """
+    
+    with pytest.raises(GasLimitExceeded):
+        safe_execute(code, max_gas=10)
+```
+
+## Pull Request Process
+
+### 1. Create Feature Branch
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 2. Make Changes
+
+- Follow coding standards
+- Add tests for new features
+- Update documentation if needed
+
+### 3. Run Quality Checks
+
+```bash
+# Format code
+black src/ tests/
+
+# Run linter
+flake8 src/ tests/
+
+# Run type checker
+mypy src/
+
+# Run tests
+pytest tests/
+```
+
+### 4. Commit Changes
+
+Write clear commit messages:
+
+```bash
+git add .
+git commit -m "Add feature: custom module whitelist support"
+```
+
+### 5. Push and Create PR
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create Pull Request on GitHub.
+
+## Adding New Features
+
+### Security Features
+
+When adding security features:
+
+1. **Document the threat**: What attack does it prevent?
+2. **Test thoroughly**: Include attack and defense test cases
+3. **Make configurable**: Allow users to enable/disable
+4. **Update whitelist/blacklist**: Add new entries if needed
+
+### Configuration Options
+
+When adding configuration options:
+
+1. Add to `SecurityConfig` dataclass
+2. Update `__post_init__` if needed
+3. Document in README
+4. Add example usage
+5. Test with different configurations
+
+## Documentation
+
+### Update README
+
+When adding features:
+
+1. Update feature list
+2. Add usage examples
+3. Update API documentation
+4. Add configuration details
+
+### Update Chinese Documentation
+
+Also update `docs/README_CN.md` with Chinese translations.
+
+### Code Comments
+
+Add clear comments:
+
+```python
+def check_gas(self) -> None:
+    """Check and consume Gas - high-frequency function
+    
+    This function is called at every loop iteration and function call
+    to prevent CPU DoS attacks. When Gas quota is exhausted, it raises
+    GasLimitExceeded exception.
+    
+    Raises:
+        GasLimitExceeded: When Gas quota is exhausted
+    """
+    if self._current_gas <= 0:
+        raise GasLimitExceeded(...)
+```
+
+## Release Process
+
+### 1. Update Version
+
+Update version in:
+- `setup.py`
+- `pyproject.toml`
+- `src/secure_sandbox/__init__.py`
+
+### 2. Update Changelog
+
+Create `CHANGELOG.md`:
+
+```markdown
+## [0.0.2] - 2026-06-05
+### Added
+- Custom module whitelist support
+- Memory monitoring feature
+
+### Changed
+- Improved Gas mechanism performance
+
+### Fixed
+- Bug in attribute interception
+```
+
+### 3. Build Package
+
+```bash
+python -m build
+```
+
+### 4. Test Installation
+
+```bash
+pip install dist/secure_sandbox-0.0.2.tar.gz
+pytest tests/
+```
+
+### 5. Publish to PyPI
+
+```bash
+twine upload dist/*
+```
+
+## Questions?
+
+- Open an Issue for bugs or feature requests
+- Email: security@example.com
+
+Thank you for contributing! 🎉

secure_sandbox-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Python Security Architect
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

secure_sandbox-0.0.1/MANIFEST.in

@@ -0,0 +1,15 @@
+include README.md
+include CONTRIBUTING.md
+include LICENSE
+include pyproject.toml
+include setup.py
+
+recursive-include src *.py
+recursive-include tests *.py
+recursive-include examples *.py *.json
+recursive-include docs *.md
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.pyo
+global-exclude .DS_Store

secure_sandbox-0.0.1/PKG-INFO

@@ -0,0 +1,350 @@
+Metadata-Version: 2.4
+Name: secure-sandbox
+Version: 0.0.1
+Summary: 高安全性Python沙箱库 - 用于安全执行不可信代码
+Home-page: https://github.com/dotnet-7/secure-sandbox
+Author: Python Security Architect
+Author-email: senyangcai <158119447@qq.com>
+License: MIT
+Project-URL: Homepage, https://github.com/dotnet-7/secure-sandbox
+Project-URL: Documentation, https://github.com/dotnet-7/secure-sandbox/wiki
+Project-URL: Repository, https://github.com/dotnet-7/secure-sandbox
+Project-URL: Issues, https://github.com/dotnet-7/secure-sandbox/issues
+Keywords: sandbox,security,code execution,AI code,unsafe code,restricted execution,gas mechanism,AST whitelist
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Secure Sandbox
+
+[![PyPI version](https://badge.fury.io/py/secure-sandbox.svg)](https://badge.fury.io/py/secure-sandbox)
+[![Python versions](https://img.shields.io/pypi/pyversions/secure-sandbox.svg)](https://pypi.org/project/secure-sandbox)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**A high-security Python sandbox library for safely executing untrusted third-party code (such as AI-generated code)**
+
+[中文文档 (Chinese Documentation)](docs/README_CN.md)
+
+## Core Features
+
+### 1. Gas Mechanism - Prevent CPU DoS Attacks
+- ✅ Automatically inject Gas checks in every loop and function call
+- ✅ Immediately throw `GasLimitExceeded` exception when Gas quota is exhausted
+- ✅ Effectively defend against infinite loops and resource exhaustion attacks
+
+### 2. AST Whitelist Validation
+- ✅ Strict AST node whitelist mechanism
+- ✅ Reject dangerous AST nodes (Import, Async, Yield, etc.)
+- ✅ Block dangerous operations at compile time
+
+### 3. Attribute Access Interception
+- ✅ All attribute accesses are rewritten to `__sandbox_getattr__`
+- ✅ Strict attribute blacklist (40+ dangerous attributes like `__class__`, `__subclasses__`)
+- ✅ Prevent sandbox escape via reflection chains
+
+### 4. Import Whitelist Control
+- ✅ Configurable module import whitelist
+- ✅ Default allows safe modules (math, json, datetime, etc.)
+- ✅ Reject dangerous modules (os, sys, subprocess, etc.)
+
+### 5. Fully Configurable
+- ✅ All security policies can be customized
+- ✅ Gas quota, AST whitelist, attribute blacklist, module whitelist all configurable
+- ✅ Support flexible security level adjustments
+
+## Installation
+
+```bash
+pip install secure-sandbox
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from secure_sandbox import safe_execute
+
+# Execute safe code
+code = """
+def factorial(n):
+    result = 1
+    for i in range(1, n + 1):
+        result *= i
+    return result
+
+print(f"Factorial of 5: {factorial(5)}")
+"""
+
+result = safe_execute(code, max_gas=100)
+print(f"Remaining Gas: {result['remaining_gas']}")
+```
+
+### Prevent Infinite Loops
+
+```python
+from secure_sandbox import SecureSandbox, GasLimitExceeded
+
+malicious_code = """
+i = 0
+while True:
+    i += 1
+"""
+
+sandbox = SecureSandbox()
+try:
+    sandbox.safe_execute(malicious_code, max_gas=50)
+except GasLimitExceeded as e:
+    print(f"Successfully intercepted infinite loop: {e}")
+```
+
+### Prevent Sandbox Escape
+
+```python
+from secure_sandbox import SecureSandbox, SandboxSecurityError
+
+escape_code = """
+result = [].__class__.__base__.__subclasses__()
+"""
+
+sandbox = SecureSandbox()
+try:
+    sandbox.safe_execute(escape_code, max_gas=100)
+except SandboxSecurityError as e:
+    print(f"Successfully intercepted escape attack: {e}")
+```
+
+### Use Module Imports
+
+```python
+from secure_sandbox import safe_execute
+
+code = """
+import math
+result = math.sqrt(16)
+print(f"sqrt(16) = {result}")
+
+from json import dumps
+json_str = dumps({"name": "Alice", "age": 25})
+print(json_str)
+"""
+
+result = safe_execute(code, max_gas=100)
+```
+
+### Security Interception Demo
+
+See comprehensive attack interception examples:
+
+```bash
+python examples/security_interception.py
+```
+
+This demonstrates how Secure Sandbox blocks **20 types of attacks**:
+- ✅ Infinite loops (Gas mechanism)
+- ✅ Reflection chain escapes (__class__, __globals__, __code__)
+- ✅ Import attacks (os, sys, subprocess)
+- ✅ Dynamic execution (eval, exec, compile)
+- ✅ Exception handling escapes
+- ✅ Context manager attacks
+- ✅ Private attribute access
+- ✅ Internal attribute attacks (__dict__, __mro__, __subclasses__)
+
+**All attacks are successfully intercepted with 100% block rate!**
+
+## Advanced Configuration
+
+### Custom Security Policy
+
+```python
+from secure_sandbox import SecureSandbox, SecurityConfig
+
+# Create custom configuration
+config = SecurityConfig(
+    # Gas configuration
+    max_gas=5000,              # Maximum Gas quota
+    max_recursion_depth=50,    # Maximum recursion depth
+    
+    # Import configuration
+    allow_imports=True,        # Allow imports
+    allowed_modules={'math', 'json'},  # Only allow these modules
+    
+    # AST node configuration (optional)
+    ast_whitelist={'For', 'While', 'FunctionDef', ...},  # Custom AST whitelist
+    ast_blacklist={'Import', 'Try', ...},  # Custom AST blacklist
+    
+    # Attribute access configuration
+    allow_dunder_access=False,  # Disallow magic methods
+    allow_private_attrs=False,  # Disallow private attributes
+    dangerous_attributes={'__class__', '__globals__', ...},  # Custom dangerous attributes
+    safe_attributes={'append', 'upper', ...},  # Custom safe attributes
+    
+    # Feature switches
+    allow_comprehensions=True,  # Allow comprehensions
+    allow_lambdas=True,         # Allow Lambda
+    allow_classes=False,        # Disallow class definitions
+)
+
+sandbox = SecureSandbox(config)
+result = sandbox.safe_execute(code, max_gas=100)
+```
+
+### Add Custom Modules to Whitelist
+
+```python
+from secure_sandbox import SecurityConfig, DEFAULT_ALLOWED_MODULES
+
+# Extend default module whitelist
+custom_modules = DEFAULT_ALLOWED_MODULES.copy()
+custom_modules.update({
+    'numpy',    # Add numpy
+    'pandas',   # Add pandas
+})
+
+config = SecurityConfig(
+    allowed_modules=custom_modules
+)
+```
+
+## Configuration Details
+
+### SecurityConfig Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `max_gas` | int | 10000 | Maximum Gas quota to prevent infinite loops |
+| `max_recursion_depth` | int | 100 | Maximum recursion depth |
+| `allow_imports` | bool | True | Whether to allow module imports |
+| `allowed_modules` | Set[str] | DEFAULT_ALLOWED_MODULES | Module import whitelist |
+| `ast_whitelist` | Set[str] | AST_WHITELIST | Allowed AST node whitelist |
+| `ast_blacklist` | Set[str] | AST_BLACKLIST | Forbidden AST node blacklist |
+| `allow_dunder_access` | bool | False | Whether to allow magic method access |
+| `allow_private_attrs` | bool | False | Whether to allow private attribute access |
+| `dangerous_attributes` | Set[str] | DANGEROUS_ATTRIBUTES | Dangerous attribute blacklist |
+| `safe_attributes` | Set[str] | SAFE_ATTRIBUTES | Safe attribute whitelist |
+| `allow_comprehensions` | bool | True | Whether to allow comprehensions |
+| `allow_lambdas` | bool | True | Whether to allow Lambda expressions |
+| `allow_classes` | bool | True | Whether to allow class definitions |
+
+### Default Allowed Modules
+
+```
+math        - Mathematical operations
+json        - JSON processing
+datetime    - Date and time
+collections - Advanced data structures
+itertools   - Iterator tools
+functools   - Function tools
+operator    - Operator functions
+typing      - Type hints
+decimal     - High-precision math
+fractions   - Fraction operations
+statistics  - Statistical functions
+array       - Arrays
+copy        - Copy tools
+re          - Regular expressions
+random      - Random numbers
+```
+
+## API Documentation
+
+### `safe_execute(code_str, max_gas, config)`
+
+Convenience function for quick code execution
+
+**Parameters**:
+- `code_str` (str): Code string to execute
+- `max_gas` (int): Maximum Gas quota, default 10000
+- `config` (SecurityConfig, optional): Security configuration
+
+**Returns**:
+```python
+{
+    'success': True,              # Execution success
+    'locals': {...},              # Local variables dictionary
+    'remaining_gas': 9999,        # Remaining Gas
+    'total_checks': 100,          # Total check count
+}
+```
+
+**Exceptions**:
+- `GasLimitExceeded`: Gas quota exhausted
+- `SandboxSecurityError`: Security violation
+- `ASTValidationError`: AST validation failed
+
+## Comparison with Traditional Solutions
+
+| Feature | RestrictedPython | Secure Sandbox |
+|---------|------------------|----------------|
+| CPU DoS Defense | ❌ None | ✅ Gas mechanism |
+| Sandbox Escape Defense | ⚠️ Limited | ✅ Strict interception |
+| Import Control | ❌ None | ✅ Whitelist mechanism |
+| Configurability | ⚠️ Basic | ✅ Fully configurable |
+| Performance Overhead | Low | Medium (10-15%) |
+
+## Security Best Practices
+
+1. **Set reasonable Gas quota**: Based on code complexity, recommend 100-1000
+2. **Limit imported modules**: Only allow necessary modules
+3. **Monitor execution results**: Check remaining_gas and exception logs
+4. **Regular audit**: Check if whitelist needs updating
+5. **Add timeout mechanism**: Combine with signal or threading for dual protection
+
+## Known Limitations
+
+1. **Performance overhead**: Gas checks add ~10-15% overhead
+2. **Feature limitations**: Cannot import dangerous modules or use certain advanced features
+3. **Reflection limitations**: Normal reflection operations are also restricted
+
+## Contributing
+
+Issues and Pull Requests are welcome!
+
+Development environment setup:
+
+```bash
+git clone https://github.com/yourname/secure-sandbox.git
+cd secure-sandbox
+pip install -e ".[dev]"
+pytest tests/
+```
+
+## License
+
+MIT License
+
+## Author
+
+Python Security Architect
+
+## Version History
+
+- **v0.0.1** - Initial version
+  - Implemented Gas mechanism
+  - Implemented AST whitelist validation
+  - Implemented attribute access interception
+  - Implemented Import whitelist control
+  - Fully configurable security policies
+  - Complete test suite