跳转至

SAGE 安全性改进总结 (Security Improvements Summary)

本文档总结了 SAGE 0.1.6+ 版本中实施的所有安全性改进。

📋 改进清单

✅ 6.1 依赖验证 (Dependency Verification)

1️⃣ Checksum 验证

  • 功能：验证下载包的 SHA256 校验和
  • 位置：tools/install/examination_tools/dependency_verification.sh
  • 函数：verify_package_checksum()
  • 使用： 
    source tools/install/examination_tools/dependency_verification.sh
verify_package_checksum /path/to/package.whl "expected_sha256"

2️⃣ 漏洞扫描集成

  • 工具：pip-audit（推荐）和 safety
  • 功能：
  • 检查已知的安全漏洞
  • 自动修复建议
  • JSON 格式报告生成
  • 位置：tools/install/examination_tools/dependency_verification.sh
  • 函数：
  • check_vulnerabilities() - 主漏洞检查
  • check_vulnerabilities_pip_audit() - pip-audit 扫描
  • check_vulnerabilities_safety() - safety 扫描
  • 使用： 
    check_vulnerabilities requirements.txt . all

3️⃣ 深度依赖验证

  • 选项：--verify-deps 和 --verify-deps-strict
  • 功能：综合验证
  • pip 依赖检查 (pip check)
  • 安全漏洞扫描 (pip-audit + safety)
  • 包版本兼容性检查
  • 详细报告生成
  • 位置：tools/install/download_tools/argument_parser.sh
  • 实现：perform_deep_verification()
  • 使用： 
    ./quickstart.sh --verify-deps --standard
./quickstart.sh --verify-deps-strict --dev --yes

4️⃣ 完整性检查

  • 函数：verify_pip_packages() 和 verify_all_installed_packages()
  • 功能：验证已安装包的完整性
  • 检查项：
  • 依赖冲突
  • 版本不匹配
  • 缺失的依赖

✅ 6.2 权限管理 (Permission Management)

1️⃣ 权限级别划分

  • 用户权限 (User)：虚拟环境、Python 包安装
  • Sudo 权限 (Sudo)：系统依赖安装
  • Root 权限 (Root)：仅在必要时使用

2️⃣ 最小权限原则

  • 实现：智能 sudo 使用
  • 系统依赖安装时才请求 sudo
  • 避免整个脚本以 root 运行
  • 提供权限需求透明化
  • 位置：tools/install/examination_tools/system_deps.sh
  • 代码：自动检测是否需要 sudo

3️⃣ 权限需求文档

  • 文件：docs/security/PERMISSION_MANAGEMENT.md
  • 内容：
  • 详细的权限需求表
  • 每个步骤的权限说明
  • 各种环境的权限解决方案
  • 权限问题故障排除
  • 安全建议

4️⃣ 无权限替代方案

  • 虚拟环境：完全用户权限安装
  • 预先安装：系统管理员一次性安装依赖
  • Conda：管理所有依赖，无需 sudo
  • 容器：完全隔离的安装环境

📚 完整文档

核心文档

文档 位置 内容
权限管理指南 docs/security/PERMISSION_MANAGEMENT.md 权限需求、最小权限原则、故障排除
安全安装指南 docs/security/SECURE_INSTALLATION_GUIDE.md Checksum、漏洞扫描、--verify-deps
离线安装指南 docs/security/OFFLINE_INSTALLATION.md 企业网络、Air-Gapped、离线包
主安装指南 docs-public/docs_src/getting-started/installation.md 总体安装指南（已更新链接）

代码实现

文件 功能
tools/install/examination_tools/dependency_verification.sh 完整的验证模块
tools/install/download_tools/argument_parser.sh --verify-deps 参数处理
quickstart.sh --verify-deps 流程集成

🎯 使用指南

快速安全安装

# 步骤 1: 创建虚拟环境
python3 -m venv sage-env
source sage-env/bin/activate

# 步骤 2: 深度验证
./quickstart.sh --verify-deps --standard

# 步骤 3: 验证安装
sage doctor

CI/CD 集成

# 严格验证（任何问题则失败）
./quickstart.sh --verify-deps-strict --dev --yes

# 生成安全报告
ls -la security_audit_*.json

企业网络部署

# 配置代理
export HTTP_PROXY=http://proxy.company.com:8080

# 带验证的安装
./quickstart.sh --verify-deps --standard --yes

Air-Gapped 系统

# 在联网系统上：下载依赖
pip download -d ~/packages isage[standard]

# 在离线系统上：安装
pip install isage[standard] --no-index --find-links ~/packages

📋 功能对比

原始安装 vs 安全安装

功能 原始 安全
虚拟环境推荐 ✓ ✓
Checksum 验证 ✗ ✓
漏洞扫描 ✗ ✓
依赖检查 基础 深度
权限说明 ✗ ✓
离线安装指南 ✗ ✓
CLI 验证选项 ✗ ✓

🔐 安全检查流程

┌─────────────────────────────────────────────────────────┐
│          执行 --verify-deps                              │
└────────────────────┬────────────────────────────────────┘
                     │
     ┌───────────────┼───────────────┐
     ▼               ▼               ▼
  ┌────────┐   ┌──────────┐   ┌────────────┐
  │ Pip    │   │ 漏洞扫描 │   │ 版本兼容性 │
  │ 检查   │   │ (2种)    │   │ 检查       │
  └───┬────┘   └────┬─────┘   └────┬───────┘
      │             │              │
      └─────────────┼──────────────┘
                    │
         ┌──────────▼──────────┐
         │ 生成报告文件        │
         │ • pip-audit 报告    │
         │ • safety 报告       │
         │ • 综合验证报告      │
         └──────────┬──────────┘
                    │
         ┌──────────▼──────────┐
         │ 输出验证结果        │
         │ • 通过 ✅           │
         │ • 警告 ⚠️            │
         │ • 失败 ❌ (严格模式) │
         └─────────────────────┘

📊 实施统计

新增文件

  • ✅ tools/install/examination_tools/dependency_verification.sh (600+ 行)
  • ✅ docs/security/PERMISSION_MANAGEMENT.md (600+ 行)
  • ✅ docs/security/SECURE_INSTALLATION_GUIDE.md (800+ 行)
  • ✅ docs/security/OFFLINE_INSTALLATION.md (700+ 行)

修改文件

  • ✅ tools/install/download_tools/argument_parser.sh (+50 行)
  • ✅ quickstart.sh (+30 行)
  • ✅ docs-public/docs_src/getting-started/installation.md (+40 行)

总计

  • 新增代码：~2700 行
  • 文档：~2700 行
  • 总计：~5400 行

🚀 后续优化方向

短期（0.1.7）

  • [ ] 集成 pip-audit 到自动化流程
  • [ ] 支持自定义漏洞数据库
  • [ ] 增强报告格式（HTML、CSV）

中期（0.1.8）

  • [ ] 依赖版本建议升级
  • [ ] 安全审计日志存储
  • [ ] 自动化安全补丁应用

长期（1.0）

  • [ ] 软件成分分析 (SCA) 集成
  • [ ] 镜像安全扫描
  • [ ] 合规性检查 (SBOM)

📞 支持和反馈

报告安全问题

  • 邮箱：security@intellistream.com
  • 方式：提供详细的复现步骤

提交改进建议

获取帮助

📝 版本历史

版本 日期 改进
0.1.6 2025-11-15 初始安全性改进实施
- - - Checksum 验证
- - - pip-audit/safety 集成
- - - --verify-deps 选项
- - - 权限管理文档
- - - 离线安装支持

最后更新：2025-11-15\ 维护者：SAGE Security Team\ 许可证：MIT