--- sidebar_label: "安全概述" title: "安全概述 - CyberGo html | 安全防护总览" description: "CyberGo html 安全防护总览：深度防御三层架构（输入层、处理层、输出层）、MaxInputSize 与 MaxDepth 限制、路径遍历防护、panic 恢复机制、HTML 内容清洗与 HighSecurityConfig 高安全预设应用。" sidebar_position: 1 --- # 安全概述 HTML 库处理的是来自互联网的不可信输入，因此在设计上将安全作为第一优先级。库内置多层独立防护机制，遵循**纵深防御**理念：每一层都假设其他层可能失效，单层被绕过不会导致整体沦陷。本页是安全功能的总览。若你想直接动手配置审计管道或核对上线清单，跳到末尾的[下一步](#下一步)。 ## 深度防御架构库的安全防护分布在三个独立层次，每层都有自己的失败模式与恢复策略： ```text 输入层防护（拒绝前过滤） ├── MaxInputSize 字节级大小上限（默认 50MB） ├── MaxDepth DOM 嵌套深度上限（默认 500，防栈溢出） ├── ProcessingTimeout 单文档处理超时（默认 30s） ├── 路径遍历检测文件路径中的 .. 组件 └── AllowedBaseDir 文件读取沙箱（OS 句柄解析，防 symlink/junction）处理层防护（清洗与取消） ├── HTML 清洗标签 / 属性 / URL / CSS 多维过滤 ├── 协作式 context 取消 ExtractWithContext 响应 ctx.Done() ├── Panic 恢复 recoverPanic 泛型包装，返回 ErrInternalPanic └── Goroutine 泄漏防护 maxTimeoutGoroutines（上限 1000）审计层防护（可观测 + 隔离） ├── AuditSink panic 隔离 SEC-003（审计子系统是 best-effort） ├── 8 种审计事件 blocked_tag/blocked_attr/blocked_url/... └── 原始值 HTML 转义防审计日志在 SIEM 仪表盘中触发 XSS ``` :::tip 为什么强调「独立」纵深防御的价值在于层间无耦合假设。例如即便清洗层漏过某个恶意 URL（处理层失效），输入层的 `MaxInputSize` 仍能挡住超长 payload；即便 AuditSink 自己 panic（审计层失效），`recoverPanic` 仍保证主流程不崩溃。 ::: ## 输入边界防护 ### 输入大小限制默认最大输入 50MB（`DefaultMaxInputSize`），防止内存耗尽攻击。配置上限同时受 `maxConfigInputSize` 约束（同样 50MB），即无法通过配置放大到不安全值： ```go cfg := html.DefaultConfig() cfg.MaxInputSize = 10 * 1024 * 1024 // 收紧到 10MB ``` 文件路径还有一道**预检查**：`Stat` 取得大小后，在 `ReadAll` 将内容载入内存前就拒绝超限文件，关闭「先读完再发现超限」的内存峰值窗口。 ### DOM 深度限制默认最大深度 500（`DefaultMaxDepth`），防止递归嵌套构造的栈溢出炸弹： ```go cfg.MaxDepth = 200 // 更严格 ``` 深度校验采用**迭代式**遍历而非递归，本身不会因输入嵌套过深而爆栈。 ### 处理超时可配置的处理超时，防止恶意 HTML 触发指数级处理时间： ```go cfg.ProcessingTimeout = 10 * time.Second ``` 超时机制通过独立 goroutine + context deadline 实现，并受 `maxTimeoutGoroutines`（1000）上限保护，防止高并发下 goroutine 失控。配合 `ExtractWithContext` 可叠加调用方的取消信号。 ## 内容清洗机制详解清洗功能由 `EnableSanitization`（默认 `true`）控制，对已解析的 DOM 树做就地修改，移除潜在恶意内容。整个流程由 `internal/sanitize.go` 实现，每一步拦截都会写入审计日志。 :::warning 何时关闭清洗仅当输入是**完全可信**的内部数据时才考虑 `EnableSanitization = false`。处理任何来自用户上传、网页抓取、第三方 API 的 HTML 都应保持开启。 ::: ### 被移除的标签以下标签连同其子树被整段移除： | 标签 | 移除原因 | |------|----------| | `