Metadata-Version: 2.4
Name: magic-sandbox
Version: 0.1.1
Summary: 占位包：Magic-sandbox 轻量级python沙箱工具（即将推出）
Author-email: wxd123 <wxd123@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/wxd123/magic-sandbox
Classifier: Development Status :: 3 - Alpha
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0.3
Dynamic: license-file

# magic-sandbox
**轻量级、可审计的 Python 沙箱**  
安全执行不可信代码，守住所有危险操作的必经之路。

[![PyPI version](https://badge.fury.io/py/magic-sandbox.svg)](https://badge.fury.io/py/magic-sandbox)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)


## 项目状态

**开发中** - 首个正式版本将于 2026 年 Q3 发布

## 特性

- 🚀 **极轻量**：纯 Python 实现，零外部依赖，毫秒级启动。
- 🛡️ **纵深防御**：AST 静态分析 + 动态桩 + 声明式资源 + 可选子进程隔离。
- 📝 **完整审计**：所有危险操作（文件、网络、子进程、动态库）自动记录日志，不可篡改。
- 🧩 **声明式权限**：第三方代码必须预先声明所需资源（文件路径、网络域名等），越权即拦截。
- 🔁 **互为触发**：每一层防御都不是孤立的，突破 AST 会触发动态桩，攻击动态桩会被 AST 捕获。
- 🧪 **Dry-Run 模式**：在完全隔离的环境中模拟执行，观察行为而不产生真实副作用。

## 适用场景

- AI Agent / LLM 生成的代码执行
- 量化交易策略隔离
- 在线代码评测（Judge）
- 插件系统（IDE、CMS、数据处理平台）
- 低代码平台的自定义脚本
- 任何需要安全运行不可信 Python 代码的场景

## 安装

```bash
pip install magic-sandbox
```

## 安全设计概览

| 防御层 | 技术 | 作用 |
|--------|------|------|
| 静态分析 | AST 扫描 | 禁止字符串拼接、危险属性（`__class__`）、高危函数（`eval`） |
| 动态桩 | 函数入口替换 | 前置校验参数、限流、dry-run 模拟 |
| 审计钩子 | `sys.addaudithook` | 底层不可绕过的监控，记录所有危险调用 |
| 声明式资源 | Manifest 校验 | 最小权限原则，越权即拦截 |
| 子进程隔离 | `subprocess` + `seccomp` | 可选模式，即使逃逸也无法影响主进程 |
| 审计日志 | 结构化 + SQLite | 完整记录攻击路径，防篡改 |

## 示例（待正式版本发布后补充）
> 示例代码将在正式版本发布时补充。

## 代码规范
本项目遵循以下基本原则：

1. 单文件不超过 200 行：超过时请拆分为多个模块
2. 单函数不超过 200 行：超过时请拆分为多个小函数
3. 注释尽量完整：关键逻辑、复杂算法、非显而易见的代码必须有注释说明
4. 如有特殊场景确实需要突破（如纯数据定义文件），可在 PR 中说明。

这些规则旨在保证代码的可读性和可维护性，便于合作，请尽量遵守。

## 针对 AI 辅助工具的提示
本项目使用 AI 辅助开发，请在生成代码时尽量遵守上述代码规范。

## 许可证
MIT License

## 作者
wxd123 - GitHub
