Skip to content

security-deployment.zh-CN.md

Latest commit

 

History

History
122 lines (85 loc) · 8.23 KB

security-deployment.zh-CN.md

File metadata and controls

122 lines (85 loc) · 8.23 KB
Raw

Asteria Analyst 安全与部署说明

本文件是 SECURITY.md 与 部署边界 的中文技术说明，面向本机使用者、维护者和准备发布 GitHub Release 的项目所有者。英文安全政策、当前代码、启动器和安全测试共同定义发布范围；发生差异时先完成核对，再同步文档或实现。

1. 当前支持的使用模型

当前公开版本设计为：

一名受信任的本机使用者
    + Windows 本机文件
    + 127.0.0.1 回环地址
    + 本机存储和可选 AI 提供方

当前公开版本提供本机单用户工具。账户认证、组织管理、租户隔离、对象级授权、私有对象存储、统一审计、限流、生产备份和事件响应由托管服务平台提供。任何公网部署均需完成相应的安全架构与运维设计。

2. 网络模型

事实 含义
源码启动器默认使用 127.0.0.1 前端和后端服务于同一台机器上的本机工作流。
便携版默认在本机端口启动 启动脚本会从 8787 开始寻找可用本机端口，并打开 /analysis。
CORS 默认限定本机 Origin 用于浏览器跨域匹配；用户登录、认证和授权由独立机制提供。
当前 API 没有身份认证层 本机回环监听将访问范围保持在本机使用场景。

共享或公网部署包含以下架构变化，并配套完成安全审查：

  • 将监听地址改为 0.0.0.0、局域网地址或公网地址；
  • 开放防火墙端口、端口转发、内网穿透或隧道；
  • 在反向代理后向多人提供页面或 API；
  • 配置面向共享使用者的 CORS、认证和授权；
  • 把 workspace/storage、%APPDATA%\AsteriaAnalyst 或 /storage 映射为共享文件目录。

若确实要建设共享/公网版本，至少需要独立完成：身份认证、会话与账户生命周期、每用户/每租户授权、私有工件下载、数据隔离、上传控制、恶意文件策略、CSRF/安全头、速率限制、审计日志、密钥托管、AI 数据处理协议、任务隔离和应急响应。

3. 数据、工件和存储

位置或概念 安全分类 处理要求
上传的数据集、历史报告、业务背景 私有本地输入 保留在本机私有目录，Git 与公开 Issue 使用脱敏描述。
settings.json、运行任务、Codex 日志、学习账本 私有运行状态 保存于私有运行目录，供本机服务读取。
public_artifacts/reports 与 /storage/** 本机可引用工件 收录已批准供界面访问的产物，并在交付前复核报告内容。
workspace/storage（源码）或 %APPDATA%\AsteriaAnalyst（便携） 用户数据根目录 应位于当前用户可写、非共享、受系统访问控制保护的位置。
GitHub 仓库与 Release 资产 公开范围 收录源码、测试、启动脚本、无敏感示例、文档和已检查的便携包。

main.py 将 PUBLIC_ARTIFACTS_DIR 挂载到 /storage，供本机界面引用已选工件；完整存储根目录保持私有。发布截图、日志和工件前逐项检查数据与隐私。

4. AI 提供方数据边界

基础文件查看和本地统计可在本机执行，不必配置 API Key。用户主动配置并使用 AI 辅助字段语义、业务路由、报告或修订后，相关字段上下文、业务背景、报告上下文或工作簿/PDF 内容可能发送到其配置的 OpenAI-compatible 提供方。

启用前至少确认：

  1. 你有权让该提供方处理该数据类别；
  2. 个人信息、客户信息、财务、健康、合同或受监管字段是否需要删除、掩码、聚合或抽样；
  3. 提供方的数据区域、保留、访问、审计和合同条款是否满足组织要求；
  4. API Key 用于授权调用；数据传输仍需满足安全与合规要求；
  5. 报告数值和结论使用确定性计算、证据和审阅记录作为依据。

启用 AI 后，公开说明应如实描述数据可能发送到已配置提供方的范围。

5. 密钥与配置保护

配置动作 预期结果
在本机 .env、进程环境或受保护的系统密钥管理中保存密钥。 密钥位于受保护的本机位置，公开文档和浏览器配置使用占位值。
使用 .env.example 作为无密钥模板。 带有真实值的 .env 保留在私有运行环境。
通过 /api/runtime-settings 的掩码摘要核对配置。 API Key 持续保留在受保护的配置中。
为最小必要的 Runtime 工作区设置路径。 Codex 与外部 Skill 在指定工作区内访问文件。

完整变量说明见 配置参考。

6. 高权限本机扩展

| 功能 | 默认状态 | 必要开关 | 适用范围 | | --- | --- | --- | | 外部 Skill/Agent Team 导入、挂载、运行 | 关闭 | ASTERIA_ENABLE_LOCAL_SKILL_INSTALLER=1 | 由本机管理员审阅来源并执行。 | | Codex Runtime API | 关闭 | ASTERIA_ENABLE_CODEX_RUNTIME_API=1 | 在受控本机工作区中使用路径、日志、会话和运行产物。 | | 非沙箱 Codex Runtime | 关闭 | ASTERIA_ALLOW_UNSANDBOXED_CODEX_RUNTIME=1 和相应请求/偏好 | 由可信本机管理员按任务需要启用。 | | HTTP 任意代码执行 | 未作为公开路由发布 | 无 | 公开 main.py 未注册 /api/code/execute；新增执行路由进入独立安全评审。 |

这些开关管理本机高权限能力的启用状态；认证、授权与租户隔离需由独立机制提供。将它们设为 true 表示当前机器的操作者明确选择接受相应风险。

7. 报告、HTML 与正式发布

  • 报告 HTML 预览在隔离语境下查看，并按普通文件内容进行审阅。
  • Analysis Lab、自动分析、调试报告、图表和文件下载服务于探索、诊断与复核；正式管理报告使用完整发布链。
  • 正式 management_report.pdf 依次经过 AI 字段语义映射、业务路由、指标规划、确定性数值执行、证据校验、报告绑定和 FormalPDFReleaseGate。
  • trace、schema 校验、确定性数值、证据校验和门禁放行齐备，且最终质量分达到 90 后，门禁放行正式报告；其他结果保留为调试或复核材料。

详情见 正式报告可置信机制。

8. GitHub 公开发布卫生

在 push、创建 Release、上传 ZIP、发截图或提交 Issue 前，确认公开材料使用以下范围：

  • .env、API Key、Token、密码、私有 Base URL；
  • 客户数据、上传工作簿、报告、修订会话、附件、日志、缓存或本机运行状态；
  • 未获授权的作品集、第三方素材或商业交付物；
  • 显示用户名、绝对路径、内部域名或可识别业务信息的截图；
  • 版本范围、运行模型和实际完成的安全验证记录。

许可证由项目所有者选择并发布。在 LICENSE 发布前，复制、修改和商用权利尚未授予；发布脚本和文档仅执行已确定的许可证策略。

9. 漏洞报告与安全事件

私密安全通道接收漏洞复现步骤、凭据、真实数据、报告、截图和客户信息等敏感材料。仓库所有者配置并验证该通道；仓库页面未显示私密报告渠道时，通过项目所有者公开列出的私密联系方式确认接收方式，再发送最小化、可安全复现的材料。

一份合格的私密报告包含：受影响版本/提交、影响范围、最小复现步骤、预期与实际行为、安全影响和使用脱敏数据的安全 PoC。维护者收到报告后确认接收、评估影响、制定修复与披露计划，并在私密通道处理攻击细节。

10. 本机安全检查单

  1. 服务保持监听 127.0.0.1。
  2. 上传数据和生成工件保存在私有本机目录。
  3. .env、日志、截图和 Git 状态使用脱敏内容。
  4. AI 调用已有数据授权和脱敏判断记录。
  5. 高权限 Runtime、Skill 或非沙箱执行由明确的本机管理员需求启用。
  6. /storage 和数据目录保持本机工件访问用途。
  7. 正式 PDF、实验产物和调试输出具有清晰的状态标识。

需要具体接口行为时参阅 API 参考；准备发布时参阅 发布与运维指南。