Skip to content

frictionless-security.zh-CN.md

Latest commit

 

History

History
312 lines (246 loc) · 8.12 KB

frictionless-security.zh-CN.md

File metadata and controls

312 lines (246 loc) · 8.12 KB

无摩擦安全：对安装向导零影响

⚠️ 状态：提案 / 路线图

本文档描述提议的实现方法，可能包含假设的命令或配置。 如需了解当前运行时行为，请参见 config-reference.zh-CN.md、operations-runbook.zh-CN.md 和 troubleshooting.zh-CN.md。

核心原则

"安全功能应该像安全气囊 — 存在、有保护作用，且在需要之前不可见。"

设计：静默自动检测

1. 无新的向导步骤（保持 9 步，< 60 秒）

// 向导保持不变
// 安全功能在后台自动检测

pub fn run_wizard() -> Result<Config> {
    // ... 现有 9 步，无更改 ...

    let config = Config {
        // ... 现有字段 ...

        // 新增：自动检测的安全（不在向导中显示）
        security: SecurityConfig::autodetect(),  // 静默！
    };

    config.save().await?;
    Ok(config)
}

2. 自动检测逻辑（首次启动时运行一次）

// src/security/detect.rs

impl SecurityConfig {
    /// 检测可用的沙箱并自动启用
    /// 基于平台 + 可用工具返回智能默认值
    pub fn autodetect() -> Self {
        Self {
            // 沙箱：优先 Landlock（原生），然后 Firejail，然后无
            sandbox: SandboxConfig::autodetect(),

            // 资源限制：始终启用监控
            resources: ResourceLimits::default(),

            // 审计：默认启用，记录到配置目录
            audit: AuditConfig::default(),

            // 其他所有项：安全默认值
            ..SecurityConfig::default()
        }
    }
}

impl SandboxConfig {
    pub fn autodetect() -> Self {
        #[cfg(target_os = \"linux\")]
        {
            // 优先 Landlock（原生，无依赖）
            if Self::probe_landlock() {
                return Self {
                    enabled: true,
                    backend: SandboxBackend::Landlock,
                    ..Self::default()
                };
            }

            // 回退：如果安装了 Firejail 则使用
            if Self::probe_firejail() {
                return Self {
                    enabled: true,
                    backend: SandboxBackend::Firejail,
                    ..Self::default()
                };
            }
        }

        #[cfg(target_os = \"macos\")]
        {
            // 在 macOS 上尝试 Bubblewrap
            if Self::probe_bubblewrap() {
                return Self {
                    enabled: true,
                    backend: SandboxBackend::Bubblewrap,
                    ..Self::default()
                };
            }
        }

        // 回退：禁用（但仍有应用层安全）
        Self {
            enabled: false,
            backend: SandboxBackend::None,
            ..Self::default()
        }
    }

    #[cfg(target_os = \"linux\")]
    fn probe_landlock() -> bool {
        // 尝试创建最小 Landlock 规则集
        // 如果成功，内核支持 Landlock
        landlock::Ruleset::new()
            .set_access_fs(landlock::AccessFS::read_file)
            .add_path(Path::new(\"/tmp\"), landlock::AccessFS::read_file)
            .map(|ruleset| ruleset.restrict_self().is_ok())
            .unwrap_or(false)
    }

    fn probe_firejail() -> bool {
        // 检查 firejail 命令是否存在
        std::process::Command::new(\"firejail\")
            .arg(\"--version\")
            .output()
            .map(|o| o.status.success())
            .unwrap_or(false)
    }
}

3. 首次运行：静默日志

$ zeroclaw agent -m \"hello\"

# 首次运行：静默检测
[INFO] Detecting security features...
[INFO] ✓ Landlock sandbox enabled (kernel 6.2+)
[INFO] ✓ Memory monitoring active (512MB limit)
[INFO] ✓ Audit logging enabled (~/.config/zeroclaw/audit.log)

# 后续运行：安静
$ zeroclaw agent -m \"hello\"
[agent] Thinking...

4. 配置文件：所有默认值隐藏

# ~/.config/zeroclaw/config.toml

# 这些部分不会被写入，除非用户自定义
# [security.sandbox]
# enabled = true  # （默认，自动检测）
# backend = \"landlock\"  # （默认，自动检测）

# [security.resources]
# max_memory_mb = 512  # （默认）

# [security.audit]
# enabled = true  # （默认）

仅当用户更改某些内容时：

[security.sandbox]
enabled = false  # 用户显式禁用

[security.resources]
max_memory_mb = 1024  # 用户提高了限制

5. 高级用户：显式控制

# 检查哪些功能处于活动状态
$ zeroclaw security --status
Security Status:
  ✓ Sandbox: Landlock (Linux kernel 6.2)
  ✓ Memory monitoring: 512MB limit
  ✓ Audit logging: ~/.config/zeroclaw/audit.log
  → 今日已记录 47 个事件

# 显式禁用沙箱（写入配置）
$ zeroclaw config set security.sandbox.enabled false

# 启用特定后端
$ zeroclaw config set security.sandbox.backend firejail

# 调整限制
$ zeroclaw config set security.resources.max_memory_mb 2048

6. 优雅降级

平台 最佳可用 回退 最坏情况
Linux 5.13+ Landlock 无 仅应用层
Linux（任意版本） Firejail Landlock 仅应用层
macOS Bubblewrap 无 仅应用层
Windows 无 - 仅应用层

应用层安全始终存在 — 这是现有的白名单/路径阻止/注入保护，已经很全面。

配置模式扩展

// src/config/schema.rs

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SecurityConfig {
    /// 沙箱配置（未设置则自动检测）
    #[serde(default)]
    pub sandbox: SandboxConfig,

    /// 资源限制（未设置则应用默认值）
    #[serde(default)]
    pub resources: ResourceLimits,

    /// 审计日志（默认启用）
    #[serde(default)]
    pub audit: AuditConfig,
}

impl Default for SecurityConfig {
    fn default() -> Self {
        Self {
            sandbox: SandboxConfig::autodetect(),  // 静默检测！
            resources: ResourceLimits::default(),
            audit: AuditConfig::default(),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SandboxConfig {
    /// 启用沙箱（默认：自动检测）
    #[serde(default)]
    pub enabled: Option<bool>,  // None = 自动检测

    /// 沙箱后端（默认：自动检测）
    #[serde(default)]
    pub backend: SandboxBackend,

    /// 自定义 Firejail 参数（可选）
    #[serde(default)]
    pub firejail_args: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = \"lowercase\")]
pub enum SandboxBackend {
    Auto,       // 自动检测（默认）
    Landlock,   // Linux 内核 LSM
    Firejail,   // 用户空间沙箱
    Bubblewrap, // 用户命名空间
    Docker,     // 容器（重量级）
    None,       // 禁用
}

impl Default for SandboxBackend {
    fn default() -> Self {
        Self::Auto  // 默认始终自动检测
    }
}

用户体验对比

之前（当前）

$ zeroclaw onboard
[1/9] Workspace Setup...
[2/9] AI Provider...
...
[9/9] Workspace Files...
✓ Security: Supervised | workspace-scoped

之后（带无摩擦安全）

$ zeroclaw onboard
[1/9] Workspace Setup...
[2/9] AI Provider...
...
[9/9] Workspace Files...
✓ Security: Supervised | workspace-scoped | Landlock sandbox ✓
# ↑ 仅多了一个词，静默自动检测！

向后兼容性

场景 行为
现有配置 工作不变，新功能选择加入
新安装 自动检测并启用可用的安全功能
无可用沙箱 回退到应用层（仍然安全）
用户禁用 一个配置标志：sandbox.enabled = false

总结

✅ 对向导零影响 — 保持 9 步，< 60 秒 ✅ 无新提示 — 静默自动检测 ✅ 无破坏性变更 — 向后兼容 ✅ 可选择退出 — 显式配置标志 ✅ 状态可见性 — zeroclaw security --status

向导仍然是「通用应用快速安装」 — 安全只是默默地更好了。